From 2340a1a23bae62d2a461a57deb653cad6383a9a9 Mon Sep 17 00:00:00 2001 From: Josh Lind Date: Wed, 24 May 2023 16:16:17 -0400 Subject: [PATCH 001/200] [Aptos Data Client] Split up tests. --- state-sync/aptos-data-client/src/tests.rs | 1570 ----------------- .../aptos-data-client/src/tests/advertise.rs | 159 ++ .../src/tests/compression.rs | 194 ++ .../aptos-data-client/src/tests/mock.rs | 172 ++ state-sync/aptos-data-client/src/tests/mod.rs | 10 + .../aptos-data-client/src/tests/peers.rs | 339 ++++ .../aptos-data-client/src/tests/poller.rs | 413 +++++ .../aptos-data-client/src/tests/priority.rs | 322 ++++ .../aptos-data-client/src/tests/utils.rs | 43 + 9 files changed, 1652 insertions(+), 1570 deletions(-) delete mode 100644 state-sync/aptos-data-client/src/tests.rs create mode 100644 state-sync/aptos-data-client/src/tests/advertise.rs create mode 100644 state-sync/aptos-data-client/src/tests/compression.rs create mode 100644 state-sync/aptos-data-client/src/tests/mock.rs create mode 100644 state-sync/aptos-data-client/src/tests/mod.rs create mode 100644 state-sync/aptos-data-client/src/tests/peers.rs create mode 100644 state-sync/aptos-data-client/src/tests/poller.rs create mode 100644 state-sync/aptos-data-client/src/tests/priority.rs create mode 100644 state-sync/aptos-data-client/src/tests/utils.rs diff --git a/state-sync/aptos-data-client/src/tests.rs b/state-sync/aptos-data-client/src/tests.rs deleted file mode 100644 index c5c572320bc14..0000000000000 --- a/state-sync/aptos-data-client/src/tests.rs +++ /dev/null @@ -1,1570 +0,0 @@ -// Copyright © Aptos Foundation -// SPDX-License-Identifier: Apache-2.0 - -use crate::{ - client::AptosDataClient, - error::Error, - interface::AptosDataClientInterface, - peer_states::calculate_optimal_chunk_sizes, - poller::{poll_peer, DataSummaryPoller}, -}; -use aptos_channels::{aptos_channel, message_queues::QueueStyle}; -use aptos_config::{ - config::{AptosDataClientConfig, BaseConfig, RoleType}, - network_id::{NetworkId, PeerNetworkId}, -}; -use aptos_crypto::HashValue; -use aptos_netcore::transport::ConnectionOrigin; -use aptos_network::{ - application::{interface::NetworkClient, metadata::ConnectionState, storage::PeersAndMetadata}, - peer_manager::{ConnectionRequestSender, PeerManagerRequest, PeerManagerRequestSender}, - protocols::{ - network::{NetworkSender, NewNetworkSender}, - wire::handshake::v1::ProtocolId, - }, - transport::ConnectionMetadata, -}; -use aptos_storage_service_client::StorageServiceClient; -use aptos_storage_service_server::network::{NetworkRequest, ResponseSender}; -use aptos_storage_service_types::{ - requests::{ - DataRequest, NewTransactionOutputsWithProofRequest, NewTransactionsWithProofRequest, - StorageServiceRequest, TransactionOutputsWithProofRequest, TransactionsWithProofRequest, - }, - responses::{ - CompleteDataRange, DataResponse, DataSummary, ProtocolMetadata, StorageServerSummary, - StorageServiceResponse, OPTIMISTIC_FETCH_VERSION_DELTA, - }, - StorageServiceError, StorageServiceMessage, -}; -use aptos_time_service::{MockTimeService, TimeService}; -use aptos_types::{ - aggregate_signature::AggregateSignature, - block_info::BlockInfo, - ledger_info::{LedgerInfo, LedgerInfoWithSignatures}, - transaction::{TransactionListWithProof, Version}, - PeerId, -}; -use claims::{assert_err, assert_matches, assert_none}; -use futures::StreamExt; -use maplit::hashmap; -use std::{sync::Arc, time::Duration}; - -fn mock_ledger_info(version: Version) -> LedgerInfoWithSignatures { - LedgerInfoWithSignatures::new( - LedgerInfo::new( - BlockInfo::new(0, 0, HashValue::zero(), HashValue::zero(), version, 0, None), - HashValue::zero(), - ), - AggregateSignature::empty(), - ) -} - -fn mock_storage_summary(version: Version) -> StorageServerSummary { - StorageServerSummary { - protocol_metadata: ProtocolMetadata { - max_epoch_chunk_size: 1000, - max_state_chunk_size: 1000, - max_transaction_chunk_size: 1000, - max_transaction_output_chunk_size: 1000, - }, - data_summary: DataSummary { - synced_ledger_info: Some(mock_ledger_info(version)), - epoch_ending_ledger_infos: None, - transactions: Some(CompleteDataRange::new(0, version).unwrap()), - transaction_outputs: Some(CompleteDataRange::new(0, version).unwrap()), - states: None, - }, - } -} - -struct MockNetwork { - network_id: NetworkId, - peer_mgr_reqs_rx: aptos_channel::Receiver<(PeerId, ProtocolId), PeerManagerRequest>, - peers_and_metadata: Arc, -} - -impl MockNetwork { - fn new( - base_config: Option, - data_client_config: Option, - networks: Option>, - ) -> (Self, MockTimeService, AptosDataClient, DataSummaryPoller) { - // Setup the request managers - let queue_cfg = aptos_channel::Config::new(10).queue_style(QueueStyle::FIFO); - let (peer_mgr_reqs_tx, peer_mgr_reqs_rx) = queue_cfg.build(); - let (connection_reqs_tx, _connection_reqs_rx) = queue_cfg.build(); - - // Setup the network client - let network_sender = NetworkSender::new( - PeerManagerRequestSender::new(peer_mgr_reqs_tx), - ConnectionRequestSender::new(connection_reqs_tx), - ); - let networks = networks - .unwrap_or_else(|| vec![NetworkId::Validator, NetworkId::Vfn, NetworkId::Public]); - let peers_and_metadata = PeersAndMetadata::new(&networks); - let client_network_id = NetworkId::Validator; - let network_client = NetworkClient::new( - vec![], - vec![ProtocolId::StorageServiceRpc], - hashmap! { - client_network_id => network_sender}, - peers_and_metadata.clone(), - ); - - // Create a storage service client - let storage_service_client = StorageServiceClient::new(network_client); - - // Create an aptos data client - let mock_time = TimeService::mock(); - let base_config = base_config.unwrap_or_default(); - let data_client_config = data_client_config.unwrap_or_default(); - let (client, poller) = AptosDataClient::new( - data_client_config, - base_config, - mock_time.clone(), - storage_service_client, - None, - ); - - // Create the mock network - let mock_network = Self { - network_id: client_network_id, - peer_mgr_reqs_rx, - peers_and_metadata, - }; - - (mock_network, mock_time.into_mock(), client, poller) - } - - /// Add a new peer to the network peer DB - fn add_peer(&mut self, priority: bool) -> PeerNetworkId { - // Get the network id - let network_id = if priority { - NetworkId::Validator - } else { - NetworkId::Public - }; - self.add_peer_with_network_id(network_id, false) - } - - /// Add a new peer to the network peer DB with the specified network - fn add_peer_with_network_id( - &mut self, - network_id: NetworkId, - outbound_connection: bool, - ) -> PeerNetworkId { - // Create a new peer - let peer_id = PeerId::random(); - let peer_network_id = PeerNetworkId::new(network_id, peer_id); - - // Create and save a new connection metadata - let mut connection_metadata = ConnectionMetadata::mock(peer_id); - connection_metadata.origin = if outbound_connection { - ConnectionOrigin::Outbound - } else { - ConnectionOrigin::Inbound - }; - connection_metadata - .application_protocols - .insert(ProtocolId::StorageServiceRpc); - self.peers_and_metadata - .insert_connection_metadata(peer_network_id, connection_metadata) - .unwrap(); - - // Return the new peer - peer_network_id - } - - /// Disconnects the peer in the network peer DB - fn disconnect_peer(&mut self, peer: PeerNetworkId) { - self.update_peer_state(peer, ConnectionState::Disconnected); - } - - /// Reconnects the peer in the network peer DB - fn reconnect_peer(&mut self, peer: PeerNetworkId) { - self.update_peer_state(peer, ConnectionState::Connected); - } - - /// Updates the state of the given peer - - fn update_peer_state(&mut self, peer: PeerNetworkId, state: ConnectionState) { - self.peers_and_metadata - .update_connection_state(peer, state) - .unwrap(); - } - - /// Get the next request sent from the client. - async fn next_request(&mut self) -> Option { - match self.peer_mgr_reqs_rx.next().await { - Some(PeerManagerRequest::SendRpc(peer_id, network_request)) => { - let peer_network_id = PeerNetworkId::new(self.network_id, peer_id); - let protocol_id = network_request.protocol_id; - let data = network_request.data; - let res_tx = network_request.res_tx; - - let message: StorageServiceMessage = bcs::from_bytes(data.as_ref()).unwrap(); - let storage_service_request = match message { - StorageServiceMessage::Request(request) => request, - _ => panic!("unexpected: {:?}", message), - }; - let response_sender = ResponseSender::new(res_tx); - - Some(NetworkRequest { - peer_network_id, - protocol_id, - storage_service_request, - response_sender, - }) - }, - Some(PeerManagerRequest::SendDirectSend(_, _)) => panic!("Unexpected direct send msg"), - None => None, - } - } -} - -#[tokio::test] -async fn request_works_only_when_data_available() { - ::aptos_logger::Logger::init_for_testing(); - let (mut mock_network, mock_time, client, poller) = MockNetwork::new(None, None, None); - - tokio::spawn(poller.start_poller()); - - // This request should fail because no peers are currently connected - let request_timeout = client.get_response_timeout_ms(); - let error = client - .get_transactions_with_proof(100, 50, 100, false, request_timeout) - .await - .unwrap_err(); - assert_matches!(error, Error::DataIsUnavailable(_)); - - // Add a connected peer - let expected_peer = mock_network.add_peer(true); - - // Requesting some txns now will still fail since no peers are advertising - // availability for the desired range. - let error = client - .get_transactions_with_proof(100, 50, 100, false, request_timeout) - .await - .unwrap_err(); - assert_matches!(error, Error::DataIsUnavailable(_)); - - // Advance time so the poller sends a data summary request - tokio::task::yield_now().await; - mock_time.advance_async(Duration::from_millis(1_000)).await; - - // Receive their request and fulfill it - let network_request = mock_network.next_request().await.unwrap(); - assert_eq!(network_request.peer_network_id, expected_peer); - assert_eq!(network_request.protocol_id, ProtocolId::StorageServiceRpc); - assert!(network_request.storage_service_request.use_compression); - assert_matches!( - network_request.storage_service_request.data_request, - DataRequest::GetStorageServerSummary - ); - - let summary = mock_storage_summary(200); - let data_response = DataResponse::StorageServerSummary(summary); - network_request - .response_sender - .send(Ok(StorageServiceResponse::new(data_response, true).unwrap())); - - // Let the poller finish processing the response - tokio::task::yield_now().await; - - // Handle the client's transactions request - tokio::spawn(async move { - let network_request = mock_network.next_request().await.unwrap(); - - assert_eq!(network_request.peer_network_id, expected_peer); - assert_eq!(network_request.protocol_id, ProtocolId::StorageServiceRpc); - assert!(network_request.storage_service_request.use_compression); - assert_matches!( - network_request.storage_service_request.data_request, - DataRequest::GetTransactionsWithProof(TransactionsWithProofRequest { - start_version: 50, - end_version: 100, - proof_version: 100, - include_events: false, - }) - ); - - let data_response = - DataResponse::TransactionsWithProof(TransactionListWithProof::new_empty()); - network_request - .response_sender - .send(Ok(StorageServiceResponse::new(data_response, true).unwrap())); - }); - - // The client's request should succeed since a peer finally has advertised - // data for this range. - let response = client - .get_transactions_with_proof(100, 50, 100, false, request_timeout) - .await - .unwrap(); - assert_eq!(response.payload, TransactionListWithProof::new_empty()); -} - -#[tokio::test] -async fn fetch_peers_frequency() { - ::aptos_logger::Logger::init_for_testing(); - let (mut mock_network, _, client, poller) = MockNetwork::new(None, None, None); - - // Add regular peer 1 and 2 - let _regular_peer_1 = mock_network.add_peer(false); - let _regular_peer_2 = mock_network.add_peer(false); - - // Set `always_poll` to true and fetch the regular peers multiple times. Ensure - // that for each fetch we receive a peer. - let num_fetches = 20; - for _ in 0..num_fetches { - let peer = poller.fetch_regular_peer(true).unwrap(); - client.in_flight_request_complete(&peer); - } - - // Set `always_poll` to false and fetch the regular peers multiple times - let mut regular_peer_count = 0; - for _ in 0..num_fetches { - if let Some(peer) = poller.fetch_regular_peer(false) { - regular_peer_count += 1; - client.in_flight_request_complete(&peer); - } - } - - // Verify we received regular peers at a reduced frequency - assert!(regular_peer_count < num_fetches); - - // Add priority peer 1 and 2 - let _priority_peer_1 = mock_network.add_peer(true); - let _priority_peer_2 = mock_network.add_peer(true); - - // Fetch the prioritized peers multiple times. Ensure that for - // each fetch we receive a peer. - for _ in 0..num_fetches { - let peer = poller.try_fetch_peer(true).unwrap(); - client.in_flight_request_complete(&peer); - } -} - -#[tokio::test] -async fn fetch_peers_ordering() { - ::aptos_logger::Logger::init_for_testing(); - let (mut mock_network, _, client, _) = MockNetwork::new(None, None, None); - - // Ensure the properties hold for both priority and non-priority peers - for is_priority_peer in [true, false] { - // Add peer 1 - let peer_1 = mock_network.add_peer(is_priority_peer); - - // Request the next peer to poll and verify that we get peer 1 - for _ in 0..3 { - let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - assert_eq!(peer_to_poll, peer_1); - client.in_flight_request_complete(&peer_to_poll); - } - - // Add peer 2 - let peer_2 = mock_network.add_peer(is_priority_peer); - - // Request the next peer and verify we get either peer - let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - assert!(peer_to_poll == peer_1 || peer_to_poll == peer_2); - client.in_flight_request_complete(&peer_to_poll); - - // Request the next peer again, but don't mark the poll as complete - let peer_to_poll_1 = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - - // Request another peer again and verify that it's different to the previous peer - let peer_to_poll_2 = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - assert_ne!(peer_to_poll_1, peer_to_poll_2); - - // Neither poll has completed (they're both in-flight), so make another request - // and verify we get no peers. - assert_none!(fetch_peer_to_poll(client.clone(), is_priority_peer).unwrap()); - - // Add peer 3 - let peer_3 = mock_network.add_peer(is_priority_peer); - - // Request another peer again and verify it's peer_3 - let peer_to_poll_3 = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - assert_eq!(peer_to_poll_3, peer_3); - - // Mark the second poll as completed - client.in_flight_request_complete(&peer_to_poll_2); - - // Make another request and verify we get peer 2 now (as it was ready) - let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - assert_eq!(peer_to_poll, peer_to_poll_2); - - // Mark the first poll as completed - client.in_flight_request_complete(&peer_to_poll_1); - - // Make another request and verify we get peer 1 now - let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - assert_eq!(peer_to_poll, peer_to_poll_1); - - // Mark the third poll as completed - client.in_flight_request_complete(&peer_to_poll_3); - - // Make another request and verify we get peer 3 now - let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - assert_eq!(peer_to_poll, peer_to_poll_3); - client.in_flight_request_complete(&peer_to_poll_3); - } -} - -#[tokio::test] -async fn fetch_peers_disconnect() { - ::aptos_logger::Logger::init_for_testing(); - let (mut mock_network, _, client, _) = MockNetwork::new(None, None, None); - - // Ensure the properties hold for both priority and non-priority peers - for is_priority_peer in [true, false] { - // Request the next peer to poll and verify we have no peers - assert_matches!( - fetch_peer_to_poll(client.clone(), is_priority_peer), - Err(Error::DataIsUnavailable(_)) - ); - - // Add peer 1 - let peer_1 = mock_network.add_peer(is_priority_peer); - - // Request the next peer to poll and verify it's peer 1 - let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - assert_eq!(peer_to_poll, peer_1); - client.in_flight_request_complete(&peer_to_poll); - - // Add peer 2 and disconnect peer 1 - let peer_2 = mock_network.add_peer(is_priority_peer); - mock_network.disconnect_peer(peer_1); - - // Request the next peer to poll and verify it's peer 2 - let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - assert_eq!(peer_to_poll, peer_2); - client.in_flight_request_complete(&peer_to_poll); - - // Disconnect peer 2 - mock_network.disconnect_peer(peer_2); - - // Request the next peer to poll and verify an error is returned because - // there are no connected peers. - assert_matches!( - fetch_peer_to_poll(client.clone(), is_priority_peer), - Err(Error::DataIsUnavailable(_)) - ); - - // Add peer 3 - let peer_3 = mock_network.add_peer(is_priority_peer); - - // Request the next peer to poll and verify it's peer 3 - let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - assert_eq!(peer_to_poll, peer_3); - client.in_flight_request_complete(&peer_to_poll); - - // Disconnect peer 3 - mock_network.disconnect_peer(peer_3); - - // Request the next peer to poll and verify an error is returned because - // there are no connected peers. - assert_matches!( - fetch_peer_to_poll(client.clone(), is_priority_peer), - Err(Error::DataIsUnavailable(_)) - ); - } -} - -#[tokio::test] -async fn fetch_peers_reconnect() { - ::aptos_logger::Logger::init_for_testing(); - let (mut mock_network, _, client, _) = MockNetwork::new(None, None, None); - - // Ensure the properties hold for both priority and non-priority peers - for is_priority_peer in [true, false] { - // Request the next peer to poll and verify we have no peers - assert_matches!( - fetch_peer_to_poll(client.clone(), is_priority_peer), - Err(Error::DataIsUnavailable(_)) - ); - - // Add peer 1 - let peer_1 = mock_network.add_peer(is_priority_peer); - - // Request the next peer to poll and verify it's peer 1 - let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - assert_eq!(peer_to_poll, peer_1); - client.in_flight_request_complete(&peer_to_poll); - - // Add peer 2 and disconnect peer 1 - let peer_2 = mock_network.add_peer(is_priority_peer); - mock_network.disconnect_peer(peer_1); - - // Request the next peer to poll and verify it's peer 2 - let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - assert_eq!(peer_to_poll, peer_2); - client.in_flight_request_complete(&peer_to_poll); - - // Disconnect peer 2 and reconnect peer 1 - mock_network.disconnect_peer(peer_2); - mock_network.reconnect_peer(peer_1); - - // Request the next peer to poll and verify it's peer 1 - let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - assert_eq!(peer_to_poll, peer_1); - - // Reconnect peer 2 - mock_network.reconnect_peer(peer_2); - - // Request the next peer to poll several times and verify it's peer 2 - // (the in-flight request for peer 1 has yet to complete). - for _ in 0..3 { - let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - assert_eq!(peer_to_poll, peer_2); - client.in_flight_request_complete(&peer_to_poll); - } - - // Disconnect peer 2 and mark peer 1's in-flight request as complete - mock_network.disconnect_peer(peer_2); - client.in_flight_request_complete(&peer_1); - - // Request the next peer to poll several times and verify it's peer 1 - for _ in 0..3 { - let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - assert_eq!(peer_to_poll, peer_1); - client.in_flight_request_complete(&peer_to_poll); - } - - // Disconnect peer 1 - mock_network.disconnect_peer(peer_1); - - // Request the next peer to poll and verify an error is returned because - // there are no connected peers. - assert_matches!( - fetch_peer_to_poll(client.clone(), is_priority_peer), - Err(Error::DataIsUnavailable(_)) - ); - } -} - -#[tokio::test] -async fn fetch_peers_max_in_flight() { - ::aptos_logger::Logger::init_for_testing(); - - // Create a data client with max in-flight requests of 2 - let data_client_config = AptosDataClientConfig { - max_num_in_flight_priority_polls: 2, - max_num_in_flight_regular_polls: 2, - ..Default::default() - }; - let (mut mock_network, _, client, _) = MockNetwork::new(None, Some(data_client_config), None); - - // Ensure the properties hold for both priority and non-priority peers - for is_priority_peer in [true, false] { - // Add peer 1 - let peer_1 = mock_network.add_peer(is_priority_peer); - - // Request the next peer to poll and verify it's peer 1 - let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - assert_eq!(peer_to_poll, peer_1); - - // Add peer 2 - let peer_2 = mock_network.add_peer(is_priority_peer); - - // Request the next peer to poll and verify it's peer 2 (peer 1's in-flight - // request has not yet completed). - let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - assert_eq!(peer_to_poll, peer_2); - - // Add peer 3 - let peer_3 = mock_network.add_peer(is_priority_peer); - - // Request the next peer to poll and verify it's empty (we already have - // the maximum number of in-flight requests). - assert_none!(fetch_peer_to_poll(client.clone(), is_priority_peer).unwrap()); - - // Mark peer 2's in-flight request as complete - client.in_flight_request_complete(&peer_2); - - // Request the next peer to poll and verify it's either peer 2 or peer 3 - let peer_to_poll_1 = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - assert!(peer_to_poll_1 == peer_2 || peer_to_poll_1 == peer_3); - - // Request the next peer to poll and verify it's empty (we already have - // the maximum number of in-flight requests). - assert_none!(fetch_peer_to_poll(client.clone(), is_priority_peer).unwrap()); - - // Mark peer 1's in-flight request as complete - client.in_flight_request_complete(&peer_1); - - // Request the next peer to poll and verify it's not the peer that already - // has an in-flight request. - let peer_to_poll_2 = fetch_peer_to_poll(client.clone(), is_priority_peer) - .unwrap() - .unwrap(); - assert_ne!(peer_to_poll_1, peer_to_poll_2); - } -} - -#[tokio::test(flavor = "multi_thread")] -async fn in_flight_error_handling() { - ::aptos_logger::Logger::init_for_testing(); - - // Create a data client with max in-flight requests of 1 - let data_client_config = AptosDataClientConfig { - max_num_in_flight_priority_polls: 1, - max_num_in_flight_regular_polls: 1, - ..Default::default() - }; - let (mut mock_network, _, client, _) = MockNetwork::new(None, Some(data_client_config), None); - - // Verify we have no in-flight polls - let num_in_flight_polls = get_num_in_flight_polls(client.clone(), true); - assert_eq!(num_in_flight_polls, 0); - - // Add a peer - let peer = mock_network.add_peer(true); - - // Poll the peer - client.in_flight_request_started(&peer); - let handle = poll_peer(client.clone(), peer, None); - - // Respond to the peer poll with an error - if let Some(network_request) = mock_network.next_request().await { - network_request - .response_sender - .send(Err(StorageServiceError::InternalError( - "An unexpected error occurred!".into(), - ))); - } - - // Wait for the poller to complete - handle.await.unwrap(); - - // Verify we have no in-flight polls - let num_in_flight_polls = get_num_in_flight_polls(client.clone(), true); - assert_eq!(num_in_flight_polls, 0); -} - -#[tokio::test] -async fn prioritized_peer_request_selection() { - ::aptos_logger::Logger::init_for_testing(); - let (mut mock_network, _, client, _) = MockNetwork::new(None, None, None); - - // Ensure the properties hold for storage summary and version requests - let storage_summary_request = DataRequest::GetStorageServerSummary; - let get_version_request = DataRequest::GetServerProtocolVersion; - for data_request in [storage_summary_request, get_version_request] { - let storage_request = StorageServiceRequest::new(data_request, true); - - // Ensure no peers can service the request (we have no connections) - assert_matches!( - client.choose_peer_for_request(&storage_request), - Err(Error::DataIsUnavailable(_)) - ); - - // Add a regular peer and verify the peer is selected as the recipient - let regular_peer_1 = mock_network.add_peer(false); - assert_eq!( - client.choose_peer_for_request(&storage_request), - Ok(regular_peer_1) - ); - - // Add a priority peer and verify the peer is selected as the recipient - let priority_peer_1 = mock_network.add_peer(true); - assert_eq!( - client.choose_peer_for_request(&storage_request), - Ok(priority_peer_1) - ); - - // Disconnect the priority peer and verify the regular peer is now chosen - mock_network.disconnect_peer(priority_peer_1); - assert_eq!( - client.choose_peer_for_request(&storage_request), - Ok(regular_peer_1) - ); - - // Connect a new priority peer and verify it is now selected - let priority_peer_2 = mock_network.add_peer(true); - assert_eq!( - client.choose_peer_for_request(&storage_request), - Ok(priority_peer_2) - ); - - // Disconnect the priority peer and verify the regular peer is again chosen - mock_network.disconnect_peer(priority_peer_2); - assert_eq!( - client.choose_peer_for_request(&storage_request), - Ok(regular_peer_1) - ); - - // Disconnect the regular peer so that we no longer have any connections - mock_network.disconnect_peer(regular_peer_1); - } -} - -#[tokio::test] -async fn prioritized_peer_subscription_selection() { - ::aptos_logger::Logger::init_for_testing(); - let (mut mock_network, _, client, _) = MockNetwork::new(None, None, None); - - // Create test data - let known_version = 10000000; - let known_epoch = 10; - - // Ensure the properties hold for both subscription requests - let new_transactions_request = - DataRequest::GetNewTransactionsWithProof(NewTransactionsWithProofRequest { - known_version, - known_epoch, - include_events: false, - }); - let new_outputs_request = - DataRequest::GetNewTransactionOutputsWithProof(NewTransactionOutputsWithProofRequest { - known_version, - known_epoch, - }); - for data_request in [new_transactions_request, new_outputs_request] { - let storage_request = StorageServiceRequest::new(data_request, true); - - // Ensure no peers can service the request (we have no connections) - assert_matches!( - client.choose_peer_for_request(&storage_request), - Err(Error::DataIsUnavailable(_)) - ); - - // Add a regular peer and verify the peer cannot support the request - let regular_peer_1 = mock_network.add_peer(false); - assert_matches!( - client.choose_peer_for_request(&storage_request), - Err(Error::DataIsUnavailable(_)) - ); - - // Advertise the data for the regular peer and verify it is now selected - client.update_summary(regular_peer_1, mock_storage_summary(known_version)); - assert_eq!( - client.choose_peer_for_request(&storage_request), - Ok(regular_peer_1) - ); - - // Add a priority peer and verify the regular peer is selected - let priority_peer_1 = mock_network.add_peer(true); - assert_eq!( - client.choose_peer_for_request(&storage_request), - Ok(regular_peer_1) - ); - - // Advertise the data for the priority peer and verify it is now selected - client.update_summary(priority_peer_1, mock_storage_summary(known_version)); - assert_eq!( - client.choose_peer_for_request(&storage_request), - Ok(priority_peer_1) - ); - - // Update the priority peer to be too far behind and verify it is not selected - client.update_summary( - priority_peer_1, - mock_storage_summary(known_version - OPTIMISTIC_FETCH_VERSION_DELTA), - ); - assert_eq!( - client.choose_peer_for_request(&storage_request), - Ok(regular_peer_1) - ); - - // Update the regular peer to be too far behind and verify neither is selected - client.update_summary( - regular_peer_1, - mock_storage_summary(known_version - (OPTIMISTIC_FETCH_VERSION_DELTA * 2)), - ); - assert_matches!( - client.choose_peer_for_request(&storage_request), - Err(Error::DataIsUnavailable(_)) - ); - - // Disconnect the regular peer and verify neither is selected - mock_network.disconnect_peer(regular_peer_1); - assert_matches!( - client.choose_peer_for_request(&storage_request), - Err(Error::DataIsUnavailable(_)) - ); - - // Advertise the data for the priority peer and verify it is now selected again - client.update_summary(priority_peer_1, mock_storage_summary(known_version + 1000)); - assert_eq!( - client.choose_peer_for_request(&storage_request), - Ok(priority_peer_1) - ); - - // Disconnect the priority peer so that we no longer have any connections - mock_network.disconnect_peer(priority_peer_1); - } -} - -#[tokio::test] -async fn all_peer_request_selection() { - ::aptos_logger::Logger::init_for_testing(); - let (mut mock_network, _, client, _) = MockNetwork::new(None, None, None); - - // Ensure no peers can service the given request (we have no connections) - let server_version_request = - StorageServiceRequest::new(DataRequest::GetServerProtocolVersion, true); - assert_matches!( - client.choose_peer_for_request(&server_version_request), - Err(Error::DataIsUnavailable(_)) - ); - - // Add a regular peer and verify the peer is selected as the recipient - let regular_peer_1 = mock_network.add_peer(false); - assert_eq!( - client.choose_peer_for_request(&server_version_request), - Ok(regular_peer_1) - ); - - // Add two prioritized peers - let priority_peer_1 = mock_network.add_peer(true); - let priority_peer_2 = mock_network.add_peer(true); - - // Request data that is not being advertised and verify we get an error - let output_data_request = - DataRequest::GetTransactionOutputsWithProof(TransactionOutputsWithProofRequest { - proof_version: 100, - start_version: 0, - end_version: 100, - }); - let storage_request = StorageServiceRequest::new(output_data_request, false); - assert_matches!( - client.choose_peer_for_request(&storage_request), - Err(Error::DataIsUnavailable(_)) - ); - - // Advertise the data for the regular peer and verify it is now selected - client.update_summary(regular_peer_1, mock_storage_summary(100)); - assert_eq!( - client.choose_peer_for_request(&storage_request), - Ok(regular_peer_1) - ); - - // Advertise the data for the priority peer and verify the priority peer is selected - client.update_summary(priority_peer_2, mock_storage_summary(100)); - let peer_for_request = client.choose_peer_for_request(&storage_request).unwrap(); - assert_eq!(peer_for_request, priority_peer_2); - - // Reconnect priority peer 1 and remove the advertised data for priority peer 2 - mock_network.reconnect_peer(priority_peer_1); - client.update_summary(priority_peer_2, mock_storage_summary(0)); - - // Request the data again and verify the regular peer is chosen - assert_eq!( - client.choose_peer_for_request(&storage_request), - Ok(regular_peer_1) - ); - - // Advertise the data for priority peer 1 and verify the priority peer is selected - client.update_summary(priority_peer_1, mock_storage_summary(100)); - let peer_for_request = client.choose_peer_for_request(&storage_request).unwrap(); - assert_eq!(peer_for_request, priority_peer_1); - - // Advertise the data for priority peer 2 and verify either priority peer is selected - client.update_summary(priority_peer_2, mock_storage_summary(100)); - let peer_for_request = client.choose_peer_for_request(&storage_request).unwrap(); - assert!(peer_for_request == priority_peer_1 || peer_for_request == priority_peer_2); -} - -#[tokio::test] -async fn validator_peer_prioritization() { - ::aptos_logger::Logger::init_for_testing(); - - // Create a validator node - let base_config = BaseConfig { - role: RoleType::Validator, - ..Default::default() - }; - let (mut mock_network, _, client, _) = MockNetwork::new(Some(base_config), None, None); - - // Add a validator peer and ensure it's prioritized - let validator_peer = mock_network.add_peer_with_network_id(NetworkId::Validator, false); - let (priority_peers, regular_peers) = client.get_priority_and_regular_peers().unwrap(); - assert_eq!(priority_peers, vec![validator_peer]); - assert_eq!(regular_peers, vec![]); - - // Add a vfn peer and ensure it's not prioritized - let vfn_peer = mock_network.add_peer_with_network_id(NetworkId::Vfn, true); - let (priority_peers, regular_peers) = client.get_priority_and_regular_peers().unwrap(); - assert_eq!(priority_peers, vec![validator_peer]); - assert_eq!(regular_peers, vec![vfn_peer]); -} - -#[tokio::test] -async fn vfn_peer_prioritization() { - ::aptos_logger::Logger::init_for_testing(); - - // Create a validator fullnode - let base_config = BaseConfig { - role: RoleType::FullNode, - ..Default::default() - }; - let (mut mock_network, _, client, _) = MockNetwork::new(Some(base_config), None, None); - - // Add a validator peer and ensure it's prioritized - let validator_peer = mock_network.add_peer_with_network_id(NetworkId::Vfn, false); - let (priority_peers, regular_peers) = client.get_priority_and_regular_peers().unwrap(); - assert_eq!(priority_peers, vec![validator_peer]); - assert_eq!(regular_peers, vec![]); - - // Add a pfn peer and ensure it's not prioritized - let pfn_peer = mock_network.add_peer_with_network_id(NetworkId::Public, true); - let (priority_peers, regular_peers) = client.get_priority_and_regular_peers().unwrap(); - assert_eq!(priority_peers, vec![validator_peer]); - assert_eq!(regular_peers, vec![pfn_peer]); -} - -#[tokio::test] -async fn pfn_peer_prioritization() { - ::aptos_logger::Logger::init_for_testing(); - - // Create a public fullnode - let base_config = BaseConfig { - role: RoleType::FullNode, - ..Default::default() - }; - let (mut mock_network, _, client, _) = - MockNetwork::new(Some(base_config), None, Some(vec![NetworkId::Public])); - - // Add an inbound pfn peer and ensure it's not prioritized - let inbound_peer = mock_network.add_peer_with_network_id(NetworkId::Public, false); - let (priority_peers, regular_peers) = client.get_priority_and_regular_peers().unwrap(); - assert_eq!(priority_peers, vec![]); - assert_eq!(regular_peers, vec![inbound_peer]); - - // Add an outbound pfn peer and ensure it's prioritized - let outbound_peer = mock_network.add_peer_with_network_id(NetworkId::Public, true); - let (priority_peers, regular_peers) = client.get_priority_and_regular_peers().unwrap(); - assert_eq!(priority_peers, vec![outbound_peer]); - assert_eq!(regular_peers, vec![inbound_peer]); -} - -// 1. 2 peers -// 2. one advertises bad range, one advertises honest range -// 3. sending a bunch of requests to the bad range (which will always go to the -// bad peer) should lower bad peer's score -// 4. eventually bad peer score should hit threshold and we err with no available -#[tokio::test] -async fn bad_peer_is_eventually_banned_internal() { - ::aptos_logger::Logger::init_for_testing(); - let (mut mock_network, _, client, _) = MockNetwork::new(None, None, None); - - let good_peer = mock_network.add_peer(true); - let bad_peer = mock_network.add_peer(true); - - // Bypass poller and just add the storage summaries directly. - - // Good peer advertises txns 0 -> 100. - client.update_summary(good_peer, mock_storage_summary(100)); - // Bad peer advertises txns 0 -> 200 (but can't actually service). - client.update_summary(bad_peer, mock_storage_summary(200)); - client.update_global_summary_cache().unwrap(); - - // The global summary should contain the bad peer's advertisement. - let global_summary = client.get_global_data_summary(); - assert!(global_summary - .advertised_data - .transactions - .contains(&CompleteDataRange::new(0, 200).unwrap())); - - // Spawn a handler for both peers. - tokio::spawn(async move { - while let Some(network_request) = mock_network.next_request().await { - let peer_network_id = network_request.peer_network_id; - let response_sender = network_request.response_sender; - if peer_network_id == good_peer { - // Good peer responds with good response. - let data_response = - DataResponse::TransactionsWithProof(TransactionListWithProof::new_empty()); - response_sender.send(Ok(StorageServiceResponse::new(data_response, true).unwrap())); - } else if peer_network_id == bad_peer { - // Bad peer responds with error. - response_sender.send(Err(StorageServiceError::InternalError("".to_string()))); - } - } - }); - - let mut seen_data_unavailable_err = false; - - // Sending a bunch of requests to the bad peer's upper range will fail. - let request_timeout = client.get_response_timeout_ms(); - for _ in 0..20 { - let result = client - .get_transactions_with_proof(200, 200, 200, false, request_timeout) - .await; - - // While the score is still decreasing, we should see a bunch of - // InternalError's. Once we see a `DataIsUnavailable` error, we should - // only see that error. - if !seen_data_unavailable_err { - assert_err!(&result); - if let Err(Error::DataIsUnavailable(_)) = result { - seen_data_unavailable_err = true; - } - } else { - assert_matches!(result, Err(Error::DataIsUnavailable(_))); - } - } - - // Peer should eventually get ignored and we should consider this request - // range unserviceable. - assert!(seen_data_unavailable_err); - - // The global summary should no longer contain the bad peer's advertisement. - client.update_global_summary_cache().unwrap(); - let global_summary = client.get_global_data_summary(); - assert!(!global_summary - .advertised_data - .transactions - .contains(&CompleteDataRange::new(0, 200).unwrap())); - - // We should still be able to send the good peer a request. - let response = client - .get_transactions_with_proof(100, 50, 100, false, request_timeout) - .await - .unwrap(); - assert_eq!(response.payload, TransactionListWithProof::new_empty()); -} - -#[tokio::test] -async fn bad_peer_is_eventually_banned_callback() { - ::aptos_logger::Logger::init_for_testing(); - let (mut mock_network, _, client, _) = MockNetwork::new(None, None, None); - - let bad_peer = mock_network.add_peer(true); - - // Bypass poller and just add the storage summaries directly. - // Bad peer advertises txns 0 -> 200 (but can't actually service). - client.update_summary(bad_peer, mock_storage_summary(200)); - client.update_global_summary_cache().unwrap(); - - // Spawn a handler for both peers. - tokio::spawn(async move { - while let Some(network_request) = mock_network.next_request().await { - let data_response = - DataResponse::TransactionsWithProof(TransactionListWithProof::new_empty()); - network_request - .response_sender - .send(Ok(StorageServiceResponse::new(data_response, true).unwrap())); - } - }); - - let mut seen_data_unavailable_err = false; - - // Sending a bunch of requests to the bad peer (that we later decide are bad). - let request_timeout = client.get_response_timeout_ms(); - for _ in 0..20 { - let result = client - .get_transactions_with_proof(200, 200, 200, false, request_timeout) - .await; - - // While the score is still decreasing, we should see a bunch of - // InternalError's. Once we see a `DataIsUnavailable` error, we should - // only see that error. - if !seen_data_unavailable_err { - match result { - Ok(response) => { - response.context.response_callback.notify_bad_response( - crate::interface::ResponseError::ProofVerificationError, - ); - }, - Err(Error::DataIsUnavailable(_)) => { - seen_data_unavailable_err = true; - }, - Err(_) => panic!("unexpected result: {:?}", result), - } - } else { - assert_matches!(result, Err(Error::DataIsUnavailable(_))); - } - } - - // Peer should eventually get ignored and we should consider this request - // range unserviceable. - assert!(seen_data_unavailable_err); - - // The global summary should no longer contain the bad peer's advertisement. - client.update_global_summary_cache().unwrap(); - let global_summary = client.get_global_data_summary(); - assert!(!global_summary - .advertised_data - .transactions - .contains(&CompleteDataRange::new(0, 200).unwrap())); -} - -#[tokio::test] -async fn compression_mismatch_disabled() { - ::aptos_logger::Logger::init_for_testing(); - - // Disable compression - let data_client_config = AptosDataClientConfig { - use_compression: false, - ..Default::default() - }; - let (mut mock_network, mock_time, client, poller) = - MockNetwork::new(None, Some(data_client_config), None); - - tokio::spawn(poller.start_poller()); - - // Add a connected peer - let _ = mock_network.add_peer(true); - - // Advance time so the poller sends a data summary request - tokio::task::yield_now().await; - mock_time.advance_async(Duration::from_millis(1_000)).await; - - // Receive their request and respond - let network_request = mock_network.next_request().await.unwrap(); - let data_response = DataResponse::StorageServerSummary(mock_storage_summary(200)); - network_request.response_sender.send(Ok( - StorageServiceResponse::new(data_response, false).unwrap() - )); - - // Let the poller finish processing the response - tokio::task::yield_now().await; - - // Handle the client's transactions request using compression - tokio::spawn(async move { - let network_request = mock_network.next_request().await.unwrap(); - assert!(!network_request.storage_service_request.use_compression); - - // Compress the response - let data_response = - DataResponse::TransactionsWithProof(TransactionListWithProof::new_empty()); - let storage_response = StorageServiceResponse::new(data_response, true).unwrap(); - network_request.response_sender.send(Ok(storage_response)); - }); - - // The client should receive a compressed response and return an error - let request_timeout = client.get_response_timeout_ms(); - let response = client - .get_transactions_with_proof(100, 50, 100, false, request_timeout) - .await - .unwrap_err(); - assert_matches!(response, Error::InvalidResponse(_)); -} - -#[tokio::test] -async fn compression_mismatch_enabled() { - ::aptos_logger::Logger::init_for_testing(); - - // Enable compression - let data_client_config = AptosDataClientConfig { - use_compression: true, - ..Default::default() - }; - let (mut mock_network, mock_time, client, poller) = - MockNetwork::new(None, Some(data_client_config), None); - - tokio::spawn(poller.start_poller()); - - // Add a connected peer - let _ = mock_network.add_peer(true); - - // Advance time so the poller sends a data summary request - tokio::task::yield_now().await; - mock_time.advance_async(Duration::from_millis(1_000)).await; - - // Receive their request and respond - let network_request = mock_network.next_request().await.unwrap(); - let data_response = DataResponse::StorageServerSummary(mock_storage_summary(200)); - network_request - .response_sender - .send(Ok(StorageServiceResponse::new(data_response, true).unwrap())); - - // Let the poller finish processing the response - tokio::task::yield_now().await; - - // Handle the client's transactions request without compression - tokio::spawn(async move { - let network_request = mock_network.next_request().await.unwrap(); - assert!(network_request.storage_service_request.use_compression); - - // Compress the response - let data_response = - DataResponse::TransactionsWithProof(TransactionListWithProof::new_empty()); - let storage_response = StorageServiceResponse::new(data_response, false).unwrap(); - network_request.response_sender.send(Ok(storage_response)); - }); - - // The client should receive a compressed response and return an error - let request_timeout = client.get_response_timeout_ms(); - let response = client - .get_transactions_with_proof(100, 50, 100, false, request_timeout) - .await - .unwrap_err(); - assert_matches!(response, Error::InvalidResponse(_)); -} - -#[tokio::test] -async fn disable_compression() { - ::aptos_logger::Logger::init_for_testing(); - - // Disable compression - let data_client_config = AptosDataClientConfig { - use_compression: false, - ..Default::default() - }; - let (mut mock_network, mock_time, client, poller) = - MockNetwork::new(None, Some(data_client_config), None); - - tokio::spawn(poller.start_poller()); - - // Add a connected peer - let expected_peer = mock_network.add_peer(true); - - // Advance time so the poller sends a data summary request - tokio::task::yield_now().await; - mock_time.advance_async(Duration::from_millis(1_000)).await; - - // Receive their request - let network_request = mock_network.next_request().await.unwrap(); - assert_eq!(network_request.peer_network_id, expected_peer); - assert_eq!(network_request.protocol_id, ProtocolId::StorageServiceRpc); - assert!(!network_request.storage_service_request.use_compression); - assert_matches!( - network_request.storage_service_request.data_request, - DataRequest::GetStorageServerSummary - ); - - // Fulfill their request - let data_response = DataResponse::StorageServerSummary(mock_storage_summary(200)); - network_request.response_sender.send(Ok( - StorageServiceResponse::new(data_response, false).unwrap() - )); - - // Let the poller finish processing the response - tokio::task::yield_now().await; - - // Handle the client's transactions request - tokio::spawn(async move { - let network_request = mock_network.next_request().await.unwrap(); - - assert_eq!(network_request.peer_network_id, expected_peer); - assert_eq!(network_request.protocol_id, ProtocolId::StorageServiceRpc); - assert!(!network_request.storage_service_request.use_compression); - assert_matches!( - network_request.storage_service_request.data_request, - DataRequest::GetTransactionsWithProof(TransactionsWithProofRequest { - start_version: 50, - end_version: 100, - proof_version: 100, - include_events: false, - }) - ); - - let data_response = - DataResponse::TransactionsWithProof(TransactionListWithProof::new_empty()); - let storage_response = StorageServiceResponse::new(data_response, false).unwrap(); - network_request.response_sender.send(Ok(storage_response)); - }); - - // The client's request should succeed since a peer finally has advertised - // data for this range. - let request_timeout = client.get_response_timeout_ms(); - let response = client - .get_transactions_with_proof(100, 50, 100, false, request_timeout) - .await - .unwrap(); - assert_eq!(response.payload, TransactionListWithProof::new_empty()); -} - -#[tokio::test(flavor = "multi_thread")] -async fn disconnected_peers_garbage_collection() { - ::aptos_logger::Logger::init_for_testing(); - let (mut mock_network, _, client, _) = MockNetwork::new(None, None, None); - - // Connect several peers - let priority_peer_1 = mock_network.add_peer(true); - let priority_peer_2 = mock_network.add_peer(true); - let priority_peer_3 = mock_network.add_peer(true); - - // Poll all of the peers to initialize the peer states - let all_peers = vec![priority_peer_1, priority_peer_2, priority_peer_3]; - poll_peers(&mut mock_network, &client, all_peers.clone()).await; - - // Verify we have peer states for all peers - verify_peer_states(&client, all_peers.clone()); - - // Disconnect priority peer 1 and update the global data summary - mock_network.disconnect_peer(priority_peer_1); - client.update_global_summary_cache().unwrap(); - - // Verify we have peer states for only the remaining peers - verify_peer_states(&client, vec![priority_peer_2, priority_peer_3]); - - // Disconnect priority peer 2 and update the global data summary - mock_network.disconnect_peer(priority_peer_2); - client.update_global_summary_cache().unwrap(); - - // Verify we have peer states for only priority peer 3 - verify_peer_states(&client, vec![priority_peer_3]); - - // Reconnect priority peer 1, poll it and update the global data summary - mock_network.reconnect_peer(priority_peer_1); - poll_peers(&mut mock_network, &client, vec![priority_peer_1]).await; - client.update_global_summary_cache().unwrap(); - - // Verify we have peer states for priority peer 1 and 3 - verify_peer_states(&client, vec![priority_peer_1, priority_peer_3]); - - // Reconnect priority peer 2, poll it and update the global data summary - mock_network.reconnect_peer(priority_peer_2); - poll_peers(&mut mock_network, &client, vec![priority_peer_2]).await; - client.update_global_summary_cache().unwrap(); - - // Verify we have peer states for all peers - verify_peer_states(&client, all_peers); -} - -#[tokio::test] -async fn bad_peer_is_eventually_added_back() { - ::aptos_logger::Logger::init_for_testing(); - let (mut mock_network, mock_time, client, poller) = MockNetwork::new(None, None, None); - - // Add a connected peer. - mock_network.add_peer(true); - - tokio::spawn(poller.start_poller()); - tokio::spawn(async move { - while let Some(network_request) = mock_network.next_request().await { - match network_request.storage_service_request.data_request { - DataRequest::GetTransactionsWithProof(_) => { - let data_response = - DataResponse::TransactionsWithProof(TransactionListWithProof::new_empty()); - network_request - .response_sender - .send(Ok(StorageServiceResponse::new( - data_response, - network_request.storage_service_request.use_compression, - ) - .unwrap())); - }, - DataRequest::GetStorageServerSummary => { - let data_response = - DataResponse::StorageServerSummary(mock_storage_summary(200)); - network_request - .response_sender - .send(Ok(StorageServiceResponse::new( - data_response, - network_request.storage_service_request.use_compression, - ) - .unwrap())); - }, - _ => panic!( - "Unexpected storage request: {:?}", - network_request.storage_service_request - ), - } - } - }); - - // Advance time so the poller sends data summary requests. - let summary_poll_interval = Duration::from_millis(1_000); - for _ in 0..2 { - tokio::task::yield_now().await; - mock_time.advance_async(summary_poll_interval).await; - } - - // Initially this request range is serviceable by this peer. - let global_summary = client.get_global_data_summary(); - assert!(global_summary - .advertised_data - .transactions - .contains(&CompleteDataRange::new(0, 200).unwrap())); - - // Keep decreasing this peer's score by considering its responses bad. - // Eventually its score drops below IGNORE_PEER_THRESHOLD. - let request_timeout = client.get_response_timeout_ms(); - for _ in 0..20 { - let result = client - .get_transactions_with_proof(200, 0, 200, false, request_timeout) - .await; - - if let Ok(response) = result { - response - .context - .response_callback - .notify_bad_response(crate::interface::ResponseError::ProofVerificationError); - } - } - - // Peer is eventually ignored and this request range unserviceable. - client.update_global_summary_cache().unwrap(); - let global_summary = client.get_global_data_summary(); - assert!(!global_summary - .advertised_data - .transactions - .contains(&CompleteDataRange::new(0, 200).unwrap())); - - // This peer still responds to the StorageServerSummary requests. - // Its score keeps increasing and this peer is eventually added back. - for _ in 0..20 { - mock_time.advance_async(summary_poll_interval).await; - } - - let global_summary = client.get_global_data_summary(); - assert!(global_summary - .advertised_data - .transactions - .contains(&CompleteDataRange::new(0, 200).unwrap())); -} - -#[tokio::test] -async fn optimal_chunk_size_calculations() { - // Create a test storage service config - let max_epoch_chunk_size = 600; - let max_state_chunk_size = 500; - let max_transaction_chunk_size = 700; - let max_transaction_output_chunk_size = 800; - let data_client_config = AptosDataClientConfig { - max_epoch_chunk_size, - max_state_chunk_size, - max_transaction_chunk_size, - max_transaction_output_chunk_size, - ..Default::default() - }; - - // Test median calculations - let optimal_chunk_sizes = calculate_optimal_chunk_sizes( - &data_client_config, - vec![7, 5, 6, 8, 10], - vec![100, 200, 300, 100], - vec![900, 700, 500], - vec![40], - ); - assert_eq!(200, optimal_chunk_sizes.state_chunk_size); - assert_eq!(7, optimal_chunk_sizes.epoch_chunk_size); - assert_eq!(700, optimal_chunk_sizes.transaction_chunk_size); - assert_eq!(40, optimal_chunk_sizes.transaction_output_chunk_size); - - // Test no advertised data - let optimal_chunk_sizes = - calculate_optimal_chunk_sizes(&data_client_config, vec![], vec![], vec![], vec![]); - assert_eq!(max_state_chunk_size, optimal_chunk_sizes.state_chunk_size); - assert_eq!(max_epoch_chunk_size, optimal_chunk_sizes.epoch_chunk_size); - assert_eq!( - max_transaction_chunk_size, - optimal_chunk_sizes.transaction_chunk_size - ); - assert_eq!( - max_transaction_output_chunk_size, - optimal_chunk_sizes.transaction_output_chunk_size - ); - - // Verify the config caps the amount of chunks - let optimal_chunk_sizes = calculate_optimal_chunk_sizes( - &data_client_config, - vec![70, 50, 60, 80, 100], - vec![1000, 1000, 2000, 3000], - vec![9000, 7000, 5000], - vec![400], - ); - assert_eq!(max_state_chunk_size, optimal_chunk_sizes.state_chunk_size); - assert_eq!(70, optimal_chunk_sizes.epoch_chunk_size); - assert_eq!( - max_transaction_chunk_size, - optimal_chunk_sizes.transaction_chunk_size - ); - assert_eq!(400, optimal_chunk_sizes.transaction_output_chunk_size); -} - -/// A helper method that fetches peers to poll depending on the peer priority -fn fetch_peer_to_poll( - client: AptosDataClient, - is_priority_peer: bool, -) -> Result, Error> { - // Fetch the next peer to poll - let result = if is_priority_peer { - client.fetch_prioritized_peer_to_poll() - } else { - client.fetch_regular_peer_to_poll() - }; - - // If we get a peer, mark the peer as having an in-flight request - if let Ok(Some(peer_to_poll)) = result { - client.in_flight_request_started(&peer_to_poll); - } - - result -} - -/// Fetches the number of in flight requests for peers depending on priority -fn get_num_in_flight_polls(client: AptosDataClient, is_priority_peer: bool) -> u64 { - if is_priority_peer { - client.get_peer_states().num_in_flight_priority_polls() - } else { - client.get_peer_states().num_in_flight_regular_polls() - } -} - -/// A simple helper function that polls all the specified peers -/// and returns storage server summaries for each. -async fn poll_peers( - mock_network: &mut MockNetwork, - client: &AptosDataClient, - all_peers: Vec, -) { - for peer in all_peers { - // Poll the peer - let handle = poll_peer(client.clone(), peer, None); - - // Respond to the poll request - let network_request = mock_network.next_request().await.unwrap(); - let data_response = DataResponse::StorageServerSummary(StorageServerSummary::default()); - network_request - .response_sender - .send(Ok(StorageServiceResponse::new(data_response, true).unwrap())); - - // Wait for the poll to complete - handle.await.unwrap(); - } -} - -/// Verifies the exclusive existence of peer states for all the specified peers -fn verify_peer_states(client: &AptosDataClient, all_peers: Vec) { - let peer_to_states = client.get_peer_states().get_peer_to_states(); - for peer in &all_peers { - assert!(peer_to_states.contains_key(peer)); - } - assert_eq!(peer_to_states.len(), all_peers.len()); -} diff --git a/state-sync/aptos-data-client/src/tests/advertise.rs b/state-sync/aptos-data-client/src/tests/advertise.rs new file mode 100644 index 0000000000000..772a1bc49086f --- /dev/null +++ b/state-sync/aptos-data-client/src/tests/advertise.rs @@ -0,0 +1,159 @@ +// Copyright © Aptos Foundation +// SPDX-License-Identifier: Apache-2.0 + +use crate::{ + error::Error, + interface::AptosDataClientInterface, + peer_states::calculate_optimal_chunk_sizes, + tests::{mock::MockNetwork, utils}, +}; +use aptos_config::config::AptosDataClientConfig; +use aptos_network::protocols::wire::handshake::v1::ProtocolId; +use aptos_storage_service_types::{ + requests::{DataRequest, TransactionsWithProofRequest}, + responses::{DataResponse, StorageServiceResponse}, +}; +use aptos_types::transaction::TransactionListWithProof; +use claims::assert_matches; +use std::time::Duration; + +#[tokio::test] +async fn request_works_only_when_data_available() { + ::aptos_logger::Logger::init_for_testing(); + let (mut mock_network, mock_time, client, poller) = MockNetwork::new(None, None, None); + + tokio::spawn(poller.start_poller()); + + // This request should fail because no peers are currently connected + let request_timeout = client.get_response_timeout_ms(); + let error = client + .get_transactions_with_proof(100, 50, 100, false, request_timeout) + .await + .unwrap_err(); + assert_matches!(error, Error::DataIsUnavailable(_)); + + // Add a connected peer + let expected_peer = mock_network.add_peer(true); + + // Requesting some txns now will still fail since no peers are advertising + // availability for the desired range. + let error = client + .get_transactions_with_proof(100, 50, 100, false, request_timeout) + .await + .unwrap_err(); + assert_matches!(error, Error::DataIsUnavailable(_)); + + // Advance time so the poller sends a data summary request + tokio::task::yield_now().await; + mock_time.advance_async(Duration::from_millis(1_000)).await; + + // Receive their request and fulfill it + let network_request = mock_network.next_request().await.unwrap(); + assert_eq!(network_request.peer_network_id, expected_peer); + assert_eq!(network_request.protocol_id, ProtocolId::StorageServiceRpc); + assert!(network_request.storage_service_request.use_compression); + assert_matches!( + network_request.storage_service_request.data_request, + DataRequest::GetStorageServerSummary + ); + + let summary = utils::create_storage_summary(200); + let data_response = DataResponse::StorageServerSummary(summary); + network_request + .response_sender + .send(Ok(StorageServiceResponse::new(data_response, true).unwrap())); + + // Let the poller finish processing the response + tokio::task::yield_now().await; + + // Handle the client's transactions request + tokio::spawn(async move { + let network_request = mock_network.next_request().await.unwrap(); + + assert_eq!(network_request.peer_network_id, expected_peer); + assert_eq!(network_request.protocol_id, ProtocolId::StorageServiceRpc); + assert!(network_request.storage_service_request.use_compression); + assert_matches!( + network_request.storage_service_request.data_request, + DataRequest::GetTransactionsWithProof(TransactionsWithProofRequest { + start_version: 50, + end_version: 100, + proof_version: 100, + include_events: false, + }) + ); + + let data_response = + DataResponse::TransactionsWithProof(TransactionListWithProof::new_empty()); + network_request + .response_sender + .send(Ok(StorageServiceResponse::new(data_response, true).unwrap())); + }); + + // The client's request should succeed since a peer finally has advertised + // data for this range. + let response = client + .get_transactions_with_proof(100, 50, 100, false, request_timeout) + .await + .unwrap(); + assert_eq!(response.payload, TransactionListWithProof::new_empty()); +} + +#[tokio::test] +async fn optimal_chunk_size_calculations() { + // Create a test storage service config + let max_epoch_chunk_size = 600; + let max_state_chunk_size = 500; + let max_transaction_chunk_size = 700; + let max_transaction_output_chunk_size = 800; + let data_client_config = AptosDataClientConfig { + max_epoch_chunk_size, + max_state_chunk_size, + max_transaction_chunk_size, + max_transaction_output_chunk_size, + ..Default::default() + }; + + // Test median calculations + let optimal_chunk_sizes = calculate_optimal_chunk_sizes( + &data_client_config, + vec![7, 5, 6, 8, 10], + vec![100, 200, 300, 100], + vec![900, 700, 500], + vec![40], + ); + assert_eq!(200, optimal_chunk_sizes.state_chunk_size); + assert_eq!(7, optimal_chunk_sizes.epoch_chunk_size); + assert_eq!(700, optimal_chunk_sizes.transaction_chunk_size); + assert_eq!(40, optimal_chunk_sizes.transaction_output_chunk_size); + + // Test no advertised data + let optimal_chunk_sizes = + calculate_optimal_chunk_sizes(&data_client_config, vec![], vec![], vec![], vec![]); + assert_eq!(max_state_chunk_size, optimal_chunk_sizes.state_chunk_size); + assert_eq!(max_epoch_chunk_size, optimal_chunk_sizes.epoch_chunk_size); + assert_eq!( + max_transaction_chunk_size, + optimal_chunk_sizes.transaction_chunk_size + ); + assert_eq!( + max_transaction_output_chunk_size, + optimal_chunk_sizes.transaction_output_chunk_size + ); + + // Verify the config caps the amount of chunks + let optimal_chunk_sizes = calculate_optimal_chunk_sizes( + &data_client_config, + vec![70, 50, 60, 80, 100], + vec![1000, 1000, 2000, 3000], + vec![9000, 7000, 5000], + vec![400], + ); + assert_eq!(max_state_chunk_size, optimal_chunk_sizes.state_chunk_size); + assert_eq!(70, optimal_chunk_sizes.epoch_chunk_size); + assert_eq!( + max_transaction_chunk_size, + optimal_chunk_sizes.transaction_chunk_size + ); + assert_eq!(400, optimal_chunk_sizes.transaction_output_chunk_size); +} diff --git a/state-sync/aptos-data-client/src/tests/compression.rs b/state-sync/aptos-data-client/src/tests/compression.rs new file mode 100644 index 0000000000000..b073610143de9 --- /dev/null +++ b/state-sync/aptos-data-client/src/tests/compression.rs @@ -0,0 +1,194 @@ +// Copyright © Aptos Foundation +// SPDX-License-Identifier: Apache-2.0 + +use crate::{ + error::Error, + interface::AptosDataClientInterface, + tests::{mock::MockNetwork, utils}, +}; +use aptos_config::config::AptosDataClientConfig; +use aptos_network::protocols::wire::handshake::v1::ProtocolId; +use aptos_storage_service_types::{ + requests::{DataRequest, TransactionsWithProofRequest}, + responses::{DataResponse, StorageServiceResponse}, +}; +use aptos_types::transaction::TransactionListWithProof; +use claims::assert_matches; +use std::time::Duration; + +#[tokio::test] +async fn compression_mismatch_disabled() { + ::aptos_logger::Logger::init_for_testing(); + + // Disable compression + let data_client_config = AptosDataClientConfig { + use_compression: false, + ..Default::default() + }; + let (mut mock_network, mock_time, client, poller) = + MockNetwork::new(None, Some(data_client_config), None); + + tokio::spawn(poller.start_poller()); + + // Add a connected peer + let _ = mock_network.add_peer(true); + + // Advance time so the poller sends a data summary request + tokio::task::yield_now().await; + mock_time.advance_async(Duration::from_millis(1_000)).await; + + // Receive their request and respond + let network_request = mock_network.next_request().await.unwrap(); + let data_response = DataResponse::StorageServerSummary(utils::create_storage_summary(200)); + network_request.response_sender.send(Ok( + StorageServiceResponse::new(data_response, false).unwrap() + )); + + // Let the poller finish processing the response + tokio::task::yield_now().await; + + // Handle the client's transactions request using compression + tokio::spawn(async move { + let network_request = mock_network.next_request().await.unwrap(); + assert!(!network_request.storage_service_request.use_compression); + + // Compress the response + let data_response = + DataResponse::TransactionsWithProof(TransactionListWithProof::new_empty()); + let storage_response = StorageServiceResponse::new(data_response, true).unwrap(); + network_request.response_sender.send(Ok(storage_response)); + }); + + // The client should receive a compressed response and return an error + let request_timeout = client.get_response_timeout_ms(); + let response = client + .get_transactions_with_proof(100, 50, 100, false, request_timeout) + .await + .unwrap_err(); + assert_matches!(response, Error::InvalidResponse(_)); +} + +#[tokio::test] +async fn compression_mismatch_enabled() { + ::aptos_logger::Logger::init_for_testing(); + + // Enable compression + let data_client_config = AptosDataClientConfig { + use_compression: true, + ..Default::default() + }; + let (mut mock_network, mock_time, client, poller) = + MockNetwork::new(None, Some(data_client_config), None); + + tokio::spawn(poller.start_poller()); + + // Add a connected peer + let _ = mock_network.add_peer(true); + + // Advance time so the poller sends a data summary request + tokio::task::yield_now().await; + mock_time.advance_async(Duration::from_millis(1_000)).await; + + // Receive their request and respond + let network_request = mock_network.next_request().await.unwrap(); + let data_response = DataResponse::StorageServerSummary(utils::create_storage_summary(200)); + network_request + .response_sender + .send(Ok(StorageServiceResponse::new(data_response, true).unwrap())); + + // Let the poller finish processing the response + tokio::task::yield_now().await; + + // Handle the client's transactions request without compression + tokio::spawn(async move { + let network_request = mock_network.next_request().await.unwrap(); + assert!(network_request.storage_service_request.use_compression); + + // Compress the response + let data_response = + DataResponse::TransactionsWithProof(TransactionListWithProof::new_empty()); + let storage_response = StorageServiceResponse::new(data_response, false).unwrap(); + network_request.response_sender.send(Ok(storage_response)); + }); + + // The client should receive a compressed response and return an error + let request_timeout = client.get_response_timeout_ms(); + let response = client + .get_transactions_with_proof(100, 50, 100, false, request_timeout) + .await + .unwrap_err(); + assert_matches!(response, Error::InvalidResponse(_)); +} + +#[tokio::test] +async fn disable_compression() { + ::aptos_logger::Logger::init_for_testing(); + + // Disable compression + let data_client_config = AptosDataClientConfig { + use_compression: false, + ..Default::default() + }; + let (mut mock_network, mock_time, client, poller) = + MockNetwork::new(None, Some(data_client_config), None); + + tokio::spawn(poller.start_poller()); + + // Add a connected peer + let expected_peer = mock_network.add_peer(true); + + // Advance time so the poller sends a data summary request + tokio::task::yield_now().await; + mock_time.advance_async(Duration::from_millis(1_000)).await; + + // Receive their request + let network_request = mock_network.next_request().await.unwrap(); + assert_eq!(network_request.peer_network_id, expected_peer); + assert_eq!(network_request.protocol_id, ProtocolId::StorageServiceRpc); + assert!(!network_request.storage_service_request.use_compression); + assert_matches!( + network_request.storage_service_request.data_request, + DataRequest::GetStorageServerSummary + ); + + // Fulfill their request + let data_response = DataResponse::StorageServerSummary(utils::create_storage_summary(200)); + network_request.response_sender.send(Ok( + StorageServiceResponse::new(data_response, false).unwrap() + )); + + // Let the poller finish processing the response + tokio::task::yield_now().await; + + // Handle the client's transactions request + tokio::spawn(async move { + let network_request = mock_network.next_request().await.unwrap(); + + assert_eq!(network_request.peer_network_id, expected_peer); + assert_eq!(network_request.protocol_id, ProtocolId::StorageServiceRpc); + assert!(!network_request.storage_service_request.use_compression); + assert_matches!( + network_request.storage_service_request.data_request, + DataRequest::GetTransactionsWithProof(TransactionsWithProofRequest { + start_version: 50, + end_version: 100, + proof_version: 100, + include_events: false, + }) + ); + + let data_response = + DataResponse::TransactionsWithProof(TransactionListWithProof::new_empty()); + let storage_response = StorageServiceResponse::new(data_response, false).unwrap(); + network_request.response_sender.send(Ok(storage_response)); + }); + + // The client's request should succeed since a peer finally has advertised + // data for this range. + let request_timeout = client.get_response_timeout_ms(); + let response = client + .get_transactions_with_proof(100, 50, 100, false, request_timeout) + .await + .unwrap(); + assert_eq!(response.payload, TransactionListWithProof::new_empty()); +} diff --git a/state-sync/aptos-data-client/src/tests/mock.rs b/state-sync/aptos-data-client/src/tests/mock.rs new file mode 100644 index 0000000000000..1cdfbcb2517cf --- /dev/null +++ b/state-sync/aptos-data-client/src/tests/mock.rs @@ -0,0 +1,172 @@ +// Copyright © Aptos Foundation +// SPDX-License-Identifier: Apache-2.0 + +use crate::{client::AptosDataClient, poller::DataSummaryPoller}; +use aptos_channels::{aptos_channel, message_queues::QueueStyle}; +use aptos_config::{ + config::{AptosDataClientConfig, BaseConfig}, + network_id::{NetworkId, PeerNetworkId}, +}; +use aptos_netcore::transport::ConnectionOrigin; +use aptos_network::{ + application::{interface::NetworkClient, metadata::ConnectionState, storage::PeersAndMetadata}, + peer_manager::{ConnectionRequestSender, PeerManagerRequest, PeerManagerRequestSender}, + protocols::{ + network::{NetworkSender, NewNetworkSender}, + wire::handshake::v1::ProtocolId, + }, + transport::ConnectionMetadata, +}; +use aptos_storage_service_client::StorageServiceClient; +use aptos_storage_service_server::network::{NetworkRequest, ResponseSender}; +use aptos_storage_service_types::StorageServiceMessage; +use aptos_time_service::{MockTimeService, TimeService}; +use aptos_types::PeerId; +use futures::StreamExt; +use maplit::hashmap; +use std::sync::Arc; + +/// A simple mock network for testing the data client +pub struct MockNetwork { + network_id: NetworkId, + peer_mgr_reqs_rx: aptos_channel::Receiver<(PeerId, ProtocolId), PeerManagerRequest>, + peers_and_metadata: Arc, +} + +impl MockNetwork { + pub fn new( + base_config: Option, + data_client_config: Option, + networks: Option>, + ) -> (Self, MockTimeService, AptosDataClient, DataSummaryPoller) { + // Setup the request managers + let queue_cfg = aptos_channel::Config::new(10).queue_style(QueueStyle::FIFO); + let (peer_mgr_reqs_tx, peer_mgr_reqs_rx) = queue_cfg.build(); + let (connection_reqs_tx, _connection_reqs_rx) = queue_cfg.build(); + + // Setup the network client + let network_sender = NetworkSender::new( + PeerManagerRequestSender::new(peer_mgr_reqs_tx), + ConnectionRequestSender::new(connection_reqs_tx), + ); + let networks = networks + .unwrap_or_else(|| vec![NetworkId::Validator, NetworkId::Vfn, NetworkId::Public]); + let peers_and_metadata = PeersAndMetadata::new(&networks); + let client_network_id = NetworkId::Validator; + let network_client = NetworkClient::new( + vec![], + vec![ProtocolId::StorageServiceRpc], + hashmap! { + client_network_id => network_sender}, + peers_and_metadata.clone(), + ); + + // Create a storage service client + let storage_service_client = StorageServiceClient::new(network_client); + + // Create an aptos data client + let mock_time = TimeService::mock(); + let base_config = base_config.unwrap_or_default(); + let data_client_config = data_client_config.unwrap_or_default(); + let (client, poller) = AptosDataClient::new( + data_client_config, + base_config, + mock_time.clone(), + storage_service_client, + None, + ); + + // Create the mock network + let mock_network = Self { + network_id: client_network_id, + peer_mgr_reqs_rx, + peers_and_metadata, + }; + + (mock_network, mock_time.into_mock(), client, poller) + } + + /// Add a new peer to the network peer DB + pub fn add_peer(&mut self, priority: bool) -> PeerNetworkId { + // Get the network id + let network_id = if priority { + NetworkId::Validator + } else { + NetworkId::Public + }; + self.add_peer_with_network_id(network_id, false) + } + + /// Add a new peer to the network peer DB with the specified network + pub fn add_peer_with_network_id( + &mut self, + network_id: NetworkId, + outbound_connection: bool, + ) -> PeerNetworkId { + // Create a new peer + let peer_id = PeerId::random(); + let peer_network_id = PeerNetworkId::new(network_id, peer_id); + + // Create and save a new connection metadata + let mut connection_metadata = ConnectionMetadata::mock(peer_id); + connection_metadata.origin = if outbound_connection { + ConnectionOrigin::Outbound + } else { + ConnectionOrigin::Inbound + }; + connection_metadata + .application_protocols + .insert(ProtocolId::StorageServiceRpc); + self.peers_and_metadata + .insert_connection_metadata(peer_network_id, connection_metadata) + .unwrap(); + + // Return the new peer + peer_network_id + } + + /// Disconnects the peer in the network peer DB + pub fn disconnect_peer(&mut self, peer: PeerNetworkId) { + self.update_peer_state(peer, ConnectionState::Disconnected); + } + + /// Reconnects the peer in the network peer DB + pub fn reconnect_peer(&mut self, peer: PeerNetworkId) { + self.update_peer_state(peer, ConnectionState::Connected); + } + + /// Updates the state of the given peer + fn update_peer_state(&mut self, peer: PeerNetworkId, state: ConnectionState) { + self.peers_and_metadata + .update_connection_state(peer, state) + .unwrap(); + } + + /// Get the next request sent from the client. + pub async fn next_request(&mut self) -> Option { + match self.peer_mgr_reqs_rx.next().await { + Some(PeerManagerRequest::SendRpc(peer_id, network_request)) => { + let peer_network_id = PeerNetworkId::new(self.network_id, peer_id); + let protocol_id = network_request.protocol_id; + let data = network_request.data; + let res_tx = network_request.res_tx; + + let message: StorageServiceMessage = bcs::from_bytes(data.as_ref()).unwrap(); + let storage_service_request = match message { + StorageServiceMessage::Request(request) => request, + _ => panic!("unexpected: {:?}", message), + }; + let response_sender = ResponseSender::new(res_tx); + + Some(NetworkRequest { + peer_network_id, + protocol_id, + storage_service_request, + response_sender, + }) + }, + Some(PeerManagerRequest::SendDirectSend(_, _)) => panic!("Unexpected direct send msg"), + None => None, + } + } +} diff --git a/state-sync/aptos-data-client/src/tests/mod.rs b/state-sync/aptos-data-client/src/tests/mod.rs new file mode 100644 index 0000000000000..5b5f32830ba78 --- /dev/null +++ b/state-sync/aptos-data-client/src/tests/mod.rs @@ -0,0 +1,10 @@ +// Copyright © Aptos Foundation +// SPDX-License-Identifier: Apache-2.0 + +mod advertise; +mod compression; +mod mock; +mod peers; +mod poller; +mod priority; +mod utils; diff --git a/state-sync/aptos-data-client/src/tests/peers.rs b/state-sync/aptos-data-client/src/tests/peers.rs new file mode 100644 index 0000000000000..b9424bd84dc11 --- /dev/null +++ b/state-sync/aptos-data-client/src/tests/peers.rs @@ -0,0 +1,339 @@ +// Copyright © Aptos Foundation +// SPDX-License-Identifier: Apache-2.0 + +use crate::{ + client::AptosDataClient, + error::Error, + interface::AptosDataClientInterface, + poller::poll_peer, + tests::{mock::MockNetwork, utils}, +}; +use aptos_config::network_id::PeerNetworkId; +use aptos_storage_service_types::{ + requests::DataRequest, + responses::{CompleteDataRange, DataResponse, StorageServerSummary, StorageServiceResponse}, + StorageServiceError, +}; +use aptos_types::transaction::TransactionListWithProof; +use claims::{assert_err, assert_matches}; +use std::time::Duration; + +#[tokio::test] +async fn bad_peer_is_eventually_banned_internal() { + ::aptos_logger::Logger::init_for_testing(); + let (mut mock_network, _, client, _) = MockNetwork::new(None, None, None); + + let good_peer = mock_network.add_peer(true); + let bad_peer = mock_network.add_peer(true); + + // Bypass poller and just add the storage summaries directly. + + // Good peer advertises txns 0 -> 100. + client.update_summary(good_peer, utils::create_storage_summary(100)); + // Bad peer advertises txns 0 -> 200 (but can't actually service). + client.update_summary(bad_peer, utils::create_storage_summary(200)); + client.update_global_summary_cache().unwrap(); + + // The global summary should contain the bad peer's advertisement. + let global_summary = client.get_global_data_summary(); + assert!(global_summary + .advertised_data + .transactions + .contains(&CompleteDataRange::new(0, 200).unwrap())); + + // Spawn a handler for both peers. + tokio::spawn(async move { + while let Some(network_request) = mock_network.next_request().await { + let peer_network_id = network_request.peer_network_id; + let response_sender = network_request.response_sender; + if peer_network_id == good_peer { + // Good peer responds with good response. + let data_response = + DataResponse::TransactionsWithProof(TransactionListWithProof::new_empty()); + response_sender.send(Ok(StorageServiceResponse::new(data_response, true).unwrap())); + } else if peer_network_id == bad_peer { + // Bad peer responds with error. + response_sender.send(Err(StorageServiceError::InternalError("".to_string()))); + } + } + }); + + let mut seen_data_unavailable_err = false; + + // Sending a bunch of requests to the bad peer's upper range will fail. + let request_timeout = client.get_response_timeout_ms(); + for _ in 0..20 { + let result = client + .get_transactions_with_proof(200, 200, 200, false, request_timeout) + .await; + + // While the score is still decreasing, we should see a bunch of + // InternalError's. Once we see a `DataIsUnavailable` error, we should + // only see that error. + if !seen_data_unavailable_err { + assert_err!(&result); + if let Err(Error::DataIsUnavailable(_)) = result { + seen_data_unavailable_err = true; + } + } else { + assert_matches!(result, Err(Error::DataIsUnavailable(_))); + } + } + + // Peer should eventually get ignored and we should consider this request + // range unserviceable. + assert!(seen_data_unavailable_err); + + // The global summary should no longer contain the bad peer's advertisement. + client.update_global_summary_cache().unwrap(); + let global_summary = client.get_global_data_summary(); + assert!(!global_summary + .advertised_data + .transactions + .contains(&CompleteDataRange::new(0, 200).unwrap())); + + // We should still be able to send the good peer a request. + let response = client + .get_transactions_with_proof(100, 50, 100, false, request_timeout) + .await + .unwrap(); + assert_eq!(response.payload, TransactionListWithProof::new_empty()); +} + +#[tokio::test] +async fn bad_peer_is_eventually_banned_callback() { + ::aptos_logger::Logger::init_for_testing(); + let (mut mock_network, _, client, _) = MockNetwork::new(None, None, None); + + let bad_peer = mock_network.add_peer(true); + + // Bypass poller and just add the storage summaries directly. + // Bad peer advertises txns 0 -> 200 (but can't actually service). + client.update_summary(bad_peer, utils::create_storage_summary(200)); + client.update_global_summary_cache().unwrap(); + + // Spawn a handler for both peers. + tokio::spawn(async move { + while let Some(network_request) = mock_network.next_request().await { + let data_response = + DataResponse::TransactionsWithProof(TransactionListWithProof::new_empty()); + network_request + .response_sender + .send(Ok(StorageServiceResponse::new(data_response, true).unwrap())); + } + }); + + let mut seen_data_unavailable_err = false; + + // Sending a bunch of requests to the bad peer (that we later decide are bad). + let request_timeout = client.get_response_timeout_ms(); + for _ in 0..20 { + let result = client + .get_transactions_with_proof(200, 200, 200, false, request_timeout) + .await; + + // While the score is still decreasing, we should see a bunch of + // InternalError's. Once we see a `DataIsUnavailable` error, we should + // only see that error. + if !seen_data_unavailable_err { + match result { + Ok(response) => { + response.context.response_callback.notify_bad_response( + crate::interface::ResponseError::ProofVerificationError, + ); + }, + Err(Error::DataIsUnavailable(_)) => { + seen_data_unavailable_err = true; + }, + Err(_) => panic!("unexpected result: {:?}", result), + } + } else { + assert_matches!(result, Err(Error::DataIsUnavailable(_))); + } + } + + // Peer should eventually get ignored and we should consider this request + // range unserviceable. + assert!(seen_data_unavailable_err); + + // The global summary should no longer contain the bad peer's advertisement. + client.update_global_summary_cache().unwrap(); + let global_summary = client.get_global_data_summary(); + assert!(!global_summary + .advertised_data + .transactions + .contains(&CompleteDataRange::new(0, 200).unwrap())); +} + +#[tokio::test] +async fn bad_peer_is_eventually_added_back() { + ::aptos_logger::Logger::init_for_testing(); + let (mut mock_network, mock_time, client, poller) = MockNetwork::new(None, None, None); + + // Add a connected peer. + mock_network.add_peer(true); + + tokio::spawn(poller.start_poller()); + tokio::spawn(async move { + while let Some(network_request) = mock_network.next_request().await { + match network_request.storage_service_request.data_request { + DataRequest::GetTransactionsWithProof(_) => { + let data_response = + DataResponse::TransactionsWithProof(TransactionListWithProof::new_empty()); + network_request + .response_sender + .send(Ok(StorageServiceResponse::new( + data_response, + network_request.storage_service_request.use_compression, + ) + .unwrap())); + }, + DataRequest::GetStorageServerSummary => { + let data_response = + DataResponse::StorageServerSummary(utils::create_storage_summary(200)); + network_request + .response_sender + .send(Ok(StorageServiceResponse::new( + data_response, + network_request.storage_service_request.use_compression, + ) + .unwrap())); + }, + _ => panic!( + "Unexpected storage request: {:?}", + network_request.storage_service_request + ), + } + } + }); + + // Advance time so the poller sends data summary requests. + let summary_poll_interval = Duration::from_millis(1_000); + for _ in 0..2 { + tokio::task::yield_now().await; + mock_time.advance_async(summary_poll_interval).await; + } + + // Initially this request range is serviceable by this peer. + let global_summary = client.get_global_data_summary(); + assert!(global_summary + .advertised_data + .transactions + .contains(&CompleteDataRange::new(0, 200).unwrap())); + + // Keep decreasing this peer's score by considering its responses bad. + // Eventually its score drops below IGNORE_PEER_THRESHOLD. + let request_timeout = client.get_response_timeout_ms(); + for _ in 0..20 { + let result = client + .get_transactions_with_proof(200, 0, 200, false, request_timeout) + .await; + + if let Ok(response) = result { + response + .context + .response_callback + .notify_bad_response(crate::interface::ResponseError::ProofVerificationError); + } + } + + // Peer is eventually ignored and this request range unserviceable. + client.update_global_summary_cache().unwrap(); + let global_summary = client.get_global_data_summary(); + assert!(!global_summary + .advertised_data + .transactions + .contains(&CompleteDataRange::new(0, 200).unwrap())); + + // This peer still responds to the StorageServerSummary requests. + // Its score keeps increasing and this peer is eventually added back. + for _ in 0..20 { + mock_time.advance_async(summary_poll_interval).await; + } + + let global_summary = client.get_global_data_summary(); + assert!(global_summary + .advertised_data + .transactions + .contains(&CompleteDataRange::new(0, 200).unwrap())); +} + +#[tokio::test(flavor = "multi_thread")] +async fn disconnected_peers_garbage_collection() { + ::aptos_logger::Logger::init_for_testing(); + let (mut mock_network, _, client, _) = MockNetwork::new(None, None, None); + + // Connect several peers + let priority_peer_1 = mock_network.add_peer(true); + let priority_peer_2 = mock_network.add_peer(true); + let priority_peer_3 = mock_network.add_peer(true); + + // Poll all of the peers to initialize the peer states + let all_peers = vec![priority_peer_1, priority_peer_2, priority_peer_3]; + poll_peers(&mut mock_network, &client, all_peers.clone()).await; + + // Verify we have peer states for all peers + verify_peer_states(&client, all_peers.clone()); + + // Disconnect priority peer 1 and update the global data summary + mock_network.disconnect_peer(priority_peer_1); + client.update_global_summary_cache().unwrap(); + + // Verify we have peer states for only the remaining peers + verify_peer_states(&client, vec![priority_peer_2, priority_peer_3]); + + // Disconnect priority peer 2 and update the global data summary + mock_network.disconnect_peer(priority_peer_2); + client.update_global_summary_cache().unwrap(); + + // Verify we have peer states for only priority peer 3 + verify_peer_states(&client, vec![priority_peer_3]); + + // Reconnect priority peer 1, poll it and update the global data summary + mock_network.reconnect_peer(priority_peer_1); + poll_peers(&mut mock_network, &client, vec![priority_peer_1]).await; + client.update_global_summary_cache().unwrap(); + + // Verify we have peer states for priority peer 1 and 3 + verify_peer_states(&client, vec![priority_peer_1, priority_peer_3]); + + // Reconnect priority peer 2, poll it and update the global data summary + mock_network.reconnect_peer(priority_peer_2); + poll_peers(&mut mock_network, &client, vec![priority_peer_2]).await; + client.update_global_summary_cache().unwrap(); + + // Verify we have peer states for all peers + verify_peer_states(&client, all_peers); +} + +/// A simple helper function that polls all the specified peers +/// and returns storage server summaries for each. +async fn poll_peers( + mock_network: &mut MockNetwork, + client: &AptosDataClient, + all_peers: Vec, +) { + for peer in all_peers { + // Poll the peer + let handle = poll_peer(client.clone(), peer, None); + + // Respond to the poll request + let network_request = mock_network.next_request().await.unwrap(); + let data_response = DataResponse::StorageServerSummary(StorageServerSummary::default()); + network_request + .response_sender + .send(Ok(StorageServiceResponse::new(data_response, true).unwrap())); + + // Wait for the poll to complete + handle.await.unwrap(); + } +} + +/// Verifies the exclusive existence of peer states for all the specified peers +fn verify_peer_states(client: &AptosDataClient, all_peers: Vec) { + let peer_to_states = client.get_peer_states().get_peer_to_states(); + for peer in &all_peers { + assert!(peer_to_states.contains_key(peer)); + } + assert_eq!(peer_to_states.len(), all_peers.len()); +} diff --git a/state-sync/aptos-data-client/src/tests/poller.rs b/state-sync/aptos-data-client/src/tests/poller.rs new file mode 100644 index 0000000000000..e59985b0acf95 --- /dev/null +++ b/state-sync/aptos-data-client/src/tests/poller.rs @@ -0,0 +1,413 @@ +// Copyright © Aptos Foundation +// SPDX-License-Identifier: Apache-2.0 + +use crate::{client::AptosDataClient, error::Error, poller::poll_peer, tests::mock::MockNetwork}; +use aptos_config::{config::AptosDataClientConfig, network_id::PeerNetworkId}; +use aptos_storage_service_types::StorageServiceError; +use claims::{assert_matches, assert_none}; + +#[tokio::test] +async fn fetch_peers_frequency() { + ::aptos_logger::Logger::init_for_testing(); + let (mut mock_network, _, client, poller) = MockNetwork::new(None, None, None); + + // Add regular peer 1 and 2 + let _regular_peer_1 = mock_network.add_peer(false); + let _regular_peer_2 = mock_network.add_peer(false); + + // Set `always_poll` to true and fetch the regular peers multiple times. Ensure + // that for each fetch we receive a peer. + let num_fetches = 20; + for _ in 0..num_fetches { + let peer = poller.fetch_regular_peer(true).unwrap(); + client.in_flight_request_complete(&peer); + } + + // Set `always_poll` to false and fetch the regular peers multiple times + let mut regular_peer_count = 0; + for _ in 0..num_fetches { + if let Some(peer) = poller.fetch_regular_peer(false) { + regular_peer_count += 1; + client.in_flight_request_complete(&peer); + } + } + + // Verify we received regular peers at a reduced frequency + assert!(regular_peer_count < num_fetches); + + // Add priority peer 1 and 2 + let _priority_peer_1 = mock_network.add_peer(true); + let _priority_peer_2 = mock_network.add_peer(true); + + // Fetch the prioritized peers multiple times. Ensure that for + // each fetch we receive a peer. + for _ in 0..num_fetches { + let peer = poller.try_fetch_peer(true).unwrap(); + client.in_flight_request_complete(&peer); + } +} + +#[tokio::test] +async fn fetch_peers_ordering() { + ::aptos_logger::Logger::init_for_testing(); + let (mut mock_network, _, client, _) = MockNetwork::new(None, None, None); + + // Ensure the properties hold for both priority and non-priority peers + for is_priority_peer in [true, false] { + // Add peer 1 + let peer_1 = mock_network.add_peer(is_priority_peer); + + // Request the next peer to poll and verify that we get peer 1 + for _ in 0..3 { + let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + assert_eq!(peer_to_poll, peer_1); + client.in_flight_request_complete(&peer_to_poll); + } + + // Add peer 2 + let peer_2 = mock_network.add_peer(is_priority_peer); + + // Request the next peer and verify we get either peer + let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + assert!(peer_to_poll == peer_1 || peer_to_poll == peer_2); + client.in_flight_request_complete(&peer_to_poll); + + // Request the next peer again, but don't mark the poll as complete + let peer_to_poll_1 = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + + // Request another peer again and verify that it's different to the previous peer + let peer_to_poll_2 = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + assert_ne!(peer_to_poll_1, peer_to_poll_2); + + // Neither poll has completed (they're both in-flight), so make another request + // and verify we get no peers. + assert_none!(fetch_peer_to_poll(client.clone(), is_priority_peer).unwrap()); + + // Add peer 3 + let peer_3 = mock_network.add_peer(is_priority_peer); + + // Request another peer again and verify it's peer_3 + let peer_to_poll_3 = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + assert_eq!(peer_to_poll_3, peer_3); + + // Mark the second poll as completed + client.in_flight_request_complete(&peer_to_poll_2); + + // Make another request and verify we get peer 2 now (as it was ready) + let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + assert_eq!(peer_to_poll, peer_to_poll_2); + + // Mark the first poll as completed + client.in_flight_request_complete(&peer_to_poll_1); + + // Make another request and verify we get peer 1 now + let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + assert_eq!(peer_to_poll, peer_to_poll_1); + + // Mark the third poll as completed + client.in_flight_request_complete(&peer_to_poll_3); + + // Make another request and verify we get peer 3 now + let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + assert_eq!(peer_to_poll, peer_to_poll_3); + client.in_flight_request_complete(&peer_to_poll_3); + } +} + +#[tokio::test] +async fn fetch_peers_disconnect() { + ::aptos_logger::Logger::init_for_testing(); + let (mut mock_network, _, client, _) = MockNetwork::new(None, None, None); + + // Ensure the properties hold for both priority and non-priority peers + for is_priority_peer in [true, false] { + // Request the next peer to poll and verify we have no peers + assert_matches!( + fetch_peer_to_poll(client.clone(), is_priority_peer), + Err(Error::DataIsUnavailable(_)) + ); + + // Add peer 1 + let peer_1 = mock_network.add_peer(is_priority_peer); + + // Request the next peer to poll and verify it's peer 1 + let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + assert_eq!(peer_to_poll, peer_1); + client.in_flight_request_complete(&peer_to_poll); + + // Add peer 2 and disconnect peer 1 + let peer_2 = mock_network.add_peer(is_priority_peer); + mock_network.disconnect_peer(peer_1); + + // Request the next peer to poll and verify it's peer 2 + let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + assert_eq!(peer_to_poll, peer_2); + client.in_flight_request_complete(&peer_to_poll); + + // Disconnect peer 2 + mock_network.disconnect_peer(peer_2); + + // Request the next peer to poll and verify an error is returned because + // there are no connected peers. + assert_matches!( + fetch_peer_to_poll(client.clone(), is_priority_peer), + Err(Error::DataIsUnavailable(_)) + ); + + // Add peer 3 + let peer_3 = mock_network.add_peer(is_priority_peer); + + // Request the next peer to poll and verify it's peer 3 + let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + assert_eq!(peer_to_poll, peer_3); + client.in_flight_request_complete(&peer_to_poll); + + // Disconnect peer 3 + mock_network.disconnect_peer(peer_3); + + // Request the next peer to poll and verify an error is returned because + // there are no connected peers. + assert_matches!( + fetch_peer_to_poll(client.clone(), is_priority_peer), + Err(Error::DataIsUnavailable(_)) + ); + } +} + +#[tokio::test] +async fn fetch_peers_reconnect() { + ::aptos_logger::Logger::init_for_testing(); + let (mut mock_network, _, client, _) = MockNetwork::new(None, None, None); + + // Ensure the properties hold for both priority and non-priority peers + for is_priority_peer in [true, false] { + // Request the next peer to poll and verify we have no peers + assert_matches!( + fetch_peer_to_poll(client.clone(), is_priority_peer), + Err(Error::DataIsUnavailable(_)) + ); + + // Add peer 1 + let peer_1 = mock_network.add_peer(is_priority_peer); + + // Request the next peer to poll and verify it's peer 1 + let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + assert_eq!(peer_to_poll, peer_1); + client.in_flight_request_complete(&peer_to_poll); + + // Add peer 2 and disconnect peer 1 + let peer_2 = mock_network.add_peer(is_priority_peer); + mock_network.disconnect_peer(peer_1); + + // Request the next peer to poll and verify it's peer 2 + let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + assert_eq!(peer_to_poll, peer_2); + client.in_flight_request_complete(&peer_to_poll); + + // Disconnect peer 2 and reconnect peer 1 + mock_network.disconnect_peer(peer_2); + mock_network.reconnect_peer(peer_1); + + // Request the next peer to poll and verify it's peer 1 + let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + assert_eq!(peer_to_poll, peer_1); + + // Reconnect peer 2 + mock_network.reconnect_peer(peer_2); + + // Request the next peer to poll several times and verify it's peer 2 + // (the in-flight request for peer 1 has yet to complete). + for _ in 0..3 { + let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + assert_eq!(peer_to_poll, peer_2); + client.in_flight_request_complete(&peer_to_poll); + } + + // Disconnect peer 2 and mark peer 1's in-flight request as complete + mock_network.disconnect_peer(peer_2); + client.in_flight_request_complete(&peer_1); + + // Request the next peer to poll several times and verify it's peer 1 + for _ in 0..3 { + let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + assert_eq!(peer_to_poll, peer_1); + client.in_flight_request_complete(&peer_to_poll); + } + + // Disconnect peer 1 + mock_network.disconnect_peer(peer_1); + + // Request the next peer to poll and verify an error is returned because + // there are no connected peers. + assert_matches!( + fetch_peer_to_poll(client.clone(), is_priority_peer), + Err(Error::DataIsUnavailable(_)) + ); + } +} + +#[tokio::test] +async fn fetch_peers_max_in_flight() { + ::aptos_logger::Logger::init_for_testing(); + + // Create a data client with max in-flight requests of 2 + let data_client_config = AptosDataClientConfig { + max_num_in_flight_priority_polls: 2, + max_num_in_flight_regular_polls: 2, + ..Default::default() + }; + let (mut mock_network, _, client, _) = MockNetwork::new(None, Some(data_client_config), None); + + // Ensure the properties hold for both priority and non-priority peers + for is_priority_peer in [true, false] { + // Add peer 1 + let peer_1 = mock_network.add_peer(is_priority_peer); + + // Request the next peer to poll and verify it's peer 1 + let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + assert_eq!(peer_to_poll, peer_1); + + // Add peer 2 + let peer_2 = mock_network.add_peer(is_priority_peer); + + // Request the next peer to poll and verify it's peer 2 (peer 1's in-flight + // request has not yet completed). + let peer_to_poll = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + assert_eq!(peer_to_poll, peer_2); + + // Add peer 3 + let peer_3 = mock_network.add_peer(is_priority_peer); + + // Request the next peer to poll and verify it's empty (we already have + // the maximum number of in-flight requests). + assert_none!(fetch_peer_to_poll(client.clone(), is_priority_peer).unwrap()); + + // Mark peer 2's in-flight request as complete + client.in_flight_request_complete(&peer_2); + + // Request the next peer to poll and verify it's either peer 2 or peer 3 + let peer_to_poll_1 = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + assert!(peer_to_poll_1 == peer_2 || peer_to_poll_1 == peer_3); + + // Request the next peer to poll and verify it's empty (we already have + // the maximum number of in-flight requests). + assert_none!(fetch_peer_to_poll(client.clone(), is_priority_peer).unwrap()); + + // Mark peer 1's in-flight request as complete + client.in_flight_request_complete(&peer_1); + + // Request the next peer to poll and verify it's not the peer that already + // has an in-flight request. + let peer_to_poll_2 = fetch_peer_to_poll(client.clone(), is_priority_peer) + .unwrap() + .unwrap(); + assert_ne!(peer_to_poll_1, peer_to_poll_2); + } +} + +#[tokio::test(flavor = "multi_thread")] +async fn in_flight_error_handling() { + ::aptos_logger::Logger::init_for_testing(); + + // Create a data client with max in-flight requests of 1 + let data_client_config = AptosDataClientConfig { + max_num_in_flight_priority_polls: 1, + max_num_in_flight_regular_polls: 1, + ..Default::default() + }; + let (mut mock_network, _, client, _) = MockNetwork::new(None, Some(data_client_config), None); + + // Verify we have no in-flight polls + let num_in_flight_polls = get_num_in_flight_polls(client.clone(), true); + assert_eq!(num_in_flight_polls, 0); + + // Add a peer + let peer = mock_network.add_peer(true); + + // Poll the peer + client.in_flight_request_started(&peer); + let handle = poll_peer(client.clone(), peer, None); + + // Respond to the peer poll with an error + if let Some(network_request) = mock_network.next_request().await { + network_request + .response_sender + .send(Err(StorageServiceError::InternalError( + "An unexpected error occurred!".into(), + ))); + } + + // Wait for the poller to complete + handle.await.unwrap(); + + // Verify we have no in-flight polls + let num_in_flight_polls = get_num_in_flight_polls(client.clone(), true); + assert_eq!(num_in_flight_polls, 0); +} + +/// A helper method that fetches peers to poll depending on the peer priority +fn fetch_peer_to_poll( + client: AptosDataClient, + is_priority_peer: bool, +) -> Result, Error> { + // Fetch the next peer to poll + let result = if is_priority_peer { + client.fetch_prioritized_peer_to_poll() + } else { + client.fetch_regular_peer_to_poll() + }; + + // If we get a peer, mark the peer as having an in-flight request + if let Ok(Some(peer_to_poll)) = result { + client.in_flight_request_started(&peer_to_poll); + } + + result +} + +/// Fetches the number of in flight requests for peers depending on priority +fn get_num_in_flight_polls(client: AptosDataClient, is_priority_peer: bool) -> u64 { + if is_priority_peer { + client.get_peer_states().num_in_flight_priority_polls() + } else { + client.get_peer_states().num_in_flight_regular_polls() + } +} diff --git a/state-sync/aptos-data-client/src/tests/priority.rs b/state-sync/aptos-data-client/src/tests/priority.rs new file mode 100644 index 0000000000000..9a3f54a90a377 --- /dev/null +++ b/state-sync/aptos-data-client/src/tests/priority.rs @@ -0,0 +1,322 @@ +// Copyright © Aptos Foundation +// SPDX-License-Identifier: Apache-2.0 + +use crate::{ + error::Error, + tests::{mock::MockNetwork, utils}, +}; +use aptos_config::{ + config::{BaseConfig, RoleType}, + network_id::NetworkId, +}; +use aptos_storage_service_types::{ + requests::{ + DataRequest, NewTransactionOutputsWithProofRequest, NewTransactionsWithProofRequest, + StorageServiceRequest, TransactionOutputsWithProofRequest, + }, + responses::OPTIMISTIC_FETCH_VERSION_DELTA, +}; +use claims::assert_matches; + +#[tokio::test] +async fn all_peer_request_selection() { + ::aptos_logger::Logger::init_for_testing(); + let (mut mock_network, _, client, _) = MockNetwork::new(None, None, None); + + // Ensure no peers can service the given request (we have no connections) + let server_version_request = + StorageServiceRequest::new(DataRequest::GetServerProtocolVersion, true); + assert_matches!( + client.choose_peer_for_request(&server_version_request), + Err(Error::DataIsUnavailable(_)) + ); + + // Add a regular peer and verify the peer is selected as the recipient + let regular_peer_1 = mock_network.add_peer(false); + assert_eq!( + client.choose_peer_for_request(&server_version_request), + Ok(regular_peer_1) + ); + + // Add two prioritized peers + let priority_peer_1 = mock_network.add_peer(true); + let priority_peer_2 = mock_network.add_peer(true); + + // Request data that is not being advertised and verify we get an error + let output_data_request = + DataRequest::GetTransactionOutputsWithProof(TransactionOutputsWithProofRequest { + proof_version: 100, + start_version: 0, + end_version: 100, + }); + let storage_request = StorageServiceRequest::new(output_data_request, false); + assert_matches!( + client.choose_peer_for_request(&storage_request), + Err(Error::DataIsUnavailable(_)) + ); + + // Advertise the data for the regular peer and verify it is now selected + client.update_summary(regular_peer_1, utils::create_storage_summary(100)); + assert_eq!( + client.choose_peer_for_request(&storage_request), + Ok(regular_peer_1) + ); + + // Advertise the data for the priority peer and verify the priority peer is selected + client.update_summary(priority_peer_2, utils::create_storage_summary(100)); + let peer_for_request = client.choose_peer_for_request(&storage_request).unwrap(); + assert_eq!(peer_for_request, priority_peer_2); + + // Reconnect priority peer 1 and remove the advertised data for priority peer 2 + mock_network.reconnect_peer(priority_peer_1); + client.update_summary(priority_peer_2, utils::create_storage_summary(0)); + + // Request the data again and verify the regular peer is chosen + assert_eq!( + client.choose_peer_for_request(&storage_request), + Ok(regular_peer_1) + ); + + // Advertise the data for priority peer 1 and verify the priority peer is selected + client.update_summary(priority_peer_1, utils::create_storage_summary(100)); + let peer_for_request = client.choose_peer_for_request(&storage_request).unwrap(); + assert_eq!(peer_for_request, priority_peer_1); + + // Advertise the data for priority peer 2 and verify either priority peer is selected + client.update_summary(priority_peer_2, utils::create_storage_summary(100)); + let peer_for_request = client.choose_peer_for_request(&storage_request).unwrap(); + assert!(peer_for_request == priority_peer_1 || peer_for_request == priority_peer_2); +} + +#[tokio::test] +async fn prioritized_peer_request_selection() { + ::aptos_logger::Logger::init_for_testing(); + let (mut mock_network, _, client, _) = MockNetwork::new(None, None, None); + + // Ensure the properties hold for storage summary and version requests + let storage_summary_request = DataRequest::GetStorageServerSummary; + let get_version_request = DataRequest::GetServerProtocolVersion; + for data_request in [storage_summary_request, get_version_request] { + let storage_request = StorageServiceRequest::new(data_request, true); + + // Ensure no peers can service the request (we have no connections) + assert_matches!( + client.choose_peer_for_request(&storage_request), + Err(Error::DataIsUnavailable(_)) + ); + + // Add a regular peer and verify the peer is selected as the recipient + let regular_peer_1 = mock_network.add_peer(false); + assert_eq!( + client.choose_peer_for_request(&storage_request), + Ok(regular_peer_1) + ); + + // Add a priority peer and verify the peer is selected as the recipient + let priority_peer_1 = mock_network.add_peer(true); + assert_eq!( + client.choose_peer_for_request(&storage_request), + Ok(priority_peer_1) + ); + + // Disconnect the priority peer and verify the regular peer is now chosen + mock_network.disconnect_peer(priority_peer_1); + assert_eq!( + client.choose_peer_for_request(&storage_request), + Ok(regular_peer_1) + ); + + // Connect a new priority peer and verify it is now selected + let priority_peer_2 = mock_network.add_peer(true); + assert_eq!( + client.choose_peer_for_request(&storage_request), + Ok(priority_peer_2) + ); + + // Disconnect the priority peer and verify the regular peer is again chosen + mock_network.disconnect_peer(priority_peer_2); + assert_eq!( + client.choose_peer_for_request(&storage_request), + Ok(regular_peer_1) + ); + + // Disconnect the regular peer so that we no longer have any connections + mock_network.disconnect_peer(regular_peer_1); + } +} + +#[tokio::test] +async fn prioritized_peer_subscription_selection() { + ::aptos_logger::Logger::init_for_testing(); + let (mut mock_network, _, client, _) = MockNetwork::new(None, None, None); + + // Create test data + let known_version = 10000000; + let known_epoch = 10; + + // Ensure the properties hold for both subscription requests + let new_transactions_request = + DataRequest::GetNewTransactionsWithProof(NewTransactionsWithProofRequest { + known_version, + known_epoch, + include_events: false, + }); + let new_outputs_request = + DataRequest::GetNewTransactionOutputsWithProof(NewTransactionOutputsWithProofRequest { + known_version, + known_epoch, + }); + for data_request in [new_transactions_request, new_outputs_request] { + let storage_request = StorageServiceRequest::new(data_request, true); + + // Ensure no peers can service the request (we have no connections) + assert_matches!( + client.choose_peer_for_request(&storage_request), + Err(Error::DataIsUnavailable(_)) + ); + + // Add a regular peer and verify the peer cannot support the request + let regular_peer_1 = mock_network.add_peer(false); + assert_matches!( + client.choose_peer_for_request(&storage_request), + Err(Error::DataIsUnavailable(_)) + ); + + // Advertise the data for the regular peer and verify it is now selected + client.update_summary(regular_peer_1, utils::create_storage_summary(known_version)); + assert_eq!( + client.choose_peer_for_request(&storage_request), + Ok(regular_peer_1) + ); + + // Add a priority peer and verify the regular peer is selected + let priority_peer_1 = mock_network.add_peer(true); + assert_eq!( + client.choose_peer_for_request(&storage_request), + Ok(regular_peer_1) + ); + + // Advertise the data for the priority peer and verify it is now selected + client.update_summary( + priority_peer_1, + utils::create_storage_summary(known_version), + ); + assert_eq!( + client.choose_peer_for_request(&storage_request), + Ok(priority_peer_1) + ); + + // Update the priority peer to be too far behind and verify it is not selected + client.update_summary( + priority_peer_1, + utils::create_storage_summary(known_version - OPTIMISTIC_FETCH_VERSION_DELTA), + ); + assert_eq!( + client.choose_peer_for_request(&storage_request), + Ok(regular_peer_1) + ); + + // Update the regular peer to be too far behind and verify neither is selected + client.update_summary( + regular_peer_1, + utils::create_storage_summary(known_version - (OPTIMISTIC_FETCH_VERSION_DELTA * 2)), + ); + assert_matches!( + client.choose_peer_for_request(&storage_request), + Err(Error::DataIsUnavailable(_)) + ); + + // Disconnect the regular peer and verify neither is selected + mock_network.disconnect_peer(regular_peer_1); + assert_matches!( + client.choose_peer_for_request(&storage_request), + Err(Error::DataIsUnavailable(_)) + ); + + // Advertise the data for the priority peer and verify it is now selected again + client.update_summary( + priority_peer_1, + utils::create_storage_summary(known_version + 1000), + ); + assert_eq!( + client.choose_peer_for_request(&storage_request), + Ok(priority_peer_1) + ); + + // Disconnect the priority peer so that we no longer have any connections + mock_network.disconnect_peer(priority_peer_1); + } +} + +#[tokio::test] +async fn validator_peer_prioritization() { + ::aptos_logger::Logger::init_for_testing(); + + // Create a validator node + let base_config = BaseConfig { + role: RoleType::Validator, + ..Default::default() + }; + let (mut mock_network, _, client, _) = MockNetwork::new(Some(base_config), None, None); + + // Add a validator peer and ensure it's prioritized + let validator_peer = mock_network.add_peer_with_network_id(NetworkId::Validator, false); + let (priority_peers, regular_peers) = client.get_priority_and_regular_peers().unwrap(); + assert_eq!(priority_peers, vec![validator_peer]); + assert_eq!(regular_peers, vec![]); + + // Add a vfn peer and ensure it's not prioritized + let vfn_peer = mock_network.add_peer_with_network_id(NetworkId::Vfn, true); + let (priority_peers, regular_peers) = client.get_priority_and_regular_peers().unwrap(); + assert_eq!(priority_peers, vec![validator_peer]); + assert_eq!(regular_peers, vec![vfn_peer]); +} + +#[tokio::test] +async fn vfn_peer_prioritization() { + ::aptos_logger::Logger::init_for_testing(); + + // Create a validator fullnode + let base_config = BaseConfig { + role: RoleType::FullNode, + ..Default::default() + }; + let (mut mock_network, _, client, _) = MockNetwork::new(Some(base_config), None, None); + + // Add a validator peer and ensure it's prioritized + let validator_peer = mock_network.add_peer_with_network_id(NetworkId::Vfn, false); + let (priority_peers, regular_peers) = client.get_priority_and_regular_peers().unwrap(); + assert_eq!(priority_peers, vec![validator_peer]); + assert_eq!(regular_peers, vec![]); + + // Add a pfn peer and ensure it's not prioritized + let pfn_peer = mock_network.add_peer_with_network_id(NetworkId::Public, true); + let (priority_peers, regular_peers) = client.get_priority_and_regular_peers().unwrap(); + assert_eq!(priority_peers, vec![validator_peer]); + assert_eq!(regular_peers, vec![pfn_peer]); +} + +#[tokio::test] +async fn pfn_peer_prioritization() { + ::aptos_logger::Logger::init_for_testing(); + + // Create a public fullnode + let base_config = BaseConfig { + role: RoleType::FullNode, + ..Default::default() + }; + let (mut mock_network, _, client, _) = + MockNetwork::new(Some(base_config), None, Some(vec![NetworkId::Public])); + + // Add an inbound pfn peer and ensure it's not prioritized + let inbound_peer = mock_network.add_peer_with_network_id(NetworkId::Public, false); + let (priority_peers, regular_peers) = client.get_priority_and_regular_peers().unwrap(); + assert_eq!(priority_peers, vec![]); + assert_eq!(regular_peers, vec![inbound_peer]); + + // Add an outbound pfn peer and ensure it's prioritized + let outbound_peer = mock_network.add_peer_with_network_id(NetworkId::Public, true); + let (priority_peers, regular_peers) = client.get_priority_and_regular_peers().unwrap(); + assert_eq!(priority_peers, vec![outbound_peer]); + assert_eq!(regular_peers, vec![inbound_peer]); +} diff --git a/state-sync/aptos-data-client/src/tests/utils.rs b/state-sync/aptos-data-client/src/tests/utils.rs new file mode 100644 index 0000000000000..cef6e82104050 --- /dev/null +++ b/state-sync/aptos-data-client/src/tests/utils.rs @@ -0,0 +1,43 @@ +// Copyright © Aptos Foundation +// SPDX-License-Identifier: Apache-2.0 + +use aptos_crypto::HashValue; +use aptos_storage_service_types::responses::{ + CompleteDataRange, DataSummary, ProtocolMetadata, StorageServerSummary, +}; +use aptos_types::{ + aggregate_signature::AggregateSignature, + block_info::BlockInfo, + ledger_info::{LedgerInfo, LedgerInfoWithSignatures}, + transaction::Version, +}; + +/// Creates a test ledger info at the given version +fn create_ledger_info(version: Version) -> LedgerInfoWithSignatures { + LedgerInfoWithSignatures::new( + LedgerInfo::new( + BlockInfo::new(0, 0, HashValue::zero(), HashValue::zero(), version, 0, None), + HashValue::zero(), + ), + AggregateSignature::empty(), + ) +} + +/// Creates a test storage server summary at the given version +pub fn create_storage_summary(version: Version) -> StorageServerSummary { + StorageServerSummary { + protocol_metadata: ProtocolMetadata { + max_epoch_chunk_size: 1000, + max_state_chunk_size: 1000, + max_transaction_chunk_size: 1000, + max_transaction_output_chunk_size: 1000, + }, + data_summary: DataSummary { + synced_ledger_info: Some(create_ledger_info(version)), + epoch_ending_ledger_infos: None, + transactions: Some(CompleteDataRange::new(0, version).unwrap()), + transaction_outputs: Some(CompleteDataRange::new(0, version).unwrap()), + states: None, + }, + } +} From c522f80b1986543a0ab963eea8dccb1c7098b010 Mon Sep 17 00:00:00 2001 From: "Daniel Porteous (dport)" Date: Wed, 31 May 2023 16:36:03 +0100 Subject: [PATCH 002/200] Add support for setting installation path to CLI install script (#8446) --- developer-docs-site/static/scripts/install_cli.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/developer-docs-site/static/scripts/install_cli.py b/developer-docs-site/static/scripts/install_cli.py index 633926ae24713..3bce28e39a1b2 100644 --- a/developer-docs-site/static/scripts/install_cli.py +++ b/developer-docs-site/static/scripts/install_cli.py @@ -215,13 +215,13 @@ def __init__( version: Optional[str] = None, force: bool = False, accept_all: bool = False, - path: Optional[str] = None, + bin_dir: Optional[str] = None, ) -> None: self._version = version self._force = force self._accept_all = accept_all + self._bin_dir = Path(bin_dir).expanduser() if bin_dir else None - self._bin_dir = None self._release_info = None self._latest_release_info = None @@ -514,12 +514,17 @@ def main(): action="store_true", default=False, ) + parser.add_argument( + "--bin-dir", + help="If given, the CLI binary will be downloaded here instead", + ) args = parser.parse_args() installer = Installer( force=args.force, accept_all=args.accept_all or not is_interactive(), + bin_dir=args.bin_dir, ) try: From 3fe9436ef159a9cc603243faf7c07ddbac2ae9fb Mon Sep 17 00:00:00 2001 From: alnoki <43892045+alnoki@users.noreply.github.com> Date: Wed, 31 May 2023 19:07:16 +0200 Subject: [PATCH 003/200] Add check for empty vector during event emission (#8448) --- aptos-move/framework/aptos-framework/doc/multisig_account.md | 5 +++-- .../framework/aptos-framework/sources/multisig_account.move | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/aptos-move/framework/aptos-framework/doc/multisig_account.md b/aptos-move/framework/aptos-framework/doc/multisig_account.md index b4639d3dafd53..f39fa4f1293fb 100644 --- a/aptos-move/framework/aptos-framework/doc/multisig_account.md +++ b/aptos-move/framework/aptos-framework/doc/multisig_account.md @@ -1641,8 +1641,9 @@ maliciously alter the owners list. vector::length(owners) >= multisig_account_resource.num_signatures_required, error::invalid_state(ENOT_ENOUGH_OWNERS), ); - - emit_event(&mut multisig_account_resource.remove_owners_events, RemoveOwnersEvent { owners_removed }); + if (vector::length(&owners_removed) > 0) { + emit_event(&mut multisig_account_resource.remove_owners_events, RemoveOwnersEvent { owners_removed }); + } } diff --git a/aptos-move/framework/aptos-framework/sources/multisig_account.move b/aptos-move/framework/aptos-framework/sources/multisig_account.move index 92d170116e7b8..eec31bb2de51f 100644 --- a/aptos-move/framework/aptos-framework/sources/multisig_account.move +++ b/aptos-move/framework/aptos-framework/sources/multisig_account.move @@ -573,8 +573,9 @@ module aptos_framework::multisig_account { vector::length(owners) >= multisig_account_resource.num_signatures_required, error::invalid_state(ENOT_ENOUGH_OWNERS), ); - - emit_event(&mut multisig_account_resource.remove_owners_events, RemoveOwnersEvent { owners_removed }); + if (vector::length(&owners_removed) > 0) { + emit_event(&mut multisig_account_resource.remove_owners_events, RemoveOwnersEvent { owners_removed }); + } } /// Update the number of signatures required then remove owners, in a single operation. From cf26cc40dad78fe418307a2810961cb7e8168b4f Mon Sep 17 00:00:00 2001 From: perryjrandall Date: Wed, 31 May 2023 10:19:08 -0700 Subject: [PATCH 004/200] [devnet] Fix devnet update message link (#8375) Reported by community member @urkes#1518 Test plan: Click this link it works --- scripts/devnet_message.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/devnet_message.sh b/scripts/devnet_message.sh index d036f5b2a558d..5da0185b4105d 100755 --- a/scripts/devnet_message.sh +++ b/scripts/devnet_message.sh @@ -23,6 +23,6 @@ For upgrade, make sure you pulled the latest docker image, or build the rust bin - genesis.blob sha256: $GENESIS_SHA - waypoint: $WAYPOINT - Chain ID: $CHAIN_ID -You can follow the instructions here for upgrade: https://aptos.dev/tutorials/run-a-fullnode#update-fullnode-with-new-releases/ +You can follow the instructions here for upgrade: https://aptos.dev/nodes/full-node/update-fullnode-with-new-devnet-releases EOF From c320d2a6a6ab98e94551ec1ab915670a09f1ca76 Mon Sep 17 00:00:00 2001 From: Bo Wu Date: Fri, 26 May 2023 12:40:36 -0700 Subject: [PATCH 005/200] [doc] add aptos db restore tool page --- .../aptos-db-restore-images/image.png | Bin 0 -> 463719 bytes .../tools/aptos-cli-tool/aptos-db-restore.md | 68 ++++++++++++++++++ 2 files changed, 68 insertions(+) create mode 100644 developer-docs-site/docs/tools/aptos-cli-tool/aptos-db-restore-images/image.png create mode 100644 developer-docs-site/docs/tools/aptos-cli-tool/aptos-db-restore.md diff --git a/developer-docs-site/docs/tools/aptos-cli-tool/aptos-db-restore-images/image.png b/developer-docs-site/docs/tools/aptos-cli-tool/aptos-db-restore-images/image.png new file mode 100644 index 0000000000000000000000000000000000000000..4bb10a3abaccc4eaa5ac96766d9fb67011da0860 GIT binary patch literal 463719 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

`AWv!_w5UCoRsDoUM1}tQRJpY>kY`X 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 N7zH8spHStvbZD@dGhH#| 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�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 literal 0 HcmV?d00001 diff --git a/developer-docs-site/docs/tools/aptos-cli-tool/aptos-db-restore.md b/developer-docs-site/docs/tools/aptos-cli-tool/aptos-db-restore.md new file mode 100644 index 0000000000000..d10ac5afca2ff --- /dev/null +++ b/developer-docs-site/docs/tools/aptos-cli-tool/aptos-db-restore.md @@ -0,0 +1,68 @@ +# Aptos DB Restore Tools and Public Backup Files + +Since its launch in October 2022, the Aptos community has grown rapidly. As of May 2023, Aptos has 743G and 159G of data in testnet and mainnet, respectively. We expect the data to increase greatly as more transactions are submitted to the blockchain. Facing the large amount of data, we want to provide users with a way to achieve two goals: + +- Quickly bootstrap a database to start a new or failed node +- Efficiently recover data from any specific period + +Our DB restore tool enables you to use existing public backup files to restore the database on your local machine. These public backup files, which have cryptographic proof, are stored on both AWS and Google Cloud for public download. You can use these backup files, along with our restore tool, to restore your database to any historical range or to the latest version. + +## **Restore DB using the Public Backup Files** + +Our CLI supports restoring a database using backup files. It reads from the backup files and recreates the Aptos DB. We support two kinds of restore: (1) recreating a DB with minimal transaction history at a user-specified transaction version (or the latest version the backup has), and (2) restoring the database over a specific period. In addition to (1), this option also ensures that the recreated DB carries the ledger history of the user-designated version range. + +**Bootstrap DB** + +The command restores the database from the closest snapshot to the target version. This command can quickly restore a database to a target version, but it does not restore all the transaction history from the past. + +Here is an example command (note: depending on whether you use AWS or Google Cloud, you may need to follow the instructions to install [aws cli](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) or [gsutil](https://cloud.google.com/storage/docs/gsutil_install) as prerequisites): + +```bash +# This requires the follow prerequsites +# 1. aws cli or google gsutil installed +# 2. aptos cli 1.0.14 +# This command syncs to version 500000000 with transaction history from 500000000 onwards +aptos node bootstrap-db \ + --target-version 500000000 \ + --command-adapter-config /path/to/s3-public.yaml \ + --target-db-dir /path/to/local/db +``` + +The s3-public.yaml ([link](https://github.com/aptos-labs/aptos-networks/blob/main/testnet/backups/s3-public.yaml)) used in the command specifies the location of the public backup files mentioned above, as well as the commands used by our backup and restore tool to interact with S3. Additionally, you can use the public Google backup files as shown here [link](https://github.com/aptos-labs/aptos-networks/blob/main/testnet/backups/gcs.yaml). + +**Restoring a Database over a Specific Time Period** + +We also support restoring the database to a previous period in the past. The command will restore all transaction history (events, write sets, key-value pairs, etc.) within the specified period, along with the state Merkle tree at the target version. + +To use this command, you need to specify the `ledger-history-start-version` and `target-version` to indicate the period you are interested in. + +```bash +# This requires aws cli installed and aptos cli 1.0.14 +# This command syncs to version 155000000 with transaction history from 150000000 onwards +aptos node bootstrap-db \ + --ledger-history-start-version 150000000 \ + --target-version 155000000 + --command-adapter-config /path/to/s3-public.yaml \ + --target-db-dir /path/to/local/db +``` + +## **Public Backup Files** + +The backup files are created by continuously querying a local full node and storing the backup data in either local files or remote storage (eg: google clound, aws, azure, etc). + +The backup files consist of three types of data that can be used to reconstruct the blockchain DB: + +- epoch_ending: It contains the ledger_info at the ending block of each epoch since the genesis. This data can be used to prove the epoch's provenance from the genesis and validator set of each epoch +- state_snapshot: It contains a snapshot of the blockchain's state Merkle tree (SMT) and key values at certain version. +- transaction: It contains the raw transaction metadata, payload, the executed outputs of the transaction after VM, as well as the cryptographic proof of the transaction in the ledger history. + +Each type of data in the backup storage is organized in the following way. The metadata file in the metadata folder contains the range of each backup and the relative path to the backup folder. The backup contains a manifest file and all the actual chunked data files. + +![image.png](./aptos-db-restore-images/image.png) + +The Aptos Labs maintains a few publicly accessible database backups in Amazon S3 and Google Cloud Storage. You can access these data files as follows: + +| | AWS Backup Data | Google Cloud Backup Data | +| --- | --- | --- | +| Testnet | https://github.com/aptos-labs/aptos-networks/blob/main/testnet/backups/s3-public.yaml | https://github.com/aptos-labs/aptos-networks/blob/main/testnet/backups/gcs.yaml | +| Mainnet | https://github.com/aptos-labs/aptos-networks/blob/main/mainnet/backups/s3-public.yaml | https://github.com/aptos-labs/aptos-networks/blob/main/mainnet/backups/gcs.yaml | \ No newline at end of file From ee328ddb6ececdf5063014b902bb9f081e56835e Mon Sep 17 00:00:00 2001 From: David Wolinsky Date: Wed, 31 May 2023 11:21:37 -0700 Subject: [PATCH 006/200] [docs] add aptos-stdlib to docs site refs (#8452) --- developer-docs-site/src/components/MoveReference/index.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer-docs-site/src/components/MoveReference/index.tsx b/developer-docs-site/src/components/MoveReference/index.tsx index 69664cd406675..a7c393e1cd158 100644 --- a/developer-docs-site/src/components/MoveReference/index.tsx +++ b/developer-docs-site/src/components/MoveReference/index.tsx @@ -14,7 +14,7 @@ const branches = ["mainnet", "testnet", "devnet", "main"]; const branch_titles = ["Mainnet", "Testnet", "Devnet", "Main"]; -const frameworks = ["move-stdlib", "aptos-framework", "aptos-token", "aptos-token-objects"]; +const frameworks = ["move-stdlib", "aptos-stdlib", "aptos-framework", "aptos-token", "aptos-token-objects"]; const TopNav = ({ branch }: TopNavProps) => { const adjustBranch = (event) => { const params = new URLSearchParams(window.location.search); From f2b84c81dd815227c23e23d7629742f4283e6abe Mon Sep 17 00:00:00 2001 From: Teng Zhang Date: Wed, 31 May 2023 11:53:11 -0700 Subject: [PATCH 007/200] supply-properties (#8388) --- .../framework/aptos-framework/doc/coin.md | 237 +++++++++++++++--- .../aptos-framework/sources/coin.move | 48 +++- .../aptos-framework/sources/coin.spec.move | 29 +++ 3 files changed, 271 insertions(+), 43 deletions(-) diff --git a/aptos-move/framework/aptos-framework/doc/coin.md b/aptos-move/framework/aptos-framework/doc/coin.md index 2e511bee0c848..12c1cea63524f 100644 --- a/aptos-move/framework/aptos-framework/doc/coin.md +++ b/aptos-move/framework/aptos-framework/doc/coin.md @@ -16,6 +16,8 @@ This module provides the foundation for typesafe Coins. - [Struct `MintCapability`](#0x1_coin_MintCapability) - [Struct `FreezeCapability`](#0x1_coin_FreezeCapability) - [Struct `BurnCapability`](#0x1_coin_BurnCapability) +- [Resource `Ghost$supply`](#0x1_coin_Ghost$supply) +- [Resource `Ghost$aggregate_supply`](#0x1_coin_Ghost$aggregate_supply) - [Constants](#@Constants_0) - [Function `initialize_supply_config`](#0x1_coin_initialize_supply_config) - [Function `allow_supply_upgrades`](#0x1_coin_allow_supply_upgrades) @@ -278,7 +280,7 @@ Information about a specific coin type. Stored on the creator of the coin's acco be displayed to a user as 5.05 (505 / 10 ** 2).

-supply: option::Option<optional_aggregator::OptionalAggregator> +supply: option::Option<optional_aggregator::OptionalAggregator>
Amount of this coin type in existence. @@ -426,6 +428,60 @@ Capability required to burn coins. + + + + +## Resource `Ghost$supply` + + + +
struct Ghost$supply<CoinType> has copy, drop, store, key
+
+ + + +
+Fields + + +
+
+v: num +
+
+ +
+
+ + +
+ + + +## Resource `Ghost$aggregate_supply` + + + +
struct Ghost$aggregate_supply<CoinType> has copy, drop, store, key
+
+ + + +
+Fields + + +
+
+v: num +
+
+ +
+
+ +
@@ -732,8 +788,13 @@ Drains the aggregatable coin, setting it to zero and returning a standard coin. }; let amount = aggregator::read(&coin.value); assert!(amount <= MAX_U64, error::out_of_range(EAGGREGATABLE_COIN_VALUE_TOO_LARGE)); - + spec { + update aggregate_supply<CoinType> = aggregate_supply<CoinType> - amount; + }; aggregator::sub(&mut coin.value, amount); + spec { + update supply<CoinType> = supply<CoinType> + amount; + }; Coin<CoinType> { value: (amount as u64), } @@ -761,8 +822,14 @@ Merges coin into aggregatable coin ( 
public(friend) fun merge_aggregatable_coin<CoinType>(dst_coin: &mut AggregatableCoin<CoinType>, coin: Coin<CoinType>) {
+    spec {
+        update supply<CoinType> = supply<CoinType> - coin.value;
+    };
     let Coin { value } = coin;
     let amount = (value as u128);
+    spec {
+        update aggregate_supply<CoinType> = aggregate_supply<CoinType> + amount;
+    };
     aggregator::add(&mut dst_coin.value, amount);
 }
@@ -1006,11 +1073,11 @@ Returns the amount of coin in existence. 
public fun supply<CoinType>(): Option<u128> acquires CoinInfo {
-    let maybe_supply = &borrow_global<CoinInfo<CoinType>>(coin_address<CoinType>()).supply;
+    let maybe_supply = &borrow_global<CoinInfo<CoinType>>(coin_address<CoinType>()).supply;
     if (option::is_some(maybe_supply)) {
-        // We do track supply, in this case read from optional aggregator.
-        let supply = option::borrow(maybe_supply);
-        let value = optional_aggregator::read(supply);
+        // We do track supply, in this case read from optional aggregator.
+        let supply = option::borrow(maybe_supply);
+        let value = optional_aggregator::read(supply);
         option::some(value)
     } else {
         option::none()
@@ -1043,13 +1110,16 @@ The capability _cap should be passed as a reference to coin: Coin<CoinType>,
     _cap: &BurnCapability<CoinType>,
 ) acquires CoinInfo {
+    spec {
+        update supply<CoinType> = supply<CoinType> - coin.value;
+    };
     let Coin { value: amount } = coin;
     assert!(amount > 0, error::invalid_argument(EZERO_COIN_AMOUNT));
 
-    let maybe_supply = &mut borrow_global_mut<CoinInfo<CoinType>>(coin_address<CoinType>()).supply;
+    let maybe_supply = &mut borrow_global_mut<CoinInfo<CoinType>>(coin_address<CoinType>()).supply;
     if (option::is_some(maybe_supply)) {
-        let supply = option::borrow_mut(maybe_supply);
-        optional_aggregator::sub(supply, (amount as u128));
+        let supply = option::borrow_mut(maybe_supply);
+        optional_aggregator::sub(supply, (amount as u128));
     }
 }
@@ -1158,6 +1228,9 @@ a BurnCapability for 
public fun destroy_zero<CoinType>(zero_coin: Coin<CoinType>) {
+    spec {
+        update supply<CoinType> = supply<CoinType> - zero_coin.value;
+    };
     let Coin { value } = zero_coin;
     assert!(value == 0, error::invalid_argument(EDESTRUCTION_OF_NONZERO_TOKEN))
 }
@@ -1185,7 +1258,13 @@ Extracts amount from the passed-in public fun extract<CoinType>(coin: &mut Coin<CoinType>, amount: u64): Coin<CoinType> {
     assert!(coin.value >= amount, error::invalid_argument(EINSUFFICIENT_BALANCE));
+    spec {
+        update supply<CoinType> = supply<CoinType> - amount;
+    };
     coin.value = coin.value - amount;
+    spec {
+        update supply<CoinType> = supply<CoinType> + amount;
+    };
     Coin { value: amount }
 }
@@ -1212,7 +1291,13 @@ Extracts the entire amount from the passed-in c 
public fun extract_all<CoinType>(coin: &mut Coin<CoinType>): Coin<CoinType> {
     let total_value = coin.value;
+    spec {
+        update supply<CoinType> = supply<CoinType> - coin.value;
+    };
     coin.value = 0;
+    spec {
+        update supply<CoinType> = supply<CoinType> + total_value;
+    };
     Coin { value: total_value }
 }
@@ -1299,7 +1384,7 @@ available. 
public entry fun upgrade_supply<CoinType>(account: &signer) acquires CoinInfo, SupplyConfig {
     let account_addr = signer::address_of(account);
 
-    // Only coin creators can upgrade total supply.
+    // Only coin creators can upgrade total supply.
     assert!(
         coin_address<CoinType>() == account_addr,
         error::invalid_argument(ECOIN_INFO_ADDRESS_MISMATCH),
@@ -1311,13 +1396,13 @@ available.
         error::permission_denied(ECOIN_SUPPLY_UPGRADE_NOT_SUPPORTED)
     );
 
-    let maybe_supply = &mut borrow_global_mut<CoinInfo<CoinType>>(account_addr).supply;
+    let maybe_supply = &mut borrow_global_mut<CoinInfo<CoinType>>(account_addr).supply;
     if (option::is_some(maybe_supply)) {
-        let supply = option::borrow_mut(maybe_supply);
+        let supply = option::borrow_mut(maybe_supply);
 
-        // If supply is tracked and the current implementation uses an integer - upgrade.
-        if (!optional_aggregator::is_parallelizable(supply)) {
-            optional_aggregator::switch(supply);
+        // If supply is tracked and the current implementation uses an integer - upgrade.
+        if (!optional_aggregator::is_parallelizable(supply)) {
+            optional_aggregator::switch(supply);
         }
     }
 }
@@ -1434,7 +1519,7 @@ Same as initialize but supply can be initialized to parallelizable
         name,
         symbol,
         decimals,
-        supply: if (monitor_supply) { option::some(optional_aggregator::new(MAX_U128, parallelizable)) } else { option::none() },
+        supply: if (monitor_supply) { option::some(optional_aggregator::new(MAX_U128, parallelizable)) } else { option::none() },
     };
     move_to(account, coin_info);
 
@@ -1467,7 +1552,13 @@ to the sum of the two tokens (dst_coin and source_coin
     spec {
         assume dst_coin.value + source_coin.value <= MAX_U64;
     };
+    spec {
+        update supply<CoinType> = supply<CoinType> - source_coin.value;
+    };
     let Coin { value } = source_coin;
+    spec {
+        update supply<CoinType> = supply<CoinType> + value;
+    };
     dst_coin.value = dst_coin.value + value;
 }
@@ -1499,15 +1590,19 @@ Returns minted Coin. _cap: &MintCapability<CoinType>, ): Coin<CoinType> acquires CoinInfo { if (amount == 0) { - return zero<CoinType>() + return Coin<CoinType> { + value: 0 + } }; - let maybe_supply = &mut borrow_global_mut<CoinInfo<CoinType>>(coin_address<CoinType>()).supply; + let maybe_supply = &mut borrow_global_mut<CoinInfo<CoinType>>(coin_address<CoinType>()).supply; if (option::is_some(maybe_supply)) { - let supply = option::borrow_mut(maybe_supply); - optional_aggregator::add(supply, (amount as u128)); + let supply = option::borrow_mut(maybe_supply); + optional_aggregator::add(supply, (amount as u128)); + }; + spec { + update supply<CoinType> = supply<CoinType> + amount; }; - Coin<CoinType> { value: amount } } @@ -1670,6 +1765,9 @@ Create a new Coin<CoinType>public fun zero<CoinType>(): Coin<CoinType> { + spec { + update supply<CoinType> = supply<CoinType> + 0; + }; Coin<CoinType> { value: 0 } @@ -1762,6 +1860,65 @@ Destroy a burn capability. 
pragma verify = true;
+
+global supply<CoinType>: num;
+
+global aggregate_supply<CoinType>: num;
+apply TotalSupplyTracked<CoinType> to *<CoinType> except
+    initialize, initialize_internal, initialize_with_parallelizable_supply;
+apply TotalSupplyNoChange<CoinType> to *<CoinType> except mint,
+    burn, burn_from, initialize, initialize_internal, initialize_with_parallelizable_supply;
+
+ + + + + + + +
fun spec_fun_supply_tracked<CoinType>(val: u64, supply: Option<OptionalAggregator>): bool {
+   option::spec_is_some(supply) ==> val == optional_aggregator::optional_aggregator_value
+           (option::spec_borrow(supply))
+}
+
+ + + + + + + +
schema TotalSupplyTracked<CoinType> {
+    invariant spec_fun_supply_tracked<CoinType>(supply<CoinType> + aggregate_supply<CoinType>,
+                global<CoinInfo<CoinType>>(type_info::type_of<CoinType>().account_address).supply);
+}
+
+ + + + + + + +
fun spec_fun_supply_no_change<CoinType>(old_supply: Option<OptionalAggregator>,
+                                            supply: Option<OptionalAggregator>): bool {
+   option::spec_is_some(old_supply) ==> optional_aggregator::optional_aggregator_value
+       (option::spec_borrow(old_supply)) == optional_aggregator::optional_aggregator_value
+       (option::spec_borrow(supply))
+}
+
+ + + + + + + +
schema TotalSupplyNoChange<CoinType> {
+    let old_supply = global<CoinInfo<CoinType>>(type_info::type_of<CoinType>().account_address).supply;
+    let post supply = global<CoinInfo<CoinType>>(type_info::type_of<CoinType>().account_address).supply;
+    ensures spec_fun_supply_no_change<CoinType>(old_supply, supply);
+}
@@ -1987,7 +2144,7 @@ Get address by reflection. 
fun get_coin_supply_opt<CoinType>(): Option<OptionalAggregator> {
-   global<CoinInfo<CoinType>>(type_info::type_of<CoinType>().account_address).supply
+   global<CoinInfo<CoinType>>(type_info::type_of<CoinType>().account_address).supply
 }
@@ -2000,7 +2157,7 @@ Get address by reflection. 
schema AbortsIfAggregator<CoinType> {
     coin: Coin<CoinType>;
     let addr =  type_info::type_of<CoinType>().account_address;
-    let maybe_supply = global<CoinInfo<CoinType>>(addr).supply;
+    let maybe_supply = global<CoinInfo<CoinType>>(addr).supply;
     aborts_if option::is_some(maybe_supply) && optional_aggregator::is_parallelizable(option::borrow(maybe_supply))
         && aggregator::spec_aggregator_get_val(option::borrow(option::borrow(maybe_supply).aggregator)) <
         coin.value;
@@ -2085,9 +2242,9 @@ Get address by reflection.
 
 
let coin_addr = type_info::type_of<CoinType>().account_address;
 aborts_if !exists<CoinInfo<CoinType>>(coin_addr);
-let maybe_supply = global<CoinInfo<CoinType>>(coin_addr).supply;
-let supply = option::spec_borrow(maybe_supply);
-let value = optional_aggregator::optional_aggregator_value(supply);
+let maybe_supply = global<CoinInfo<CoinType>>(coin_addr).supply;
+let supply = option::spec_borrow(maybe_supply);
+let value = optional_aggregator::optional_aggregator_value(supply);
 ensures if (option::spec_is_some(maybe_supply)) {
     result == option::spec_some(value)
 } else {
@@ -2137,10 +2294,10 @@ Get address by reflection.
 aborts_if amount != 0 && !exists<CoinInfo<CoinType>>(addr);
 aborts_if amount != 0 && !exists<CoinStore<CoinType>>(account_addr);
 aborts_if coin_store.coin.value < amount;
-let maybe_supply = global<CoinInfo<CoinType>>(addr).supply;
-let supply = option::spec_borrow(maybe_supply);
-let value = optional_aggregator::optional_aggregator_value(supply);
-let post post_maybe_supply = global<CoinInfo<CoinType>>(addr).supply;
+let maybe_supply = global<CoinInfo<CoinType>>(addr).supply;
+let supply = option::spec_borrow(maybe_supply);
+let value = optional_aggregator::optional_aggregator_value(supply);
+let post post_maybe_supply = global<CoinInfo<CoinType>>(addr).supply;
 let post post_supply = option::spec_borrow(post_maybe_supply);
 let post post_value = optional_aggregator::optional_aggregator_value(post_supply);
 aborts_if option::spec_is_some(maybe_supply) && value < amount;
@@ -2300,14 +2457,14 @@ The creator of CoinType must be @aptos_framework.
 let supply_config = global<SupplyConfig>(@aptos_framework);
 aborts_if !supply_config.allow_upgrades;
 modifies global<CoinInfo<CoinType>>(account_addr);
-let maybe_supply = global<CoinInfo<CoinType>>(account_addr).supply;
-let supply = option::spec_borrow(maybe_supply);
-let value = optional_aggregator::optional_aggregator_value(supply);
-let post post_maybe_supply = global<CoinInfo<CoinType>>(account_addr).supply;
+let maybe_supply = global<CoinInfo<CoinType>>(account_addr).supply;
+let supply = option::spec_borrow(maybe_supply);
+let value = optional_aggregator::optional_aggregator_value(supply);
+let post post_maybe_supply = global<CoinInfo<CoinType>>(account_addr).supply;
 let post post_supply = option::spec_borrow(post_maybe_supply);
 let post post_value = optional_aggregator::optional_aggregator_value(post_supply);
 let supply_no_parallel = option::spec_is_some(maybe_supply) &&
-    !optional_aggregator::is_parallelizable(supply);
+    !optional_aggregator::is_parallelizable(supply);
 aborts_if supply_no_parallel && !exists<aggregator_factory::AggregatorFactory>(@aptos_framework);
 ensures supply_no_parallel ==>
     optional_aggregator::is_parallelizable(post_supply) && post_value == value;
@@ -2395,9 +2552,9 @@ Only the creator of CoinType can initialize.
 };
 let account_addr = signer::address_of(account);
 let post coin_info = global<CoinInfo<CoinType>>(account_addr);
-let post supply = option::spec_borrow(coin_info.supply);
-let post value = optional_aggregator::optional_aggregator_value(supply);
-let post limit = optional_aggregator::optional_aggregator_limit(supply);
+let post supply = option::spec_borrow(coin_info.supply);
+let post value = optional_aggregator::optional_aggregator_value(supply);
+let post limit = optional_aggregator::optional_aggregator_limit(supply);
 modifies global<CoinInfo<CoinType>>(account_addr);
 aborts_if monitor_supply && parallelizable
     && !exists<aggregator_factory::AggregatorFactory>(@aptos_framework);
@@ -2407,9 +2564,9 @@ Only the creator of CoinType can initialize.
     && coin_info.decimals == decimals;
 ensures if (monitor_supply) {
     value == 0 && limit == MAX_U128
-        && (parallelizable == optional_aggregator::is_parallelizable(supply))
+        && (parallelizable == optional_aggregator::is_parallelizable(supply))
 } else {
-    option::spec_is_none(coin_info.supply)
+    option::spec_is_none(coin_info.supply)
 };
 ensures result_1 == BurnCapability<CoinType> {};
 ensures result_2 == FreezeCapability<CoinType> {};
diff --git a/aptos-move/framework/aptos-framework/sources/coin.move b/aptos-move/framework/aptos-framework/sources/coin.move
index 7f7bcc2a734ef..d45751deeddb1 100644
--- a/aptos-move/framework/aptos-framework/sources/coin.move
+++ b/aptos-move/framework/aptos-framework/sources/coin.move
@@ -183,8 +183,13 @@ module aptos_framework::coin {
         };
         let amount = aggregator::read(&coin.value);
         assert!(amount <= MAX_U64, error::out_of_range(EAGGREGATABLE_COIN_VALUE_TOO_LARGE));
-
+        spec {
+            update aggregate_supply = aggregate_supply - amount;
+        };
         aggregator::sub(&mut coin.value, amount);
+        spec {
+            update supply = supply + amount;
+        };
         Coin {
             value: (amount as u64),
         }
@@ -192,8 +197,14 @@ module aptos_framework::coin {
 
     /// Merges `coin` into aggregatable coin (`dst_coin`).
     public(friend) fun merge_aggregatable_coin(dst_coin: &mut AggregatableCoin, coin: Coin) {
+        spec {
+            update supply = supply - coin.value;
+        };
         let Coin { value } = coin;
         let amount = (value as u128);
+        spec {
+            update aggregate_supply = aggregate_supply + amount;
+        };
         aggregator::add(&mut dst_coin.value, amount);
     }
 
@@ -286,6 +297,9 @@ module aptos_framework::coin {
         coin: Coin,
         _cap: &BurnCapability,
     ) acquires CoinInfo {
+        spec {
+            update supply = supply - coin.value;
+        };
         let Coin { value: amount } = coin;
         assert!(amount > 0, error::invalid_argument(EZERO_COIN_AMOUNT));
 
@@ -341,6 +355,9 @@ module aptos_framework::coin {
     /// so it is impossible to "burn" any non-zero amount of `Coin` without having
     /// a `BurnCapability` for the specific `CoinType`.
     public fun destroy_zero(zero_coin: Coin) {
+        spec {
+            update supply = supply - zero_coin.value;
+        };
         let Coin { value } = zero_coin;
         assert!(value == 0, error::invalid_argument(EDESTRUCTION_OF_NONZERO_TOKEN))
     }
@@ -348,14 +365,26 @@ module aptos_framework::coin {
     /// Extracts `amount` from the passed-in `coin`, where the original token is modified in place.
     public fun extract(coin: &mut Coin, amount: u64): Coin {
         assert!(coin.value >= amount, error::invalid_argument(EINSUFFICIENT_BALANCE));
+        spec {
+            update supply = supply - amount;
+        };
         coin.value = coin.value - amount;
+        spec {
+            update supply = supply + amount;
+        };
         Coin { value: amount }
     }
 
     /// Extracts the entire amount from the passed-in `coin`, where the original token is modified in place.
     public fun extract_all(coin: &mut Coin): Coin {
         let total_value = coin.value;
+        spec {
+            update supply = supply - coin.value;
+        };
         coin.value = 0;
+        spec {
+            update supply = supply + total_value;
+        };
         Coin { value: total_value }
     }
 
@@ -472,7 +501,13 @@ module aptos_framework::coin {
         spec {
             assume dst_coin.value + source_coin.value <= MAX_U64;
         };
+        spec {
+            update supply = supply - source_coin.value;
+        };
         let Coin { value } = source_coin;
+        spec {
+            update supply = supply + value;
+        };
         dst_coin.value = dst_coin.value + value;
     }
 
@@ -484,7 +519,9 @@ module aptos_framework::coin {
         _cap: &MintCapability,
     ): Coin acquires CoinInfo {
         if (amount == 0) {
-            return zero()
+            return Coin {
+                value: 0
+            }
         };
 
         let maybe_supply = &mut borrow_global_mut>(coin_address()).supply;
@@ -492,7 +529,9 @@ module aptos_framework::coin {
             let supply = option::borrow_mut(maybe_supply);
             optional_aggregator::add(supply, (amount as u128));
         };
-
+        spec {
+            update supply = supply + amount;
+        };
         Coin { value: amount }
     }
 
@@ -555,6 +594,9 @@ module aptos_framework::coin {
 
     /// Create a new `Coin` with a value of `0`.
     public fun zero(): Coin {
+        spec {
+            update supply = supply + 0;
+        };
         Coin {
             value: 0
         }
diff --git a/aptos-move/framework/aptos-framework/sources/coin.spec.move b/aptos-move/framework/aptos-framework/sources/coin.spec.move
index 410c44f7efee6..0aea237d0ced4 100644
--- a/aptos-move/framework/aptos-framework/sources/coin.spec.move
+++ b/aptos-move/framework/aptos-framework/sources/coin.spec.move
@@ -1,6 +1,35 @@
 spec aptos_framework::coin {
     spec module {
         pragma verify = true;
+        global supply: num;
+        global aggregate_supply: num;
+        apply TotalSupplyTracked to * except
+            initialize, initialize_internal, initialize_with_parallelizable_supply;
+        apply TotalSupplyNoChange to * except mint,
+            burn, burn_from, initialize, initialize_internal, initialize_with_parallelizable_supply;
+    }
+
+    spec fun spec_fun_supply_tracked(val: u64, supply: Option): bool {
+        option::spec_is_some(supply) ==> val == optional_aggregator::optional_aggregator_value
+                (option::spec_borrow(supply))
+    }
+
+    spec schema TotalSupplyTracked {
+        invariant spec_fun_supply_tracked(supply + aggregate_supply,
+                    global>(type_info::type_of().account_address).supply);
+    }
+
+    spec fun spec_fun_supply_no_change(old_supply: Option,
+                                                 supply: Option): bool {
+        option::spec_is_some(old_supply) ==> optional_aggregator::optional_aggregator_value
+            (option::spec_borrow(old_supply)) == optional_aggregator::optional_aggregator_value
+            (option::spec_borrow(supply))
+    }
+
+    spec schema TotalSupplyNoChange {
+        let old_supply = global>(type_info::type_of().account_address).supply;
+        let post supply = global>(type_info::type_of().account_address).supply;
+        ensures spec_fun_supply_no_change(old_supply, supply);
     }
 
     spec AggregatableCoin {

From 4beb914a168bd358ec375bfd9854cffaa271199a Mon Sep 17 00:00:00 2001
From: Jin <128556004+0xjinn@users.noreply.github.com>
Date: Wed, 31 May 2023 12:06:24 -0700
Subject: [PATCH 008/200] [CLI][Rest] added default custom header (#8368)

* added default custom header

* fixes on comments

* moved the client_builder to new file

* fixes from comment
---
 Cargo.lock                                    |   2 +
 aptos                                         |   1 +
 .../aptos-rest-client/src/client_builder.rs   | 101 ++++++++++++++++++
 crates/aptos-rest-client/src/lib.rs           |  59 ++++------
 crates/aptos/Cargo.toml                       |   1 +
 crates/aptos/src/common/types.rs              |  14 +--
 sdk/Cargo.toml                                |   1 +
 testsuite/forge/src/interface/node.rs         |   6 +-
 8 files changed, 140 insertions(+), 45 deletions(-)
 create mode 120000 aptos
 create mode 100644 crates/aptos-rest-client/src/client_builder.rs

diff --git a/Cargo.lock b/Cargo.lock
index 43d5c8692d643..57cff9fada9a5 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -145,6 +145,7 @@ name = "aptos"
 version = "1.0.14"
 dependencies = [
  "anyhow",
+ "aptos-api-types",
  "aptos-backup-cli",
  "aptos-bitvec",
  "aptos-build-info",
@@ -2696,6 +2697,7 @@ name = "aptos-sdk"
 version = "0.0.3"
 dependencies = [
  "anyhow",
+ "aptos-api-types",
  "aptos-cached-packages",
  "aptos-crypto",
  "aptos-global-constants",
diff --git a/aptos b/aptos
new file mode 120000
index 0000000000000..5089ff4552742
--- /dev/null
+++ b/aptos
@@ -0,0 +1 @@
+target/debug/aptos
\ No newline at end of file
diff --git a/crates/aptos-rest-client/src/client_builder.rs b/crates/aptos-rest-client/src/client_builder.rs
new file mode 100644
index 0000000000000..e04228566e584
--- /dev/null
+++ b/crates/aptos-rest-client/src/client_builder.rs
@@ -0,0 +1,101 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::{
+    get_version_path_with_base, Client, DEFAULT_VERSION_PATH_BASE, X_APTOS_SDK_HEADER_VALUE,
+};
+use anyhow::Result;
+use aptos_api_types::X_APTOS_CLIENT;
+use reqwest::{
+    header::{HeaderMap, HeaderName, HeaderValue},
+    Client as ReqwestClient, ClientBuilder as ReqwestClientBuilder,
+};
+use std::{str::FromStr, time::Duration};
+use url::Url;
+
+pub enum AptosBaseUrl {
+    Mainnet,
+    Devnet,
+    Testnet,
+    Custom(Url),
+}
+
+impl AptosBaseUrl {
+    pub fn to_url(&self) -> Url {
+        match self {
+            AptosBaseUrl::Mainnet => {
+                Url::from_str("https://fullnode.mainnet.aptoslabs.com").unwrap()
+            },
+            AptosBaseUrl::Devnet => Url::from_str("https://fullnode.devnet.aptoslabs.com").unwrap(),
+            AptosBaseUrl::Testnet => {
+                Url::from_str("https://fullnode.testnet.aptoslabs.com").unwrap()
+            },
+            AptosBaseUrl::Custom(url) => url.to_owned(),
+        }
+    }
+}
+
+pub struct ClientBuilder {
+    reqwest_builder: ReqwestClientBuilder,
+    version_path_base: String,
+    base_url: Url,
+    timeout: Duration,
+    headers: HeaderMap,
+}
+
+impl ClientBuilder {
+    pub fn new(aptos_base_url: AptosBaseUrl) -> Self {
+        let mut headers = HeaderMap::new();
+        headers.insert(
+            X_APTOS_CLIENT,
+            HeaderValue::from_static(X_APTOS_SDK_HEADER_VALUE),
+        );
+
+        Self {
+            reqwest_builder: ReqwestClient::builder(),
+            base_url: aptos_base_url.to_url(),
+            version_path_base: DEFAULT_VERSION_PATH_BASE.to_string(),
+            timeout: Duration::from_secs(10), // Default to 10 seconds
+            headers,
+        }
+    }
+
+    pub fn base_url(mut self, base_url: Url) -> Self {
+        self.base_url = base_url;
+        self
+    }
+
+    pub fn timeout(mut self, timeout: Duration) -> Self {
+        self.timeout = timeout;
+        self
+    }
+
+    pub fn header(mut self, header_key: &str, header_val: &str) -> Result {
+        self.headers.insert(
+            HeaderName::from_str(header_key)?,
+            HeaderValue::from_str(header_val)?,
+        );
+        Ok(self)
+    }
+
+    pub fn version_path_base(mut self, version_path_base: String) -> Self {
+        self.version_path_base = version_path_base;
+        self
+    }
+
+    pub fn build(self) -> Client {
+        let version_path_base = get_version_path_with_base(self.base_url.clone());
+
+        Client {
+            inner: self
+                .reqwest_builder
+                .default_headers(self.headers)
+                .timeout(self.timeout)
+                .cookie_store(true)
+                .build()
+                .unwrap(),
+            base_url: self.base_url,
+            version_path_base,
+        }
+    }
+}
diff --git a/crates/aptos-rest-client/src/lib.rs b/crates/aptos-rest-client/src/lib.rs
index 790fad31c18ee..1a6f653636f47 100644
--- a/crates/aptos-rest-client/src/lib.rs
+++ b/crates/aptos-rest-client/src/lib.rs
@@ -10,9 +10,11 @@ pub mod faucet;
 pub use faucet::FaucetClient;
 pub mod response;
 pub use response::Response;
+pub mod client_builder;
 pub mod state;
 pub mod types;
 
+pub use crate::client_builder::{AptosBaseUrl, ClientBuilder};
 use crate::{
     aptos::{AptosVersion, Balance},
     error::RestError,
@@ -50,7 +52,6 @@ use tokio::time::Instant;
 pub use types::{deserialize_from_prefixed_hex_string, Account, Resource};
 use url::Url;
 
-pub const USER_AGENT: &str = concat!("aptos-client-sdk-rust / ", env!("CARGO_PKG_VERSION"));
 pub const DEFAULT_VERSION_PATH_BASE: &str = "v1/";
 const DEFAULT_MAX_WAIT_MS: u64 = 60000;
 const DEFAULT_INTERVAL_MS: u64 = 1000;
@@ -59,6 +60,7 @@ static DEFAULT_INTERVAL_DURATION: Duration = Duration::from_millis(DEFAULT_INTER
 const DEFAULT_MAX_SERVER_LAG_WAIT_DURATION: Duration = Duration::from_secs(60);
 const RESOURCES_PER_CALL_PAGINATION: u64 = 9999;
 const MODULES_PER_CALL_PAGINATION: u64 = 1000;
+const X_APTOS_SDK_HEADER_VALUE: &str = concat!("aptos-rust-sdk/", env!("CARGO_PKG_VERSION"));
 
 type AptosResult = Result;
 
@@ -70,45 +72,12 @@ pub struct Client {
 }
 
 impl Client {
-    pub fn new_with_timeout(base_url: Url, timeout: Duration) -> Self {
-        Client::new_with_timeout_and_user_agent(base_url, timeout, USER_AGENT)
-    }
-
-    pub fn new_with_timeout_and_user_agent(
-        base_url: Url,
-        timeout: Duration,
-        user_agent: &str,
-    ) -> Self {
-        let inner = ReqwestClient::builder()
-            .timeout(timeout)
-            .user_agent(user_agent)
-            .cookie_store(true)
-            .build()
-            .unwrap();
-
-        // If the user provided no version in the path, use the default. If the
-        // provided version has no trailing slash, add it, otherwise url.join
-        // will ignore the version path base.
-        let version_path_base = match base_url.path() {
-            "/" => DEFAULT_VERSION_PATH_BASE.to_string(),
-            path => {
-                if !path.ends_with('/') {
-                    format!("{}/", path)
-                } else {
-                    path.to_string()
-                }
-            },
-        };
-
-        Self {
-            inner,
-            base_url,
-            version_path_base,
-        }
+    pub fn builder(aptos_base_url: AptosBaseUrl) -> ClientBuilder {
+        ClientBuilder::new(aptos_base_url)
     }
 
     pub fn new(base_url: Url) -> Self {
-        Self::new_with_timeout(base_url, Duration::from_secs(10))
+        Self::builder(AptosBaseUrl::Custom(base_url)).build()
     }
 
     pub fn path_prefix_string(&self) -> String {
@@ -1583,6 +1552,22 @@ impl Client {
     }
 }
 
+// If the user provided no version in the path, use the default. If the
+// provided version has no trailing slash, add it, otherwise url.join
+// will ignore the version path base.
+pub fn get_version_path_with_base(base_url: Url) -> String {
+    match base_url.path() {
+        "/" => DEFAULT_VERSION_PATH_BASE.to_string(),
+        path => {
+            if !path.ends_with('/') {
+                format!("{}/", path)
+            } else {
+                path.to_string()
+            }
+        },
+    }
+}
+
 pub fn retriable_with_404(status_code: StatusCode, aptos_error: Option) -> bool {
     retriable(status_code, aptos_error) | matches!(status_code, StatusCode::NOT_FOUND)
 }
diff --git a/crates/aptos/Cargo.toml b/crates/aptos/Cargo.toml
index f601f45b0a484..4c67963644648 100644
--- a/crates/aptos/Cargo.toml
+++ b/crates/aptos/Cargo.toml
@@ -14,6 +14,7 @@ rust-version = { workspace = true }
 
 [dependencies]
 anyhow = { workspace = true }
+aptos-api-types = { workspace = true }
 aptos-backup-cli = { workspace = true }
 aptos-bitvec = { workspace = true }
 aptos-build-info = { workspace = true }
diff --git a/crates/aptos/src/common/types.rs b/crates/aptos/src/common/types.rs
index 449459999fb8c..f9dec4dc79c06 100644
--- a/crates/aptos/src/common/types.rs
+++ b/crates/aptos/src/common/types.rs
@@ -29,7 +29,7 @@ use aptos_logger::Level;
 use aptos_rest_client::{
     aptos_api_types::{EntryFunctionId, HashValue, MoveType, ViewRequest},
     error::RestError,
-    Client, Transaction,
+    AptosBaseUrl, Client, Transaction,
 };
 use aptos_sdk::{transaction_builder::TransactionFactory, types::LocalAccount};
 use aptos_types::{
@@ -63,6 +63,9 @@ const ACCEPTED_CLOCK_SKEW_US: u64 = 5 * US_IN_SECS;
 pub const DEFAULT_EXPIRATION_SECS: u64 = 30;
 pub const DEFAULT_PROFILE: &str = "default";
 
+// Custom header value to identify the client
+const X_APTOS_CLIENT_VALUE: &str = concat!("aptos-cli/", env!("CARGO_PKG_VERSION"));
+
 /// A common result to be returned to users
 pub type CliResult = Result;
 
@@ -905,11 +908,10 @@ impl RestOptions {
     }
 
     pub fn client(&self, profile: &ProfileOptions) -> CliTypedResult {
-        Ok(Client::new_with_timeout_and_user_agent(
-            self.url(profile)?,
-            Duration::from_secs(self.connection_timeout_secs),
-            USER_AGENT,
-        ))
+        Ok(Client::builder(AptosBaseUrl::Custom(self.url(profile)?))
+            .timeout(Duration::from_secs(self.connection_timeout_secs))
+            .header(aptos_api_types::X_APTOS_CLIENT, X_APTOS_CLIENT_VALUE)?
+            .build())
     }
 }
 
diff --git a/sdk/Cargo.toml b/sdk/Cargo.toml
index a183e66394ab6..0f326eb95452b 100644
--- a/sdk/Cargo.toml
+++ b/sdk/Cargo.toml
@@ -14,6 +14,7 @@ rust-version = { workspace = true }
 
 [dependencies]
 anyhow = { workspace = true }
+aptos-api-types = { workspace = true }
 aptos-cached-packages = { workspace = true }
 aptos-crypto = { workspace = true }
 aptos-global-constants = { workspace = true }
diff --git a/testsuite/forge/src/interface/node.rs b/testsuite/forge/src/interface/node.rs
index 56c32396a4566..d969e04190d10 100644
--- a/testsuite/forge/src/interface/node.rs
+++ b/testsuite/forge/src/interface/node.rs
@@ -6,7 +6,7 @@ use crate::{Result, Version};
 use anyhow::anyhow;
 use aptos_config::{config::NodeConfig, network_id::NetworkId};
 use aptos_inspection_service::inspection_client::InspectionClient;
-use aptos_rest_client::Client as RestClient;
+use aptos_rest_client::{AptosBaseUrl, Client as RestClient};
 use aptos_sdk::types::PeerId;
 use std::{
     collections::HashMap,
@@ -144,7 +144,9 @@ pub trait NodeExt: Node {
 
     /// Return REST API client of this Node
     fn rest_client_with_timeout(&self, timeout: Duration) -> RestClient {
-        RestClient::new_with_timeout(self.rest_api_endpoint(), timeout)
+        RestClient::builder(AptosBaseUrl::Custom(self.rest_api_endpoint()))
+            .timeout(timeout)
+            .build()
     }
 
     /// Return an InspectionClient for this Node

From 82cebdfd785a976aa06c4570b1739e5f57cb3eb3 Mon Sep 17 00:00:00 2001
From: perryjrandall 
Date: Wed, 31 May 2023 16:21:36 -0700
Subject: [PATCH 009/200] [revert] Revert added symlink (#8456)

---
 aptos | 1 -
 1 file changed, 1 deletion(-)
 delete mode 120000 aptos

diff --git a/aptos b/aptos
deleted file mode 120000
index 5089ff4552742..0000000000000
--- a/aptos
+++ /dev/null
@@ -1 +0,0 @@
-target/debug/aptos
\ No newline at end of file

From 40dc32c11e6e226887013ffeebbd185b155c4cb2 Mon Sep 17 00:00:00 2001
From: danielx <66756900+danielxiangzl@users.noreply.github.com>
Date: Wed, 31 May 2023 17:34:14 -0700
Subject: [PATCH 010/200] [Executor] Move block gas limit to state computer
 (#8441)

[Executor]  moving block gas limit to state computer, refactoring and fixing tests
---
 api/test-context/src/test_context.rs          |   2 +-
 aptos-move/aptos-debugger/src/lib.rs          |   2 +-
 .../aptos-transaction-benchmarks/src/main.rs  |  10 +-
 .../src/transactions.rs                       |  36 ++---
 .../src/aptos_test_harness.rs                 |   2 +-
 .../src/bins/run_aptos_p2p.rs                 |   2 +-
 aptos-move/aptos-vm/src/aptos_vm.rs           |  39 +----
 aptos-move/aptos-vm/src/block_executor/mod.rs |   4 +-
 aptos-move/aptos-vm/src/lib.rs                |  10 +-
 .../sharded_block_executor/executor_shard.rs  |   6 +-
 .../src/sharded_block_executor/mod.rs         |  13 +-
 aptos-move/block-executor/src/executor.rs     |  14 +-
 .../src/proptest_types/tests.rs               | 104 +++++++------
 .../src/proptest_types/types.rs               |   4 +-
 aptos-move/e2e-tests/src/executor.rs          |   2 +-
 consensus/src/state_computer.rs               |  25 ++--
 .../executor-benchmark/src/native_executor.rs |  14 +-
 .../src/transaction_executor.rs               |   2 +-
 .../src/integration_test_impl.rs              |  20 ++-
 execution/executor-types/src/lib.rs           |   5 +-
 execution/executor/src/block_executor.rs      |  69 ++-------
 execution/executor/src/chunk_executor.rs      |   6 +-
 .../executor/src/components/chunk_output.rs   |  69 +++------
 execution/executor/src/db_bootstrapper.rs     |   9 +-
 execution/executor/src/fuzzing.rs             |  26 +---
 .../executor/src/mock_vm/mock_vm_test.rs      |   6 +-
 execution/executor/src/mock_vm/mod.rs         |  23 +--
 .../src/tests/chunk_executor_tests.rs         |  11 +-
 execution/executor/src/tests/mod.rs           | 139 +++++++++---------
 .../executor/tests/db_bootstrapper_test.rs    |   5 +-
 .../tests/storage_integration_test.rs         |   7 +-
 .../test_helpers/transaction_test_helpers.rs  |  11 +-
 32 files changed, 289 insertions(+), 408 deletions(-)

diff --git a/api/test-context/src/test_context.rs b/api/test-context/src/test_context.rs
index 49accba9b661b..e1f14dd1796d6 100644
--- a/api/test-context/src/test_context.rs
+++ b/api/test-context/src/test_context.rs
@@ -604,7 +604,7 @@ impl TestContext {
         let parent_id = self.executor.committed_block_id();
         let result = self
             .executor
-            .execute_block((metadata.id(), txns.clone()), parent_id)
+            .execute_block((metadata.id(), txns.clone()), parent_id, None)
             .unwrap();
         let mut compute_status = result.compute_status().clone();
         assert_eq!(compute_status.len(), txns.len(), "{:?}", result);
diff --git a/aptos-move/aptos-debugger/src/lib.rs b/aptos-move/aptos-debugger/src/lib.rs
index eed8ee3b9b064..bf34e3043917d 100644
--- a/aptos-move/aptos-debugger/src/lib.rs
+++ b/aptos-move/aptos-debugger/src/lib.rs
@@ -58,7 +58,7 @@ impl AptosDebugger {
         txns: Vec,
     ) -> Result> {
         let state_view = DebuggerStateView::new(self.debugger.clone(), version);
-        AptosVM::execute_block(txns, &state_view)
+        AptosVM::execute_block(txns, &state_view, None)
             .map_err(|err| format_err!("Unexpected VM Error: {:?}", err))
     }
 
diff --git a/aptos-move/aptos-transaction-benchmarks/src/main.rs b/aptos-move/aptos-transaction-benchmarks/src/main.rs
index e710dd0c604d5..022493cac8535 100755
--- a/aptos-move/aptos-transaction-benchmarks/src/main.rs
+++ b/aptos-move/aptos-transaction-benchmarks/src/main.rs
@@ -49,7 +49,7 @@ struct ParamSweepOpt {
     pub num_runs: usize,
 
     #[clap(long)]
-    pub maybe_gas_limit: Option,
+    pub maybe_block_gas_limit: Option,
 }
 
 #[derive(Debug, Parser)]
@@ -76,7 +76,7 @@ struct ExecuteOpt {
     pub no_conflict_txns: bool,
 
     #[clap(long)]
-    pub maybe_gas_limit: Option,
+    pub maybe_block_gas_limit: Option,
 }
 
 fn param_sweep(opt: ParamSweepOpt) {
@@ -91,7 +91,7 @@ fn param_sweep(opt: ParamSweepOpt) {
     let run_parallel = !opt.skip_parallel;
     let run_sequential = !opt.skip_sequential;
 
-    let maybe_gas_limit = opt.maybe_gas_limit;
+    let maybe_block_gas_limit = opt.maybe_block_gas_limit;
 
     assert!(
         run_sequential || run_parallel,
@@ -110,7 +110,7 @@ fn param_sweep(opt: ParamSweepOpt) {
                 1,
                 concurrency_level,
                 false,
-                maybe_gas_limit,
+                maybe_block_gas_limit,
             );
             par_tps.sort();
             seq_tps.sort();
@@ -171,7 +171,7 @@ fn execute(opt: ExecuteOpt) {
         opt.num_executor_shards,
         opt.concurrency_level_per_shard,
         opt.no_conflict_txns,
-        opt.maybe_gas_limit,
+        opt.maybe_block_gas_limit,
     );
 
     let sum: usize = par_tps.iter().sum();
diff --git a/aptos-move/aptos-transaction-benchmarks/src/transactions.rs b/aptos-move/aptos-transaction-benchmarks/src/transactions.rs
index fb6d65617cf72..a1ce63d35f2ef 100644
--- a/aptos-move/aptos-transaction-benchmarks/src/transactions.rs
+++ b/aptos-move/aptos-transaction-benchmarks/src/transactions.rs
@@ -73,7 +73,6 @@ where
                     self.num_transactions,
                     1,
                     AccountPickStyle::Unlimited,
-                    None,
                 )
             },
             |state| state.execute_sequential(),
@@ -92,7 +91,6 @@ where
                     self.num_transactions,
                     1,
                     AccountPickStyle::Unlimited,
-                    None,
                 )
             },
             |state| state.execute_parallel(),
@@ -113,7 +111,7 @@ where
         num_executor_shards: usize,
         concurrency_level_per_shard: usize,
         no_conflict_txn: bool,
-        maybe_gas_limit: Option,
+        maybe_block_gas_limit: Option,
     ) -> (Vec, Vec) {
         let mut par_tps = Vec::new();
         let mut seq_tps = Vec::new();
@@ -138,7 +136,6 @@ where
             num_txn,
             num_executor_shards,
             account_pick_style,
-            maybe_gas_limit,
         );
 
         for i in 0..total_runs {
@@ -149,6 +146,7 @@ where
                     run_seq,
                     no_conflict_txn,
                     concurrency_level_per_shard,
+                    maybe_block_gas_limit,
                 );
             } else {
                 let tps = state.execute_blockstm_benchmark(
@@ -156,6 +154,7 @@ where
                     run_seq,
                     no_conflict_txn,
                     concurrency_level_per_shard,
+                    maybe_block_gas_limit,
                 );
                 par_tps.push(tps.0);
                 seq_tps.push(tps.1);
@@ -188,14 +187,12 @@ where
         num_transactions: usize,
         num_executor_shards: usize,
         account_pick_style: AccountPickStyle,
-        maybe_gas_limit: Option,
     ) -> Self {
         Self::with_universe(
             strategy,
             universe_strategy(num_accounts, num_transactions, account_pick_style),
             num_transactions,
             num_executor_shards,
-            maybe_gas_limit,
         )
     }
 
@@ -206,7 +203,6 @@ where
         universe_strategy: impl Strategy,
         num_transactions: usize,
         num_executor_shards: usize,
-        maybe_gas_limit: Option,
     ) -> Self {
         let mut runner = TestRunner::default();
         let universe_gen = universe_strategy
@@ -221,13 +217,9 @@ where
         let universe = universe_gen.setup_gas_cost_stability(&mut executor);
 
         let state_view = Arc::new(executor.get_state_view().clone());
-        let parallel_block_executor = Arc::new(ShardedBlockExecutor::new(
-            num_executor_shards,
-            None,
-            maybe_gas_limit,
-        ));
-        let sequential_block_executor =
-            Arc::new(ShardedBlockExecutor::new(1, Some(1), maybe_gas_limit));
+        let parallel_block_executor =
+            Arc::new(ShardedBlockExecutor::new(num_executor_shards, None));
+        let sequential_block_executor = Arc::new(ShardedBlockExecutor::new(1, Some(1)));
 
         let validator_set = ValidatorSet::fetch_config(
             &FakeExecutor::from_head_genesis()
@@ -292,7 +284,7 @@ where
         let txns = self.gen_transaction(false);
         let executor = self.sequential_block_executor;
         executor
-            .execute_block(self.state_view.clone(), txns, 1)
+            .execute_block(self.state_view.clone(), txns, 1, None)
             .expect("VM should not fail to start");
     }
 
@@ -303,7 +295,7 @@ where
         let txns = self.gen_transaction(false);
         let executor = self.parallel_block_executor.clone();
         executor
-            .execute_block(self.state_view.clone(), txns, num_cpus::get())
+            .execute_block(self.state_view.clone(), txns, num_cpus::get(), None)
             .expect("VM should not fail to start");
     }
 
@@ -312,6 +304,7 @@ where
         transactions: Vec,
         block_executor: Arc>,
         concurrency_level_per_shard: usize,
+        maybe_block_gas_limit: Option,
     ) -> usize {
         let block_size = transactions.len();
         let timer = Instant::now();
@@ -320,6 +313,7 @@ where
                 self.state_view.clone(),
                 transactions,
                 concurrency_level_per_shard,
+                maybe_block_gas_limit,
             )
             .expect("VM should not fail to start");
         let exec_time = timer.elapsed().as_millis();
@@ -333,6 +327,7 @@ where
         run_seq: bool,
         no_conflict_txns: bool,
         conurrency_level_per_shard: usize,
+        maybe_block_gas_limit: Option,
     ) -> (usize, usize) {
         let transactions = self.gen_transaction(no_conflict_txns);
         let par_tps = if run_par {
@@ -341,6 +336,7 @@ where
                 transactions.clone(),
                 self.parallel_block_executor.clone(),
                 conurrency_level_per_shard,
+                maybe_block_gas_limit,
             );
             println!("Parallel execution finishes, TPS = {}", tps);
             tps
@@ -349,8 +345,12 @@ where
         };
         let seq_tps = if run_seq {
             println!("Sequential execution starts...");
-            let tps =
-                self.execute_benchmark(transactions, self.sequential_block_executor.clone(), 1);
+            let tps = self.execute_benchmark(
+                transactions,
+                self.sequential_block_executor.clone(),
+                1,
+                maybe_block_gas_limit,
+            );
             println!("Sequential execution finishes, TPS = {}", tps);
             tps
         } else {
diff --git a/aptos-move/aptos-transactional-test-harness/src/aptos_test_harness.rs b/aptos-move/aptos-transactional-test-harness/src/aptos_test_harness.rs
index fb671b281013a..96f880b559fca 100644
--- a/aptos-move/aptos-transactional-test-harness/src/aptos_test_harness.rs
+++ b/aptos-move/aptos-transactional-test-harness/src/aptos_test_harness.rs
@@ -468,7 +468,7 @@ impl<'a> AptosTestAdapter<'a> {
     /// Should error if the transaction ends up being discarded, or having a status other than
     /// EXECUTED.
     fn run_transaction(&mut self, txn: Transaction) -> Result {
-        let mut outputs = AptosVM::execute_block(vec![txn], &self.storage.clone())?;
+        let mut outputs = AptosVM::execute_block(vec![txn], &self.storage.clone(), None)?;
 
         assert_eq!(outputs.len(), 1);
 
diff --git a/aptos-move/aptos-vm-profiling/src/bins/run_aptos_p2p.rs b/aptos-move/aptos-vm-profiling/src/bins/run_aptos_p2p.rs
index e1ee32f805fcb..ec1ecd8a226af 100644
--- a/aptos-move/aptos-vm-profiling/src/bins/run_aptos_p2p.rs
+++ b/aptos-move/aptos-vm-profiling/src/bins/run_aptos_p2p.rs
@@ -44,7 +44,7 @@ fn main() -> Result<()> {
         })
         .collect();
 
-    let res = AptosVM::execute_block(txns, &state_store)?;
+    let res = AptosVM::execute_block(txns, &state_store, None)?;
     for i in 0..NUM_TXNS {
         assert!(res[i as usize].status().status().unwrap().is_success());
     }
diff --git a/aptos-move/aptos-vm/src/aptos_vm.rs b/aptos-move/aptos-vm/src/aptos_vm.rs
index 80163c8661e57..a3a1a1298255a 100644
--- a/aptos-move/aptos-vm/src/aptos_vm.rs
+++ b/aptos-move/aptos-vm/src/aptos_vm.rs
@@ -1472,6 +1472,7 @@ impl VMExecutor for AptosVM {
     fn execute_block(
         transactions: Vec,
         state_view: &(impl StateView + Sync),
+        maybe_block_gas_limit: Option,
     ) -> Result, VMStatus> {
         fail_point!("move_adapter::execute_block", |_| {
             Err(VMStatus::Error(
@@ -1492,41 +1493,7 @@ impl VMExecutor for AptosVM {
             transactions,
             state_view,
             Self::get_concurrency_level(),
-            None,
-        );
-        if ret.is_ok() {
-            // Record the histogram count for transactions per block.
-            BLOCK_TRANSACTION_COUNT.observe(count as f64);
-        }
-        ret
-    }
-
-    fn execute_block_with_gas_limit(
-        transactions: Vec,
-        state_view: &(impl StateView + Sync),
-        maybe_gas_limit: Option,
-    ) -> std::result::Result, VMStatus> {
-        fail_point!("move_adapter::execute_block", |_| {
-            Err(VMStatus::Error(
-                StatusCode::UNKNOWN_INVARIANT_VIOLATION_ERROR,
-                None,
-            ))
-        });
-
-        let log_context = AdapterLogSchema::new(state_view.id(), 0);
-        info!(
-            log_context,
-            "Executing block, transaction count: {}",
-            transactions.len()
-        );
-
-        let count = transactions.len();
-        let ret = BlockAptosVM::execute_block(
-            Arc::clone(&RAYON_EXEC_POOL),
-            transactions,
-            state_view,
-            Self::get_concurrency_level(),
-            maybe_gas_limit,
+            maybe_block_gas_limit,
         );
         if ret.is_ok() {
             // Record the histogram count for transactions per block.
@@ -1539,6 +1506,7 @@ impl VMExecutor for AptosVM {
         sharded_block_executor: &ShardedBlockExecutor,
         transactions: Vec,
         state_view: Arc,
+        maybe_block_gas_limit: Option,
     ) -> Result, VMStatus> {
         let log_context = AdapterLogSchema::new(state_view.id(), 0);
         info!(
@@ -1552,6 +1520,7 @@ impl VMExecutor for AptosVM {
             state_view,
             transactions,
             AptosVM::get_concurrency_level(),
+            maybe_block_gas_limit,
         );
         if ret.is_ok() {
             // Record the histogram count for transactions per block.
diff --git a/aptos-move/aptos-vm/src/block_executor/mod.rs b/aptos-move/aptos-vm/src/block_executor/mod.rs
index 302f64db151c4..2d9b3d9d93514 100644
--- a/aptos-move/aptos-vm/src/block_executor/mod.rs
+++ b/aptos-move/aptos-vm/src/block_executor/mod.rs
@@ -136,7 +136,7 @@ impl BlockAptosVM {
         transactions: Vec,
         state_view: &S,
         concurrency_level: usize,
-        maybe_gas_limit: Option,
+        maybe_block_gas_limit: Option,
     ) -> Result, VMStatus> {
         let _timer = BLOCK_EXECUTOR_EXECUTE_BLOCK_SECONDS.start_timer();
         // Verify the signatures of all the transactions in parallel.
@@ -162,7 +162,7 @@ impl BlockAptosVM {
         let executor = BlockExecutor::, S>::new(
             concurrency_level,
             executor_thread_pool,
-            maybe_gas_limit,
+            maybe_block_gas_limit,
         );
 
         let ret = executor.execute_block(state_view, signature_verified_block, state_view);
diff --git a/aptos-move/aptos-vm/src/lib.rs b/aptos-move/aptos-vm/src/lib.rs
index 0152b7df53543..54125625acedb 100644
--- a/aptos-move/aptos-vm/src/lib.rs
+++ b/aptos-move/aptos-vm/src/lib.rs
@@ -152,14 +152,7 @@ pub trait VMExecutor: Send + Sync {
     fn execute_block(
         transactions: Vec,
         state_view: &(impl StateView + Sync),
-    ) -> Result, VMStatus>;
-
-    /// Executes a block of transactions with per_block_gas_limit
-    /// and returns output for each one of them.
-    fn execute_block_with_gas_limit(
-        transactions: Vec,
-        state_view: &(impl StateView + Sync),
-        maybe_gas_limit: Option,
+        maybe_block_gas_limit: Option,
     ) -> Result, VMStatus>;
 
     /// Executes a block of transactions using a sharded block executor and returns the results.
@@ -167,6 +160,7 @@ pub trait VMExecutor: Send + Sync {
         sharded_block_executor: &ShardedBlockExecutor,
         transactions: Vec,
         state_view: Arc,
+        maybe_block_gas_limit: Option,
     ) -> Result, VMStatus>;
 }
 
diff --git a/aptos-move/aptos-vm/src/sharded_block_executor/executor_shard.rs b/aptos-move/aptos-vm/src/sharded_block_executor/executor_shard.rs
index 2206e00c62ae6..2f3d5b427a6b0 100644
--- a/aptos-move/aptos-vm/src/sharded_block_executor/executor_shard.rs
+++ b/aptos-move/aptos-vm/src/sharded_block_executor/executor_shard.rs
@@ -20,7 +20,6 @@ pub struct ExecutorShard {
     executor_thread_pool: Arc,
     command_rx: Receiver>,
     result_tx: Sender, VMStatus>>,
-    maybe_gas_limit: Option,
 }
 
 impl ExecutorShard {
@@ -30,7 +29,6 @@ impl ExecutorShard {
         num_executor_threads: usize,
         command_rx: Receiver>,
         result_tx: Sender, VMStatus>>,
-        maybe_gas_limit: Option,
     ) -> Self {
         let executor_thread_pool = Arc::new(
             rayon::ThreadPoolBuilder::new()
@@ -49,7 +47,6 @@ impl ExecutorShard {
             executor_thread_pool,
             command_rx,
             result_tx,
-            maybe_gas_limit,
         }
     }
 
@@ -61,6 +58,7 @@ impl ExecutorShard {
                     state_view,
                     transactions,
                     concurrency_level_per_shard,
+                    maybe_block_gas_limit,
                 ) => {
                     trace!(
                         "Shard {} received ExecuteBlock command of block size {} ",
@@ -72,7 +70,7 @@ impl ExecutorShard {
                         transactions,
                         state_view.as_ref(),
                         concurrency_level_per_shard,
-                        self.maybe_gas_limit,
+                        maybe_block_gas_limit,
                     );
                     drop(state_view);
                     self.result_tx.send(ret).unwrap();
diff --git a/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs b/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs
index 87e913c230f55..3537e08dbba5e 100644
--- a/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs
+++ b/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs
@@ -33,16 +33,12 @@ pub struct ShardedBlockExecutor {
 }
 
 pub enum ExecutorShardCommand {
-    ExecuteBlock(Arc, Vec, usize),
+    ExecuteBlock(Arc, Vec, usize, Option),
     Stop,
 }
 
 impl ShardedBlockExecutor {
-    pub fn new(
-        num_executor_shards: usize,
-        executor_threads_per_shard: Option,
-        maybe_gas_limit: Option,
-    ) -> Self {
+    pub fn new(num_executor_shards: usize, executor_threads_per_shard: Option) -> Self {
         assert!(num_executor_shards > 0, "num_executor_shards must be > 0");
         let executor_threads_per_shard = executor_threads_per_shard.unwrap_or_else(|| {
             (num_cpus::get() as f64 / num_executor_shards as f64).ceil() as usize
@@ -61,7 +57,6 @@ impl ShardedBlockExecutor {
                 executor_threads_per_shard,
                 transactions_rx,
                 result_tx,
-                maybe_gas_limit,
             ));
         }
         info!(
@@ -85,6 +80,7 @@ impl ShardedBlockExecutor {
         state_view: Arc,
         block: Vec,
         concurrency_level_per_shard: usize,
+        maybe_block_gas_limit: Option,
     ) -> Result, VMStatus> {
         let block_partitions = self.partitioner.partition(block, self.num_executor_shards);
         // Number of partitions might be smaller than the number of executor shards in case of
@@ -96,6 +92,7 @@ impl ShardedBlockExecutor {
                     state_view.clone(),
                     transactions,
                     concurrency_level_per_shard,
+                    maybe_block_gas_limit,
                 ))
                 .unwrap();
         }
@@ -135,7 +132,6 @@ fn spawn_executor_shard(
     concurrency_level: usize,
     command_rx: Receiver>,
     result_tx: Sender, VMStatus>>,
-    maybe_gas_limit: Option,
 ) -> thread::JoinHandle<()> {
     // create and start a new executor shard in a separate thread
     thread::Builder::new()
@@ -147,7 +143,6 @@ fn spawn_executor_shard(
                 concurrency_level,
                 command_rx,
                 result_tx,
-                maybe_gas_limit,
             );
             executor_shard.start();
         })
diff --git a/aptos-move/block-executor/src/executor.rs b/aptos-move/block-executor/src/executor.rs
index b0013246a7db5..3bd172dd5539d 100644
--- a/aptos-move/block-executor/src/executor.rs
+++ b/aptos-move/block-executor/src/executor.rs
@@ -49,7 +49,7 @@ pub struct BlockExecutor {
     // threads that may be concurrently participating in parallel execution.
     concurrency_level: usize,
     executor_thread_pool: Arc,
-    maybe_gas_limit: Option,
+    maybe_block_gas_limit: Option,
     phantom: PhantomData<(T, E, S)>,
 }
 
@@ -64,7 +64,7 @@ where
     pub fn new(
         concurrency_level: usize,
         executor_thread_pool: Arc,
-        maybe_gas_limit: Option,
+        maybe_block_gas_limit: Option,
     ) -> Self {
         assert!(
             concurrency_level > 0 && concurrency_level <= num_cpus::get(),
@@ -74,7 +74,7 @@ where
         Self {
             concurrency_level,
             executor_thread_pool,
-            maybe_gas_limit,
+            maybe_block_gas_limit,
             phantom: PhantomData,
         }
     }
@@ -221,7 +221,7 @@ where
 
     fn coordinator_commit_hook(
         &self,
-        maybe_gas_limit: Option,
+        maybe_block_gas_limit: Option,
         scheduler: &Scheduler,
         post_commit_txs: &Vec>,
         worker_idx: &mut usize,
@@ -266,7 +266,7 @@ where
                 },
             };
 
-            if let Some(per_block_gas_limit) = maybe_gas_limit {
+            if let Some(per_block_gas_limit) = maybe_block_gas_limit {
                 // When the accumulated gas of the committed txns exceeds PER_BLOCK_GAS_LIMIT, early halt BlockSTM.
                 if *accumulated_gas >= per_block_gas_limit {
                     // Set the execution output status to be SkipRest, to skip the rest of the txns.
@@ -360,7 +360,7 @@ where
             match &role {
                 CommitRole::Coordinator(post_commit_txs) => {
                     self.coordinator_commit_hook(
-                        self.maybe_gas_limit,
+                        self.maybe_block_gas_limit,
                         scheduler,
                         post_commit_txs,
                         &mut worker_idx,
@@ -575,7 +575,7 @@ where
                 break;
             }
 
-            if let Some(per_block_gas_limit) = self.maybe_gas_limit {
+            if let Some(per_block_gas_limit) = self.maybe_block_gas_limit {
                 // When the accumulated gas of the committed txns
                 // exceeds per_block_gas_limit, halt sequential execution.
                 if accumulated_gas >= per_block_gas_limit {
diff --git a/aptos-move/block-executor/src/proptest_types/tests.rs b/aptos-move/block-executor/src/proptest_types/tests.rs
index 93d6cda5fc9af..d897a68f8604e 100644
--- a/aptos-move/block-executor/src/proptest_types/tests.rs
+++ b/aptos-move/block-executor/src/proptest_types/tests.rs
@@ -29,7 +29,7 @@ fn run_transactions(
     skip_rest_transactions: Vec,
     num_repeat: usize,
     module_access: (bool, bool),
-    maybe_gas_limit: Option,
+    maybe_block_gas_limit: Option,
 ) where
     K: Hash + Clone + Debug + Eq + Send + Sync + PartialOrd + Ord + 'static,
     V: Clone + Eq + Send + Sync + Arbitrary + 'static,
@@ -67,7 +67,7 @@ fn run_transactions(
         >::new(
             num_cpus::get(),
             executor_thread_pool.clone(),
-            maybe_gas_limit,
+            maybe_block_gas_limit,
         )
         .execute_transactions_parallel((), &transactions, &data_view);
 
@@ -76,7 +76,8 @@ fn run_transactions(
             continue;
         }
 
-        let baseline = ExpectedOutput::generate_baseline(&transactions, None, maybe_gas_limit);
+        let baseline =
+            ExpectedOutput::generate_baseline(&transactions, None, maybe_block_gas_limit);
         baseline.assert_output(&output);
     }
 }
@@ -134,7 +135,7 @@ proptest! {
     }
 }
 
-fn dynamic_read_writes_with_gas_limit(num_txns: usize, maybe_gas_limit: Option) {
+fn dynamic_read_writes_with_block_gas_limit(num_txns: usize, maybe_block_gas_limit: Option) {
     let mut runner = TestRunner::default();
 
     let universe = vec(any::<[u8; 32]>(), 100)
@@ -156,11 +157,11 @@ fn dynamic_read_writes_with_gas_limit(num_txns: usize, maybe_gas_limit: Option) {
+fn deltas_writes_mixed_with_block_gas_limit(num_txns: usize, maybe_block_gas_limit: Option) {
     let mut runner = TestRunner::default();
 
     let universe = vec(any::<[u8; 32]>(), 50)
@@ -200,16 +201,17 @@ fn deltas_writes_mixed_with_gas_limit(num_txns: usize, maybe_gas_limit: Option::new(
             num_cpus::get(),
             executor_thread_pool.clone(),
-            maybe_gas_limit,
+            maybe_block_gas_limit,
         )
         .execute_transactions_parallel((), &transactions, &data_view);
 
-        let baseline = ExpectedOutput::generate_baseline(&transactions, None, maybe_gas_limit);
+        let baseline =
+            ExpectedOutput::generate_baseline(&transactions, None, maybe_block_gas_limit);
         baseline.assert_output(&output);
     }
 }
 
-fn deltas_resolver_with_gas_limit(num_txns: usize, maybe_gas_limit: Option) {
+fn deltas_resolver_with_block_gas_limit(num_txns: usize, maybe_block_gas_limit: Option) {
     let mut runner = TestRunner::default();
 
     let universe = vec(any::<[u8; 32]>(), 50)
@@ -249,7 +251,7 @@ fn deltas_resolver_with_gas_limit(num_txns: usize, maybe_gas_limit: Option)
         >::new(
             num_cpus::get(),
             executor_thread_pool.clone(),
-            maybe_gas_limit,
+            maybe_block_gas_limit,
         )
         .execute_transactions_parallel((), &transactions, &data_view);
 
@@ -260,13 +262,19 @@ fn deltas_resolver_with_gas_limit(num_txns: usize, maybe_gas_limit: Option)
             .map(|out| out.delta_writes())
             .collect();
 
-        let baseline =
-            ExpectedOutput::generate_baseline(&transactions, Some(delta_writes), maybe_gas_limit);
+        let baseline = ExpectedOutput::generate_baseline(
+            &transactions,
+            Some(delta_writes),
+            maybe_block_gas_limit,
+        );
         baseline.assert_output(&output);
     }
 }
 
-fn dynamic_read_writes_contended_with_gas_limit(num_txns: usize, maybe_gas_limit: Option) {
+fn dynamic_read_writes_contended_with_block_gas_limit(
+    num_txns: usize,
+    maybe_block_gas_limit: Option,
+) {
     let mut runner = TestRunner::default();
 
     let universe = vec(any::<[u8; 32]>(), 10)
@@ -289,11 +297,14 @@ fn dynamic_read_writes_contended_with_gas_limit(num_txns: usize, maybe_gas_limit
         vec![],
         100,
         (false, false),
-        maybe_gas_limit,
+        maybe_block_gas_limit,
     );
 }
 
-fn module_publishing_fallback_with_gas_limit(num_txns: usize, maybe_gas_limit: Option) {
+fn module_publishing_fallback_with_block_gas_limit(
+    num_txns: usize,
+    maybe_block_gas_limit: Option,
+) {
     let mut runner = TestRunner::default();
 
     let universe = vec(any::<[u8; 32]>(), 100)
@@ -315,7 +326,7 @@ fn module_publishing_fallback_with_gas_limit(num_txns: usize, maybe_gas_limit: O
         vec![],
         2,
         (false, true),
-        maybe_gas_limit,
+        maybe_block_gas_limit,
     );
     run_transactions(
         &universe,
@@ -324,7 +335,7 @@ fn module_publishing_fallback_with_gas_limit(num_txns: usize, maybe_gas_limit: O
         vec![],
         2,
         (false, true),
-        maybe_gas_limit,
+        maybe_block_gas_limit,
     );
     run_transactions(
         &universe,
@@ -333,11 +344,14 @@ fn module_publishing_fallback_with_gas_limit(num_txns: usize, maybe_gas_limit: O
         vec![],
         2,
         (true, true),
-        maybe_gas_limit,
+        maybe_block_gas_limit,
     );
 }
 
-fn publishing_fixed_params_with_gas_limit(num_txns: usize, maybe_gas_limit: Option) {
+fn publishing_fixed_params_with_block_gas_limit(
+    num_txns: usize,
+    maybe_block_gas_limit: Option,
+) {
     let mut runner = TestRunner::default();
 
     let universe = vec(any::<[u8; 32]>(), 50)
@@ -407,7 +421,7 @@ fn publishing_fixed_params_with_gas_limit(num_txns: usize, maybe_gas_limit: Opti
         Transaction, ValueType<[u8; 32]>>,
         Task, ValueType<[u8; 32]>>,
         DeltaDataView, ValueType<[u8; 32]>>,
-    >::new(num_cpus::get(), executor_thread_pool, maybe_gas_limit)
+    >::new(num_cpus::get(), executor_thread_pool, maybe_block_gas_limit)
     .execute_transactions_parallel((), &transactions, &data_view);
     assert_ok!(output);
 
@@ -463,27 +477,27 @@ fn publishing_fixed_params_with_gas_limit(num_txns: usize, maybe_gas_limit: Opti
 
 #[test]
 fn dynamic_read_writes() {
-    dynamic_read_writes_with_gas_limit(3000, None);
+    dynamic_read_writes_with_block_gas_limit(3000, None);
 }
 
 #[test]
 fn deltas_writes_mixed() {
-    deltas_writes_mixed_with_gas_limit(1000, None);
+    deltas_writes_mixed_with_block_gas_limit(1000, None);
 }
 
 #[test]
 fn deltas_resolver() {
-    deltas_resolver_with_gas_limit(1000, None);
+    deltas_resolver_with_block_gas_limit(1000, None);
 }
 
 #[test]
 fn dynamic_read_writes_contended() {
-    dynamic_read_writes_contended_with_gas_limit(1000, None);
+    dynamic_read_writes_contended_with_block_gas_limit(1000, None);
 }
 
 #[test]
 fn module_publishing_fallback() {
-    module_publishing_fallback_with_gas_limit(3000, None);
+    module_publishing_fallback_with_block_gas_limit(3000, None);
 }
 
 #[test]
@@ -491,7 +505,7 @@ fn module_publishing_fallback() {
 // not overlapping module r/w keys.
 fn module_publishing_races() {
     for _ in 0..5 {
-        publishing_fixed_params_with_gas_limit(300, None);
+        publishing_fixed_params_with_block_gas_limit(300, None);
     }
 }
 
@@ -550,35 +564,41 @@ proptest! {
 }
 
 #[test]
-fn dynamic_read_writes_with_block_gas_limit() {
-    dynamic_read_writes_with_gas_limit(3000, Some(rand::thread_rng().gen_range(0, 3000) as u64));
-    dynamic_read_writes_with_gas_limit(3000, Some(0));
+fn dynamic_read_writes_with_block_gas_limit_test() {
+    dynamic_read_writes_with_block_gas_limit(
+        3000,
+        Some(rand::thread_rng().gen_range(0, 3000) as u64),
+    );
+    dynamic_read_writes_with_block_gas_limit(3000, Some(0));
 }
 
 #[test]
-fn deltas_writes_mixed_with_block_gas_limit() {
-    deltas_writes_mixed_with_gas_limit(1000, Some(rand::thread_rng().gen_range(0, 1000) as u64));
-    deltas_writes_mixed_with_gas_limit(1000, Some(0));
+fn deltas_writes_mixed_with_block_gas_limit_test() {
+    deltas_writes_mixed_with_block_gas_limit(
+        1000,
+        Some(rand::thread_rng().gen_range(0, 1000) as u64),
+    );
+    deltas_writes_mixed_with_block_gas_limit(1000, Some(0));
 }
 
 #[test]
-fn deltas_resolver_with_block_gas_limit() {
-    deltas_resolver_with_gas_limit(1000, Some(rand::thread_rng().gen_range(0, 1000) as u64));
-    deltas_resolver_with_gas_limit(1000, Some(0));
+fn deltas_resolver_with_block_gas_limit_test() {
+    deltas_resolver_with_block_gas_limit(1000, Some(rand::thread_rng().gen_range(0, 1000) as u64));
+    deltas_resolver_with_block_gas_limit(1000, Some(0));
 }
 
 #[test]
-fn dynamic_read_writes_contended_with_block_gas_limit() {
-    dynamic_read_writes_contended_with_gas_limit(
+fn dynamic_read_writes_contended_with_block_gas_limit_test() {
+    dynamic_read_writes_contended_with_block_gas_limit(
         1000,
         Some(rand::thread_rng().gen_range(0, 1000) as u64),
     );
-    dynamic_read_writes_contended_with_gas_limit(1000, Some(0));
+    dynamic_read_writes_contended_with_block_gas_limit(1000, Some(0));
 }
 
 #[test]
-fn module_publishing_fallback_with_block_gas_limit() {
-    module_publishing_fallback_with_gas_limit(
+fn module_publishing_fallback_with_block_gas_limit_test() {
+    module_publishing_fallback_with_block_gas_limit(
         3000,
         // Need to execute at least 2 txns to trigger module publishing fallback
         Some(rand::thread_rng().gen_range(1, 3000) as u64),
@@ -588,9 +608,9 @@ fn module_publishing_fallback_with_block_gas_limit() {
 #[test]
 // Test a single transaction intersection interleaves with a lot of dependencies and
 // not overlapping module r/w keys.
-fn module_publishing_races_with_block_gas_limit() {
+fn module_publishing_races_with_block_gas_limit_test() {
     for _ in 0..5 {
-        publishing_fixed_params_with_gas_limit(
+        publishing_fixed_params_with_block_gas_limit(
             300,
             Some(rand::thread_rng().gen_range(0, 300) as u64),
         );
diff --git a/aptos-move/block-executor/src/proptest_types/types.rs b/aptos-move/block-executor/src/proptest_types/types.rs
index c0c8aca22ac88..d1064637c2813 100644
--- a/aptos-move/block-executor/src/proptest_types/types.rs
+++ b/aptos-move/block-executor/src/proptest_types/types.rs
@@ -536,7 +536,7 @@ impl ExpectedOutput {
     pub fn generate_baseline(
         txns: &[Transaction],
         resolved_deltas: Option>>,
-        maybe_gas_limit: Option,
+        maybe_block_gas_limit: Option,
     ) -> Self {
         let mut current_world = HashMap::new();
         // Delta world stores the latest u128 value of delta aggregator. When empty, the
@@ -640,7 +640,7 @@ impl ExpectedOutput {
 
                     // In unit tests, the gas_used of any txn is set to be 1.
                     accumulated_gas += 1;
-                    if let Some(block_gas_limit) = maybe_gas_limit {
+                    if let Some(block_gas_limit) = maybe_block_gas_limit {
                         if accumulated_gas >= block_gas_limit {
                             return Self::ExceedBlockGasLimit(idx, result_vec);
                         }
diff --git a/aptos-move/e2e-tests/src/executor.rs b/aptos-move/e2e-tests/src/executor.rs
index c1edbf84c862c..20e6be81d52cc 100644
--- a/aptos-move/e2e-tests/src/executor.rs
+++ b/aptos-move/e2e-tests/src/executor.rs
@@ -436,7 +436,7 @@ impl FakeExecutor {
             }
         }
 
-        let output = AptosVM::execute_block(txn_block.clone(), &self.data_store);
+        let output = AptosVM::execute_block(txn_block.clone(), &self.data_store, None);
         if !self.no_parallel_exec {
             let parallel_output = self.execute_transaction_block_parallel(txn_block);
             assert_eq!(output, parallel_output);
diff --git a/consensus/src/state_computer.rs b/consensus/src/state_computer.rs
index 5a17885d5138f..e87161cc9ed6c 100644
--- a/consensus/src/state_computer.rs
+++ b/consensus/src/state_computer.rs
@@ -58,6 +58,7 @@ pub struct ExecutionProxy {
     write_mutex: AsyncMutex,
     payload_manager: Mutex>>,
     transaction_shuffler: Mutex>>,
+    maybe_block_gas_limit: Mutex>,
     transaction_deduper: Mutex>>,
 }
 
@@ -92,6 +93,7 @@ impl ExecutionProxy {
             write_mutex: AsyncMutex::new(LogicalTime::new(0, 0)),
             payload_manager: Mutex::new(None),
             transaction_shuffler: Mutex::new(None),
+            maybe_block_gas_limit: Mutex::new(None),
             transaction_deduper: Mutex::new(None),
         }
     }
@@ -127,7 +129,7 @@ impl StateComputer for ExecutionProxy {
         let deduped_txns = txn_deduper.dedup(txns);
         let shuffled_txns = txn_shuffler.shuffle(deduped_txns);
 
-        let block_gas_limit = self.executor.get_block_gas_limit();
+        let block_gas_limit = *self.maybe_block_gas_limit.lock();
 
         // TODO: figure out error handling for the prologue txn
         let executor = self.executor.clone();
@@ -141,7 +143,11 @@ impl StateComputer for ExecutionProxy {
         let compute_result = monitor!(
             "execute_block",
             tokio::task::spawn_blocking(move || {
-                executor.execute_block((block_id, transactions_to_execute), parent_block_id)
+                executor.execute_block(
+                    (block_id, transactions_to_execute),
+                    parent_block_id,
+                    block_gas_limit,
+                )
             })
             .await
         )
@@ -185,7 +191,7 @@ impl StateComputer for ExecutionProxy {
         let txn_deduper = self.transaction_deduper.lock().as_ref().unwrap().clone();
         let txn_shuffler = self.transaction_shuffler.lock().as_ref().unwrap().clone();
 
-        let block_gas_limit = self.executor.get_block_gas_limit();
+        let block_gas_limit = *self.maybe_block_gas_limit.lock();
 
         for block in blocks {
             block_ids.push(block.id());
@@ -295,7 +301,7 @@ impl StateComputer for ExecutionProxy {
         epoch_state: &EpochState,
         payload_manager: Arc,
         transaction_shuffler: Arc,
-        _block_gas_limit: Option,
+        block_gas_limit: Option,
         transaction_deduper: Arc,
     ) {
         *self.validators.lock() = epoch_state
@@ -306,9 +312,7 @@ impl StateComputer for ExecutionProxy {
         self.transaction_shuffler
             .lock()
             .replace(transaction_shuffler);
-        // TODO: Temporarily disable initializing block gas limit and leave it as default None,
-        // until there is a better way to handle the possible panic when executor is initialized.
-        // self.executor.update_block_gas_limit(block_gas_limit);
+        *self.maybe_block_gas_limit.lock() = block_gas_limit;
         self.transaction_deduper.lock().replace(transaction_deduper);
     }
 
@@ -352,6 +356,7 @@ async fn test_commit_sync_race() {
             &self,
             _block: (HashValue, Vec),
             _parent_block_id: HashValue,
+            _maybe_block_gas_limit: Option,
         ) -> Result {
             Ok(StateComputeResult::new_dummy())
         }
@@ -370,12 +375,6 @@ async fn test_commit_sync_race() {
         }
 
         fn finish(&self) {}
-
-        fn get_block_gas_limit(&self) -> Option {
-            None
-        }
-
-        fn update_block_gas_limit(&self, _block_gas_limit: Option) {}
     }
 
     #[async_trait::async_trait]
diff --git a/execution/executor-benchmark/src/native_executor.rs b/execution/executor-benchmark/src/native_executor.rs
index 118fa4eb8b510..7294123769ce1 100644
--- a/execution/executor-benchmark/src/native_executor.rs
+++ b/execution/executor-benchmark/src/native_executor.rs
@@ -338,6 +338,7 @@ impl TransactionBlockExecutor for NativeExecutor {
     fn execute_transaction_block(
         transactions: Vec,
         state_view: CachedStateView,
+        _maybe_block_gas_limit: Option,
     ) -> Result {
         let transaction_outputs = NATIVE_EXECUTOR_POOL.install(|| {
             transactions
@@ -411,17 +412,4 @@ impl TransactionBlockExecutor for NativeExecutor {
             state_cache: state_view.into_state_cache(),
         })
     }
-
-    // Dummy function that is not supposed to be used
-    fn execute_transaction_block_with_gas_limit(
-        _transactions: Vec,
-        state_view: CachedStateView,
-        _maybe_gas_limit: Option,
-    ) -> Result {
-        Ok(ChunkOutput {
-            transactions: vec![],
-            transaction_outputs: vec![],
-            state_cache: state_view.into_state_cache(),
-        })
-    }
 }
diff --git a/execution/executor-benchmark/src/transaction_executor.rs b/execution/executor-benchmark/src/transaction_executor.rs
index f47b7c20c25cc..a156f13d8dc42 100644
--- a/execution/executor-benchmark/src/transaction_executor.rs
+++ b/execution/executor-benchmark/src/transaction_executor.rs
@@ -61,7 +61,7 @@ where
         let block_id = HashValue::random();
         let output = self
             .executor
-            .execute_block((block_id, transactions), self.parent_block_id)
+            .execute_block((block_id, transactions), self.parent_block_id, None)
             .unwrap();
 
         assert_eq!(output.compute_status().len(), num_txns);
diff --git a/execution/executor-test-helpers/src/integration_test_impl.rs b/execution/executor-test-helpers/src/integration_test_impl.rs
index fad11604db79a..83d3b77bffa31 100644
--- a/execution/executor-test-helpers/src/integration_test_impl.rs
+++ b/execution/executor-test-helpers/src/integration_test_impl.rs
@@ -21,7 +21,7 @@ use aptos_types::{
     block_metadata::BlockMetadata,
     chain_id::ChainId,
     event::EventKey,
-    test_helpers::transaction_test_helpers::block,
+    test_helpers::transaction_test_helpers::{block, BLOCK_GAS_LIMIT},
     transaction::{
         Transaction, Transaction::UserTransaction, TransactionListWithProof, TransactionWithProof,
         WriteSetPayload,
@@ -160,10 +160,14 @@ pub fn test_execution_with_storage_impl() -> Arc {
             txn_factory.transfer(account3.address(), 10 * B),
         )));
     }
-    let block3 = block(block3, executor.get_block_gas_limit()); // append state checkpoint txn
+    let block3 = block(block3, BLOCK_GAS_LIMIT); // append state checkpoint txn
 
     let output1 = executor
-        .execute_block((block1_id, block1.clone()), parent_block_id)
+        .execute_block(
+            (block1_id, block1.clone()),
+            parent_block_id,
+            BLOCK_GAS_LIMIT,
+        )
         .unwrap();
     let li1 = gen_ledger_info_with_sigs(1, &output1, block1_id, &[signer.clone()]);
     let epoch2_genesis_id = Block::make_genesis_block_from_ledger_info(li1.ledger_info()).id();
@@ -371,7 +375,7 @@ pub fn test_execution_with_storage_impl() -> Arc {
 
     // Execute block 2, 3, 4
     let output2 = executor
-        .execute_block((block2_id, block2), epoch2_genesis_id)
+        .execute_block((block2_id, block2), epoch2_genesis_id, BLOCK_GAS_LIMIT)
         .unwrap();
     let li2 = gen_ledger_info_with_sigs(2, &output2, block2_id, &[signer.clone()]);
     let epoch3_genesis_id = Block::make_genesis_block_from_ledger_info(li2.ledger_info()).id();
@@ -386,7 +390,11 @@ pub fn test_execution_with_storage_impl() -> Arc {
     assert_eq!(current_version, 13);
 
     let output3 = executor
-        .execute_block((block3_id, block3.clone()), epoch3_genesis_id)
+        .execute_block(
+            (block3_id, block3.clone()),
+            epoch3_genesis_id,
+            BLOCK_GAS_LIMIT,
+        )
         .unwrap();
     let li3 = gen_ledger_info_with_sigs(3, &output3, block3_id, &[signer]);
     executor.commit_blocks(vec![block3_id], li3).unwrap();
@@ -430,7 +438,7 @@ pub fn test_execution_with_storage_impl() -> Arc {
     .unwrap();
 
     // With block gas limit, StateCheckpoint txn is inserted to block after execution.
-    let diff = executor.get_block_gas_limit().map(|_| 0).unwrap_or(1);
+    let diff = BLOCK_GAS_LIMIT.map(|_| 0).unwrap_or(1);
 
     let transaction_list_with_proof = db
         .reader
diff --git a/execution/executor-types/src/lib.rs b/execution/executor-types/src/lib.rs
index 69ca00e860fec..eeafe613814f2 100644
--- a/execution/executor-types/src/lib.rs
+++ b/execution/executor-types/src/lib.rs
@@ -92,6 +92,7 @@ pub trait BlockExecutorTrait: Send + Sync {
         &self,
         block: (HashValue, Vec),
         parent_block_id: HashValue,
+        maybe_block_gas_limit: Option,
     ) -> Result;
 
     /// Saves eligible blocks to persistent storage.
@@ -124,10 +125,6 @@ pub trait BlockExecutorTrait: Send + Sync {
 
     /// Finishes the block executor by releasing memory held by inner data structures(SMT).
     fn finish(&self);
-
-    fn get_block_gas_limit(&self) -> Option;
-
-    fn update_block_gas_limit(&self, block_gas_limit: Option);
 }
 
 #[derive(Clone)]
diff --git a/execution/executor/src/block_executor.rs b/execution/executor/src/block_executor.rs
index b1568a582821c..9097df8babcd2 100644
--- a/execution/executor/src/block_executor.rs
+++ b/execution/executor/src/block_executor.rs
@@ -16,7 +16,7 @@ use crate::{
 use anyhow::Result;
 use aptos_crypto::HashValue;
 use aptos_executor_types::{BlockExecutorTrait, Error, StateComputeResult};
-use aptos_infallible::{Mutex, RwLock};
+use aptos_infallible::RwLock;
 use aptos_logger::prelude::*;
 use aptos_scratchpad::SparseMerkleTree;
 use aptos_state_view::StateViewId;
@@ -35,12 +35,7 @@ pub trait TransactionBlockExecutor: Send + Sync {
     fn execute_transaction_block(
         transactions: Vec,
         state_view: CachedStateView,
-    ) -> Result;
-
-    fn execute_transaction_block_with_gas_limit(
-        transactions: Vec,
-        state_view: CachedStateView,
-        maybe_gas_limit: Option,
+        maybe_block_gas_limit: Option,
     ) -> Result;
 }
 
@@ -48,19 +43,12 @@ impl TransactionBlockExecutor for AptosVM {
     fn execute_transaction_block(
         transactions: Vec,
         state_view: CachedStateView,
+        maybe_block_gas_limit: Option,
     ) -> Result {
-        ChunkOutput::by_transaction_execution::(transactions, state_view)
-    }
-
-    fn execute_transaction_block_with_gas_limit(
-        transactions: Vec,
-        state_view: CachedStateView,
-        maybe_gas_limit: Option,
-    ) -> Result {
-        ChunkOutput::by_transaction_execution_with_gas_limit::(
+        ChunkOutput::by_transaction_execution::(
             transactions,
             state_view,
-            maybe_gas_limit,
+            maybe_block_gas_limit,
         )
     }
 }
@@ -101,24 +89,6 @@ impl BlockExecutorTrait for BlockExecutor
 where
     V: TransactionBlockExecutor,
 {
-    fn get_block_gas_limit(&self) -> Option {
-        self.maybe_initialize().expect("Failed to initialize.");
-        self.inner
-            .read()
-            .as_ref()
-            .expect("BlockExecutor is not reset")
-            .get_block_gas_limit()
-    }
-
-    fn update_block_gas_limit(&self, block_gas_limit: Option) {
-        self.maybe_initialize().expect("Failed to initialize.");
-        self.inner
-            .write()
-            .as_ref()
-            .expect("BlockExecutor is not reset")
-            .update_block_gas_limit(block_gas_limit);
-    }
-
     fn committed_block_id(&self) -> HashValue {
         self.maybe_initialize().expect("Failed to initialize.");
         self.inner
@@ -137,13 +107,14 @@ where
         &self,
         block: (HashValue, Vec),
         parent_block_id: HashValue,
+        maybe_block_gas_limit: Option,
     ) -> Result {
         self.maybe_initialize()?;
         self.inner
             .read()
             .as_ref()
             .expect("BlockExecutor is not reset")
-            .execute_block(block, parent_block_id)
+            .execute_block(block, parent_block_id, maybe_block_gas_limit)
     }
 
     fn commit_blocks_ext(
@@ -168,7 +139,6 @@ struct BlockExecutorInner {
     db: DbReaderWriter,
     block_tree: BlockTree,
     phantom: PhantomData,
-    block_gas_limit: Mutex>,
 }
 
 impl BlockExecutorInner
@@ -181,7 +151,6 @@ where
             db,
             block_tree,
             phantom: PhantomData,
-            block_gas_limit: Mutex::new(None),
         })
     }
 
@@ -200,15 +169,6 @@ impl BlockExecutorInner
 where
     V: TransactionBlockExecutor,
 {
-    fn get_block_gas_limit(&self) -> Option {
-        self.block_gas_limit.lock().as_ref().copied()
-    }
-
-    fn update_block_gas_limit(&self, block_gas_limit: Option) {
-        let mut gas_limit = self.block_gas_limit.lock();
-        *gas_limit = block_gas_limit;
-    }
-
     fn committed_block_id(&self) -> HashValue {
         self.block_tree.root_block().id
     }
@@ -217,6 +177,7 @@ where
         &self,
         block: (HashValue, Vec),
         parent_block_id: HashValue,
+        maybe_block_gas_limit: Option,
     ) -> Result {
         let _timer = APTOS_EXECUTOR_EXECUTE_BLOCK_SECONDS.start_timer();
         let (block_id, transactions) = block;
@@ -261,8 +222,6 @@ where
                 )?
             };
 
-            let maybe_gas_limit = self.get_block_gas_limit();
-
             let chunk_output = {
                 let _timer = APTOS_EXECUTOR_VM_EXECUTE_BLOCK_SECONDS.start_timer();
                 fail_point!("executor::vm_execute_block", |_| {
@@ -270,15 +229,7 @@ where
                         "Injected error in vm_execute_block"
                     )))
                 });
-                if maybe_gas_limit.is_some() {
-                    V::execute_transaction_block_with_gas_limit(
-                        transactions,
-                        state_view,
-                        maybe_gas_limit,
-                    )?
-                } else {
-                    V::execute_transaction_block(transactions, state_view)?
-                }
+                V::execute_transaction_block(transactions, state_view, maybe_block_gas_limit)?
             };
             chunk_output.trace_log_transaction_status();
 
@@ -287,7 +238,7 @@ where
                 .start_timer();
 
             let (output, _, _) = chunk_output
-                .apply_to_ledger_for_block(parent_view, maybe_gas_limit.map(|_| block_id))?;
+                .apply_to_ledger_for_block(parent_view, maybe_block_gas_limit.map(|_| block_id))?;
 
             output
         };
diff --git a/execution/executor/src/chunk_executor.rs b/execution/executor/src/chunk_executor.rs
index 3e3724a40b217..e2c3b9f27459f 100644
--- a/execution/executor/src/chunk_executor.rs
+++ b/execution/executor/src/chunk_executor.rs
@@ -203,7 +203,8 @@ impl ChunkExecutorInner {
         let state_view = self.state_view(&latest_view)?;
         let chunk_output = {
             let _timer = APTOS_EXECUTOR_VM_EXECUTE_CHUNK_SECONDS.start_timer();
-            ChunkOutput::by_transaction_execution::(transactions, state_view)?
+            // State sync executor shouldn't have block gas limit.
+            ChunkOutput::by_transaction_execution::(transactions, state_view, None)?
         };
         let executed_chunk = Self::apply_chunk_output_for_state_sync(
             verified_target_li,
@@ -529,7 +530,8 @@ impl ChunkExecutorInner {
             .cloned()
             .collect();
 
-        let chunk_output = ChunkOutput::by_transaction_execution::(txns, state_view)?;
+        // State sync executor shouldn't have block gas limit.
+        let chunk_output = ChunkOutput::by_transaction_execution::(txns, state_view, None)?;
         // not `zip_eq`, deliberately
         for (version, txn_out, txn_info, write_set, events) in multizip((
             begin_version..end_version,
diff --git a/execution/executor/src/components/chunk_output.rs b/execution/executor/src/components/chunk_output.rs
index b4fd421ec6262..6561082edf249 100644
--- a/execution/executor/src/components/chunk_output.rs
+++ b/execution/executor/src/components/chunk_output.rs
@@ -29,7 +29,6 @@ pub static SHARDED_BLOCK_EXECUTOR: Lazy(
         transactions: Vec,
         state_view: CachedStateView,
+        maybe_block_gas_limit: Option,
     ) -> Result {
-        let transaction_outputs = Self::execute_block::(transactions.clone(), &state_view)?;
-
-        // to print txn output for debugging, uncomment:
-        // println!("{:?}", transaction_outputs.iter().map(|t| t.status() ).collect::>());
-
-        update_counters_for_processed_chunk(&transactions, &transaction_outputs, "executed");
-
-        Ok(Self {
-            transactions,
-            transaction_outputs,
-            state_cache: state_view.into_state_cache(),
-        })
-    }
-
-    pub fn by_transaction_execution_with_gas_limit(
-        transactions: Vec,
-        state_view: CachedStateView,
-        maybe_gas_limit: Option,
-    ) -> Result {
-        let transaction_outputs = Self::execute_block_with_gas_limit::(
-            transactions.clone(),
-            &state_view,
-            maybe_gas_limit,
-        )?;
+        let transaction_outputs =
+            Self::execute_block::(transactions.clone(), &state_view, maybe_block_gas_limit)?;
 
         // to print txn output for debugging, uncomment:
         // println!("{:?}", transaction_outputs.iter().map(|t| t.status() ).collect::>());
@@ -89,10 +67,14 @@ impl ChunkOutput {
     pub fn by_transaction_execution_sharded(
         transactions: Vec,
         state_view: CachedStateView,
+        maybe_block_gas_limit: Option,
     ) -> Result {
         let state_view_arc = Arc::new(state_view);
-        let transaction_outputs =
-            Self::execute_block_sharded::(transactions.clone(), state_view_arc.clone())?;
+        let transaction_outputs = Self::execute_block_sharded::(
+            transactions.clone(),
+            state_view_arc.clone(),
+            maybe_block_gas_limit,
+        )?;
 
         update_counters_for_processed_chunk(&transactions, &transaction_outputs, "executed");
 
@@ -172,11 +154,13 @@ impl ChunkOutput {
     fn execute_block_sharded(
         transactions: Vec,
         state_view: Arc,
+        maybe_block_gas_limit: Option,
     ) -> Result> {
         Ok(V::execute_block_sharded(
             SHARDED_BLOCK_EXECUTOR.lock().deref(),
             transactions,
             state_view,
+            maybe_block_gas_limit,
         )?)
     }
 
@@ -186,22 +170,12 @@ impl ChunkOutput {
     fn execute_block(
         transactions: Vec,
         state_view: &CachedStateView,
+        maybe_block_gas_limit: Option,
     ) -> Result> {
-        Ok(V::execute_block(transactions, &state_view)?)
-    }
-
-    /// Executes the block of [Transaction]s using the [VMExecutor] and returns
-    /// a vector of [TransactionOutput]s.
-    #[cfg(not(feature = "consensus-only-perf-test"))]
-    fn execute_block_with_gas_limit(
-        transactions: Vec,
-        state_view: &CachedStateView,
-        maybe_gas_limit: Option,
-    ) -> Result> {
-        Ok(V::execute_block_with_gas_limit(
+        Ok(V::execute_block(
             transactions,
             &state_view,
-            maybe_gas_limit,
+            maybe_block_gas_limit,
         )?)
     }
 
@@ -213,13 +187,16 @@ impl ChunkOutput {
     fn execute_block(
         transactions: Vec,
         state_view: &CachedStateView,
+        maybe_block_gas_limit: Option,
     ) -> Result> {
         use aptos_state_view::{StateViewId, TStateView};
         use aptos_types::write_set::WriteSet;
 
         let transaction_outputs = match state_view.id() {
             // this state view ID implies a genesis block in non-test cases.
-            StateViewId::Miscellaneous => V::execute_block(transactions, &state_view)?,
+            StateViewId::Miscellaneous => {
+                V::execute_block(transactions, &state_view, maybe_block_gas_limit)?
+            },
             _ => transactions
                 .iter()
                 .map(|_| {
@@ -234,16 +211,6 @@ impl ChunkOutput {
         };
         Ok(transaction_outputs)
     }
-
-    /// In consensus-only mode, we do not care about gas limits.
-    #[cfg(feature = "consensus-only-perf-test")]
-    fn execute_block_with_gas_limit(
-        transactions: Vec,
-        state_view: &CachedStateView,
-        _maybe_gas_limit: Option,
-    ) -> Result> {
-        Self::execute_block::(transactions, state_view)
-    }
 }
 
 pub fn update_counters_for_processed_chunk(
diff --git a/execution/executor/src/db_bootstrapper.rs b/execution/executor/src/db_bootstrapper.rs
index 2f8b7ef9123ec..c898a6269b215 100644
--- a/execution/executor/src/db_bootstrapper.rs
+++ b/execution/executor/src/db_bootstrapper.rs
@@ -136,9 +136,12 @@ pub fn calculate_genesis(
         get_state_epoch(&base_state_view)?
     };
 
-    let (mut output, _, _) =
-        ChunkOutput::by_transaction_execution::(vec![genesis_txn.clone()], base_state_view)?
-            .apply_to_ledger(&executed_trees, None)?;
+    let (mut output, _, _) = ChunkOutput::by_transaction_execution::(
+        vec![genesis_txn.clone()],
+        base_state_view,
+        None,
+    )?
+    .apply_to_ledger(&executed_trees, None)?;
     ensure!(
         !output.to_commit.is_empty(),
         "Genesis txn execution failed."
diff --git a/execution/executor/src/fuzzing.rs b/execution/executor/src/fuzzing.rs
index c24db7ec31894..45dd95abf8860 100644
--- a/execution/executor/src/fuzzing.rs
+++ b/execution/executor/src/fuzzing.rs
@@ -15,6 +15,7 @@ use aptos_storage_interface::{
 };
 use aptos_types::{
     ledger_info::LedgerInfoWithSignatures,
+    test_helpers::transaction_test_helpers::BLOCK_GAS_LIMIT,
     transaction::{Transaction, TransactionOutput, TransactionToCommit, Version},
     vm_status::VMStatus,
 };
@@ -38,7 +39,7 @@ pub fn fuzz_execute_and_commit_blocks(
     let mut block_ids = vec![];
     for block in blocks {
         let block_id = block.0;
-        let _execution_results = executor.execute_block(block, parent_block_id);
+        let _execution_results = executor.execute_block(block, parent_block_id, BLOCK_GAS_LIMIT);
         parent_block_id = block_id;
         block_ids.push(block_id);
     }
@@ -52,19 +53,12 @@ impl TransactionBlockExecutor for FakeVM {
     fn execute_transaction_block(
         transactions: Vec,
         state_view: CachedStateView,
+        maybe_block_gas_limit: Option,
     ) -> Result {
-        ChunkOutput::by_transaction_execution::(transactions, state_view)
-    }
-
-    fn execute_transaction_block_with_gas_limit(
-        transactions: Vec,
-        state_view: CachedStateView,
-        maybe_gas_limit: Option,
-    ) -> Result {
-        ChunkOutput::by_transaction_execution_with_gas_limit::(
+        ChunkOutput::by_transaction_execution::(
             transactions,
             state_view,
-            maybe_gas_limit,
+            maybe_block_gas_limit,
         )
     }
 }
@@ -74,6 +68,7 @@ impl VMExecutor for FakeVM {
         _sharded_block_executor: &ShardedBlockExecutor,
         _transactions: Vec,
         _state_view: Arc,
+        _maybe_block_gas_limit: Option,
     ) -> Result, VMStatus> {
         Ok(Vec::new())
     }
@@ -81,14 +76,7 @@ impl VMExecutor for FakeVM {
     fn execute_block(
         _transactions: Vec,
         _state_view: &impl StateView,
-    ) -> Result, VMStatus> {
-        Ok(Vec::new())
-    }
-
-    fn execute_block_with_gas_limit(
-        _transactions: Vec,
-        _state_view: &impl StateView,
-        _maybe_gas_limit: Option,
+        _maybe_block_gas_limit: Option,
     ) -> Result, VMStatus> {
         Ok(Vec::new())
     }
diff --git a/execution/executor/src/mock_vm/mock_vm_test.rs b/execution/executor/src/mock_vm/mock_vm_test.rs
index 73c24af2e0164..05cbd65739387 100644
--- a/execution/executor/src/mock_vm/mock_vm_test.rs
+++ b/execution/executor/src/mock_vm/mock_vm_test.rs
@@ -45,7 +45,7 @@ fn test_mock_vm_different_senders() {
         txns.push(encode_mint_transaction(gen_address(i), amount));
     }
 
-    let outputs = MockVM::execute_block(txns.clone(), &MockStateView)
+    let outputs = MockVM::execute_block(txns.clone(), &MockStateView, None)
         .expect("MockVM should not fail to start");
 
     for (output, txn) in itertools::zip_eq(outputs.iter(), txns.iter()) {
@@ -82,7 +82,7 @@ fn test_mock_vm_same_sender() {
     }
 
     let outputs =
-        MockVM::execute_block(txns, &MockStateView).expect("MockVM should not fail to start");
+        MockVM::execute_block(txns, &MockStateView, None).expect("MockVM should not fail to start");
 
     for (i, output) in outputs.iter().enumerate() {
         assert_eq!(
@@ -116,7 +116,7 @@ fn test_mock_vm_payment() {
     ];
 
     let output =
-        MockVM::execute_block(txns, &MockStateView).expect("MockVM should not fail to start");
+        MockVM::execute_block(txns, &MockStateView, None).expect("MockVM should not fail to start");
 
     let mut output_iter = output.iter();
     output_iter.next();
diff --git a/execution/executor/src/mock_vm/mod.rs b/execution/executor/src/mock_vm/mod.rs
index f69543306d32f..6df256d61093c 100644
--- a/execution/executor/src/mock_vm/mod.rs
+++ b/execution/executor/src/mock_vm/mod.rs
@@ -61,19 +61,12 @@ impl TransactionBlockExecutor for MockVM {
     fn execute_transaction_block(
         transactions: Vec,
         state_view: CachedStateView,
+        maybe_block_gas_limit: Option,
     ) -> Result {
-        ChunkOutput::by_transaction_execution::(transactions, state_view)
-    }
-
-    fn execute_transaction_block_with_gas_limit(
-        transactions: Vec,
-        state_view: CachedStateView,
-        maybe_gas_limit: Option,
-    ) -> Result {
-        ChunkOutput::by_transaction_execution_with_gas_limit::(
+        ChunkOutput::by_transaction_execution::(
             transactions,
             state_view,
-            maybe_gas_limit,
+            maybe_block_gas_limit,
         )
     }
 }
@@ -82,6 +75,7 @@ impl VMExecutor for MockVM {
     fn execute_block(
         transactions: Vec,
         state_view: &impl StateView,
+        _maybe_block_gas_limit: Option,
     ) -> Result, VMStatus> {
         if state_view.is_genesis() {
             assert_eq!(
@@ -212,18 +206,11 @@ impl VMExecutor for MockVM {
         Ok(outputs)
     }
 
-    fn execute_block_with_gas_limit(
-        transactions: Vec,
-        state_view: &(impl StateView + Sync),
-        _maybe_gas_limit: Option,
-    ) -> Result, VMStatus> {
-        MockVM::execute_block(transactions, state_view)
-    }
-
     fn execute_block_sharded(
         _sharded_block_executor: &ShardedBlockExecutor,
         _transactions: Vec,
         _state_view: Arc,
+        _maybe_block_gas_limit: Option,
     ) -> std::result::Result, VMStatus> {
         todo!()
     }
diff --git a/execution/executor/src/tests/chunk_executor_tests.rs b/execution/executor/src/tests/chunk_executor_tests.rs
index be6a4b19dd14c..d7c057bddc8fe 100644
--- a/execution/executor/src/tests/chunk_executor_tests.rs
+++ b/execution/executor/src/tests/chunk_executor_tests.rs
@@ -17,7 +17,7 @@ use aptos_executor_types::{BlockExecutorTrait, ChunkExecutorTrait};
 use aptos_storage_interface::DbReaderWriter;
 use aptos_types::{
     ledger_info::LedgerInfoWithSignatures,
-    test_helpers::transaction_test_helpers::block,
+    test_helpers::transaction_test_helpers::{block, BLOCK_GAS_LIMIT},
     transaction::{TransactionListWithProof, TransactionOutputListWithProof},
 };
 use rand::Rng;
@@ -274,15 +274,12 @@ fn test_executor_execute_and_commit_chunk_local_result_mismatch() {
             .collect::>();
         let output = executor
             .execute_block(
-                (block_id, block(txns, executor.get_block_gas_limit())),
+                (block_id, block(txns, BLOCK_GAS_LIMIT)),
                 parent_block_id,
+                BLOCK_GAS_LIMIT,
             )
             .unwrap();
-        // With no block gas limit, StateCheckpoint txn is inserted to block before execution.
-        // So the ledger_info version needs to + 1 with no block gas limit.
-        let maybe_gas_limit = executor.get_block_gas_limit();
-        let diff = maybe_gas_limit.map(|_| 0).unwrap_or(1);
-        let ledger_info = tests::gen_ledger_info(5 + diff, output.root_hash(), block_id, 1);
+        let ledger_info = tests::gen_ledger_info(5 + 1, output.root_hash(), block_id, 1);
         executor.commit_blocks(vec![block_id], ledger_info).unwrap();
     }
 
diff --git a/execution/executor/src/tests/mod.rs b/execution/executor/src/tests/mod.rs
index 22ea1df12519e..e9e4338642b06 100644
--- a/execution/executor/src/tests/mod.rs
+++ b/execution/executor/src/tests/mod.rs
@@ -30,7 +30,7 @@ use aptos_types::{
     ledger_info::{LedgerInfo, LedgerInfoWithSignatures},
     proof::definition::LeafCount,
     state_store::{state_key::StateKey, state_value::StateValue},
-    test_helpers::transaction_test_helpers::block,
+    test_helpers::transaction_test_helpers::{block, BLOCK_GAS_LIMIT},
     transaction::{
         ExecutionStatus, RawTransaction, Script, SignedTransaction, Transaction,
         TransactionListWithProof, TransactionOutput, TransactionPayload, TransactionStatus,
@@ -53,8 +53,9 @@ fn execute_and_commit_block(
 
     let output = executor
         .execute_block(
-            (id, block(vec![txn], executor.get_block_gas_limit())),
+            (id, block(vec![txn], BLOCK_GAS_LIMIT)),
             parent_block_id,
+            BLOCK_GAS_LIMIT,
         )
         .unwrap();
     let version = 2 * (txn_index + 1);
@@ -80,7 +81,6 @@ impl TestExecutor {
         let waypoint = generate_waypoint::(&db, &genesis).unwrap();
         maybe_bootstrap::(&db, &genesis, waypoint).unwrap();
         let executor = BlockExecutor::new(db.clone());
-        executor.update_block_gas_limit(Some(1000)); // Can comment out this line to test without gas limit
 
         TestExecutor {
             _path: path,
@@ -152,11 +152,9 @@ fn test_executor_status() {
 
     let output = executor
         .execute_block(
-            (
-                block_id,
-                block(vec![txn0, txn1, txn2], executor.get_block_gas_limit()),
-            ),
+            (block_id, block(vec![txn0, txn1, txn2], BLOCK_GAS_LIMIT)),
             parent_block_id,
+            BLOCK_GAS_LIMIT,
         )
         .unwrap();
 
@@ -184,10 +182,7 @@ fn test_executor_status_consensus_only() {
 
     let output = executor
         .execute_block(
-            (
-                block_id,
-                block(vec![txn0, txn1, txn2], executor.get_block_gas_limit()),
-            ),
+            (block_id, block(vec![txn0, txn1, txn2], BLOCK_GAS_LIMIT)),
             parent_block_id,
         )
         .unwrap();
@@ -216,8 +211,9 @@ fn test_executor_one_block() {
         .collect::>();
     let output = executor
         .execute_block(
-            (block_id, block(txns, executor.get_block_gas_limit())),
+            (block_id, block(txns, BLOCK_GAS_LIMIT)),
             parent_block_id,
+            BLOCK_GAS_LIMIT,
         )
         .unwrap();
     let version = num_user_txns + 1;
@@ -261,20 +257,16 @@ fn test_executor_two_blocks_with_failed_txns() {
         .collect::>();
     let _output1 = executor
         .execute_block(
-            (
-                block1_id,
-                block(block1_txns, executor.get_block_gas_limit()),
-            ),
+            (block1_id, block(block1_txns, BLOCK_GAS_LIMIT)),
             parent_block_id,
+            BLOCK_GAS_LIMIT,
         )
         .unwrap();
     let output2 = executor
         .execute_block(
-            (
-                block2_id,
-                block(block2_txns, executor.get_block_gas_limit()),
-            ),
+            (block2_id, block(block2_txns, BLOCK_GAS_LIMIT)),
             block1_id,
+            BLOCK_GAS_LIMIT,
         )
         .unwrap();
 
@@ -294,11 +286,9 @@ fn test_executor_commit_twice() {
     let block1_id = gen_block_id(1);
     let output1 = executor
         .execute_block(
-            (
-                block1_id,
-                block(block1_txns, executor.get_block_gas_limit()),
-            ),
+            (block1_id, block(block1_txns, BLOCK_GAS_LIMIT)),
             parent_block_id,
+            BLOCK_GAS_LIMIT,
         )
         .unwrap();
     let ledger_info = gen_ledger_info(6, output1.root_hash(), block1_id, 1);
@@ -326,11 +316,9 @@ fn test_executor_execute_same_block_multiple_times() {
     for _i in 0..100 {
         let output = executor
             .execute_block(
-                (
-                    block_id,
-                    block(txns.clone(), executor.get_block_gas_limit()),
-                ),
+                (block_id, block(txns.clone(), BLOCK_GAS_LIMIT)),
                 parent_block_id,
+                BLOCK_GAS_LIMIT,
             )
             .unwrap();
         responses.push(output);
@@ -339,10 +327,10 @@ fn test_executor_execute_same_block_multiple_times() {
     assert_eq!(responses.len(), 1);
 }
 
-fn ledger_version_from_block_size(block_size: usize, maybe_gas_limit: Option) -> usize {
+fn ledger_version_from_block_size(block_size: usize, maybe_block_gas_limit: Option) -> usize {
     // With block gas limit, StateCheckpoint txn is inserted to block after execution.
     // So the ledger_info version needs to block_size + 1 with block gas limit.
-    block_size + maybe_gas_limit.map(|_| 1).unwrap_or(0)
+    block_size + maybe_block_gas_limit.map(|_| 1).unwrap_or(0)
 }
 
 /// Generates a list of `TransactionListWithProof`s according to the given ranges.
@@ -368,17 +356,20 @@ fn create_transaction_chunks(
         let txn = encode_mint_transaction(gen_address(i), 100);
         txns.push(txn);
     }
-    if executor.get_block_gas_limit().is_none() {
+    if BLOCK_GAS_LIMIT.is_none() {
         txns.push(Transaction::StateCheckpoint(HashValue::random()));
     }
     let id = gen_block_id(1);
 
     let output = executor
-        .execute_block((id, txns.clone()), executor.committed_block_id())
+        .execute_block(
+            (id, txns.clone()),
+            executor.committed_block_id(),
+            BLOCK_GAS_LIMIT,
+        )
         .unwrap();
 
-    let ledger_version =
-        ledger_version_from_block_size(txns.len(), executor.get_block_gas_limit()) as u64;
+    let ledger_version = ledger_version_from_block_size(txns.len(), BLOCK_GAS_LIMIT) as u64;
     let ledger_info = gen_ledger_info(ledger_version, output.root_hash(), id, 1);
     executor
         .commit_blocks(vec![id], ledger_info.clone())
@@ -411,12 +402,20 @@ fn test_noop_block_after_reconfiguration() {
     let first_txn = encode_reconfiguration_transaction();
     let first_block_id = gen_block_id(1);
     let output1 = executor
-        .execute_block((first_block_id, vec![first_txn]), parent_block_id)
+        .execute_block(
+            (first_block_id, vec![first_txn]),
+            parent_block_id,
+            BLOCK_GAS_LIMIT,
+        )
         .unwrap();
     parent_block_id = first_block_id;
-    let second_block = TestBlock::new(10, 10, gen_block_id(2), executor.get_block_gas_limit());
+    let second_block = TestBlock::new(10, 10, gen_block_id(2), BLOCK_GAS_LIMIT);
     let output2 = executor
-        .execute_block((second_block.id, second_block.txns), parent_block_id)
+        .execute_block(
+            (second_block.id, second_block.txns),
+            parent_block_id,
+            BLOCK_GAS_LIMIT,
+        )
         .unwrap();
     assert_eq!(output1.root_hash(), output2.root_hash());
 }
@@ -589,24 +588,24 @@ fn test_reconfig_suffix_empty_blocks() {
         db: _,
         executor,
     } = TestExecutor::new();
-    // add gas limit to be consistent with block executor that will add state checkpoint txn
-    let block_a = TestBlock::new(10000, 1, gen_block_id(1), Some(0));
+    let block_a = TestBlock::new(10000, 1, gen_block_id(1), BLOCK_GAS_LIMIT);
+    // add block gas limit to be consistent with block executor that will add state checkpoint txn
     let mut block_b = TestBlock::new(10000, 1, gen_block_id(2), Some(0));
-    let block_c = TestBlock::new(1, 1, gen_block_id(3), Some(0));
-    let block_d = TestBlock::new(1, 1, gen_block_id(4), Some(0));
+    let block_c = TestBlock::new(1, 1, gen_block_id(3), BLOCK_GAS_LIMIT);
+    let block_d = TestBlock::new(1, 1, gen_block_id(4), BLOCK_GAS_LIMIT);
     block_b.txns.push(encode_reconfiguration_transaction());
     let parent_block_id = executor.committed_block_id();
     executor
-        .execute_block((block_a.id, block_a.txns), parent_block_id)
+        .execute_block((block_a.id, block_a.txns), parent_block_id, BLOCK_GAS_LIMIT)
         .unwrap();
     let output = executor
-        .execute_block((block_b.id, block_b.txns), block_a.id)
+        .execute_block((block_b.id, block_b.txns), block_a.id, BLOCK_GAS_LIMIT)
         .unwrap();
     executor
-        .execute_block((block_c.id, block_c.txns), block_b.id)
+        .execute_block((block_c.id, block_c.txns), block_b.id, BLOCK_GAS_LIMIT)
         .unwrap();
     executor
-        .execute_block((block_d.id, block_d.txns), block_c.id)
+        .execute_block((block_d.id, block_d.txns), block_c.id, BLOCK_GAS_LIMIT)
         .unwrap();
 
     let ledger_info = gen_ledger_info(20002, output.root_hash(), block_d.id, 1);
@@ -624,7 +623,12 @@ struct TestBlock {
 }
 
 impl TestBlock {
-    fn new(num_user_txns: u64, amount: u32, id: HashValue, maybe_gas_limit: Option) -> Self {
+    fn new(
+        num_user_txns: u64,
+        amount: u32,
+        id: HashValue,
+        maybe_block_gas_limit: Option,
+    ) -> Self {
         let txns = if num_user_txns == 0 {
             Vec::new()
         } else {
@@ -632,7 +636,7 @@ impl TestBlock {
                 (0..num_user_txns)
                     .map(|index| encode_mint_transaction(gen_address(index), u64::from(amount)))
                     .collect(),
-                maybe_gas_limit,
+                maybe_block_gas_limit,
             )
         };
         TestBlock { txns, id }
@@ -641,7 +645,10 @@ impl TestBlock {
 
 // Executes a list of transactions by executing and immediately committing one at a time. Returns
 // the root hash after all transactions are committed.
-fn run_transactions_naive(transactions: Vec) -> HashValue {
+fn run_transactions_naive(
+    transactions: Vec,
+    maybe_block_gas_limit: Option,
+) -> HashValue {
     let executor = TestExecutor::new();
     let db = &executor.db;
     let mut ledger_view: ExecutedTrees = db.reader.get_latest_executed_trees().unwrap();
@@ -656,6 +663,7 @@ fn run_transactions_naive(transactions: Vec) -> HashValue {
                     Arc::new(AsyncProofFetcher::new(db.reader.clone())),
                 )
                 .unwrap(),
+            maybe_block_gas_limit,
         )
         .unwrap();
         let (executed, _, _) = out.apply_to_ledger(&ledger_view, None).unwrap();
@@ -689,13 +697,13 @@ proptest! {
             let executor = TestExecutor::new();
 
             let block_id = gen_block_id(1);
-            let mut block = TestBlock::new(num_user_txns, 10, block_id, executor.get_block_gas_limit());
+            let mut block = TestBlock::new(num_user_txns, 10, block_id, BLOCK_GAS_LIMIT);
             let num_txns = block.txns.len() as LeafCount;
             block.txns[reconfig_txn_index as usize] = encode_reconfiguration_transaction();
 
             let parent_block_id = executor.committed_block_id();
             let output = executor.execute_block(
-                (block_id, block.txns.clone()), parent_block_id
+                (block_id, block.txns.clone()), parent_block_id, BLOCK_GAS_LIMIT
             ).unwrap();
 
             // assert: txns after the reconfiguration are with status "Retry"
@@ -714,11 +722,11 @@ proptest! {
             // retry txns after reconfiguration
             let retry_block_id = gen_block_id(2);
             let retry_output = executor.execute_block(
-                (retry_block_id, block.txns.iter().skip(reconfig_txn_index as usize + 1).cloned().collect()), parent_block_id
+                (retry_block_id, block.txns.iter().skip(reconfig_txn_index as usize + 1).cloned().collect()), parent_block_id, BLOCK_GAS_LIMIT
             ).unwrap();
             prop_assert!(retry_output.compute_status().iter().all(|s| matches!(*s, TransactionStatus::Keep(_))));
 
-            let ledger_version = ledger_version_from_block_size(num_txns as usize, executor.get_block_gas_limit()) as u64;
+            let ledger_version = ledger_version_from_block_size(num_txns as usize, BLOCK_GAS_LIMIT) as u64;
 
             // commit
             let ledger_info = gen_ledger_info(ledger_version, retry_output.root_hash(), retry_block_id, 12345 /* timestamp */);
@@ -750,22 +758,20 @@ proptest! {
     fn test_executor_restart(a_size in 1..30u64, b_size in 1..30u64, amount in any::()) {
         let TestExecutor { _path, db, executor } = TestExecutor::new();
 
-        let block_a = TestBlock::new(a_size, amount, gen_block_id(1), executor.get_block_gas_limit());
-        let block_b = TestBlock::new(b_size, amount, gen_block_id(2), executor.get_block_gas_limit());
+        let block_a = TestBlock::new(a_size, amount, gen_block_id(1), BLOCK_GAS_LIMIT);
+        let block_b = TestBlock::new(b_size, amount, gen_block_id(2), BLOCK_GAS_LIMIT);
 
         let mut parent_block_id;
         let mut root_hash;
 
-        let maybe_gas_limit = executor.get_block_gas_limit();
-
         // First execute and commit one block, then destroy executor.
         {
             parent_block_id = executor.committed_block_id();
             let output_a = executor.execute_block(
-                (block_a.id, block_a.txns.clone()), parent_block_id
+                (block_a.id, block_a.txns.clone()), parent_block_id, BLOCK_GAS_LIMIT
             ).unwrap();
             root_hash = output_a.root_hash();
-            let ledger_info = gen_ledger_info(ledger_version_from_block_size(block_a.txns.len(), maybe_gas_limit) as u64, root_hash, block_a.id, 1);
+            let ledger_info = gen_ledger_info(ledger_version_from_block_size(block_a.txns.len(), BLOCK_GAS_LIMIT) as u64, root_hash, block_a.id, 1);
             executor.commit_blocks(vec![block_a.id], ledger_info).unwrap();
             parent_block_id = block_a.id;
         }
@@ -773,11 +779,10 @@ proptest! {
         // Now we construct a new executor and run one more block.
         {
             let executor = BlockExecutor::::new(db);
-            executor.update_block_gas_limit(maybe_gas_limit);
-            let output_b = executor.execute_block((block_b.id, block_b.txns.clone()), parent_block_id).unwrap();
+            let output_b = executor.execute_block((block_b.id, block_b.txns.clone()), parent_block_id, BLOCK_GAS_LIMIT).unwrap();
             root_hash = output_b.root_hash();
             let ledger_info = gen_ledger_info(
-                (ledger_version_from_block_size(block_a.txns.len(), maybe_gas_limit) + ledger_version_from_block_size(block_b.txns.len(), maybe_gas_limit)) as u64,
+                (ledger_version_from_block_size(block_a.txns.len(), BLOCK_GAS_LIMIT) + ledger_version_from_block_size(block_b.txns.len(), BLOCK_GAS_LIMIT)) as u64,
                 root_hash,
                 block_b.id,
                 2,
@@ -788,15 +793,15 @@ proptest! {
         let expected_root_hash = run_transactions_naive({
             let mut txns = vec![];
             txns.extend(block_a.txns.iter().cloned());
-            if executor.get_block_gas_limit().is_some() {
+            if BLOCK_GAS_LIMIT.is_some() {
                 txns.push(Transaction::StateCheckpoint(block_a.id));
             }
             txns.extend(block_b.txns.iter().cloned());
-            if executor.get_block_gas_limit().is_some() {
+            if BLOCK_GAS_LIMIT.is_some() {
                 txns.push(Transaction::StateCheckpoint(block_b.id));
             }
             txns
-        });
+        }, BLOCK_GAS_LIMIT);
         prop_assert_eq!(root_hash, expected_root_hash);
     }
 
@@ -832,13 +837,13 @@ proptest! {
         let first_block_id = gen_block_id(1);
         let _output1 = executor.execute_block(
             (first_block_id, first_block_txns),
-            parent_block_id
+            parent_block_id, BLOCK_GAS_LIMIT
         ).unwrap();
 
         let second_block_id = gen_block_id(2);
         let output2 = executor.execute_block(
-            (second_block_id, block(second_block_txns, executor.get_block_gas_limit())),
-            first_block_id,
+            (second_block_id, block(second_block_txns, BLOCK_GAS_LIMIT)),
+            first_block_id, BLOCK_GAS_LIMIT
         ).unwrap();
 
         let version = chunk_size + overlap_size + num_new_txns + 1;
diff --git a/execution/executor/tests/db_bootstrapper_test.rs b/execution/executor/tests/db_bootstrapper_test.rs
index 0ccbf3e8a237e..f6b7f0c946e51 100644
--- a/execution/executor/tests/db_bootstrapper_test.rs
+++ b/execution/executor/tests/db_bootstrapper_test.rs
@@ -30,7 +30,7 @@ use aptos_types::{
     event::EventHandle,
     on_chain_config::{access_path_for_config, ConfigurationResource, OnChainConfig, ValidatorSet},
     state_store::state_key::StateKey,
-    test_helpers::transaction_test_helpers::block,
+    test_helpers::transaction_test_helpers::{block, BLOCK_GAS_LIMIT},
     transaction::{authenticator::AuthenticationKey, ChangeSet, Transaction, WriteSetPayload},
     trusted_state::TrustedState,
     validator_signer::ValidatorSigner,
@@ -87,8 +87,9 @@ fn execute_and_commit(txns: Vec, db: &DbReaderWriter, signer: &Vali
     let executor = BlockExecutor::::new(db.clone());
     let output = executor
         .execute_block(
-            (block_id, block(txns, executor.get_block_gas_limit())),
+            (block_id, block(txns, BLOCK_GAS_LIMIT)),
             executor.committed_block_id(),
+            BLOCK_GAS_LIMIT,
         )
         .unwrap();
     assert_eq!(output.num_leaves(), target_version + 1);
diff --git a/execution/executor/tests/storage_integration_test.rs b/execution/executor/tests/storage_integration_test.rs
index e986325192e8b..158ccf2f391ef 100644
--- a/execution/executor/tests/storage_integration_test.rs
+++ b/execution/executor/tests/storage_integration_test.rs
@@ -19,6 +19,7 @@ use aptos_types::{
     account_view::AccountView,
     block_metadata::BlockMetadata,
     state_store::state_key::StateKey,
+    test_helpers::transaction_test_helpers::BLOCK_GAS_LIMIT,
     transaction::{Transaction, WriteSetPayload},
     trusted_state::TrustedState,
     validator_signer::ValidatorSigner,
@@ -139,7 +140,11 @@ fn test_reconfiguration() {
     let txn_block = vec![txn1, txn2, txn3];
     let block_id = gen_block_id(1);
     let vm_output = executor
-        .execute_block((block_id, txn_block.clone()), parent_block_id)
+        .execute_block(
+            (block_id, txn_block.clone()),
+            parent_block_id,
+            BLOCK_GAS_LIMIT,
+        )
         .unwrap();
 
     // Make sure the execution result sees the reconfiguration
diff --git a/types/src/test_helpers/transaction_test_helpers.rs b/types/src/test_helpers/transaction_test_helpers.rs
index 9d4d1de16bc56..eac86008f93a2 100644
--- a/types/src/test_helpers/transaction_test_helpers.rs
+++ b/types/src/test_helpers/transaction_test_helpers.rs
@@ -15,6 +15,10 @@ use aptos_crypto::{ed25519::*, traits::*, HashValue};
 const MAX_GAS_AMOUNT: u64 = 1_000_000;
 const TEST_GAS_PRICE: u64 = 100;
 
+// The block gas limit parameter for executor tests
+pub const BLOCK_GAS_LIMIT: Option = Some(1000);
+// pub const BLOCK_GAS_LIMIT: Option = None;
+
 static EMPTY_SCRIPT: &[u8] = include_bytes!("empty_script.mv");
 
 // Create an expiration time 'seconds' after now
@@ -239,8 +243,11 @@ pub fn get_test_txn_with_chain_id(
     SignedTransaction::new(raw_txn, public_key, signature)
 }
 
-pub fn block(mut user_txns: Vec, maybe_gas_limit: Option) -> Vec {
-    if maybe_gas_limit.is_none() {
+pub fn block(
+    mut user_txns: Vec,
+    maybe_block_gas_limit: Option,
+) -> Vec {
+    if maybe_block_gas_limit.is_none() {
         user_txns.push(Transaction::StateCheckpoint(HashValue::random()));
     }
     user_txns

From 943c21d11f170f99026b0a4f350b43e2907320e6 Mon Sep 17 00:00:00 2001
From: Josh Lind 
Date: Tue, 30 May 2023 11:58:34 -0400
Subject: [PATCH 011/200] [Aptos Node] Bump cargo version of aptos-node to 1.5

---
 Cargo.lock            | 2 +-
 aptos-node/Cargo.toml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 57cff9fada9a5..11dba01eeda23 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2195,7 +2195,7 @@ dependencies = [
 
 [[package]]
 name = "aptos-node"
-version = "1.4.0"
+version = "1.5.0"
 dependencies = [
  "anyhow",
  "aptos-api",
diff --git a/aptos-node/Cargo.toml b/aptos-node/Cargo.toml
index 5602a99daf5b0..3700ba1d82de0 100644
--- a/aptos-node/Cargo.toml
+++ b/aptos-node/Cargo.toml
@@ -1,7 +1,7 @@
 [package]
 name = "aptos-node"
 description = "Aptos node"
-version = "1.4.0"
+version = "1.5.0"
 
 # Workspace inherited keys
 authors = { workspace = true }

From 7367f15829422bce46f74ce779bec56d4c14f548 Mon Sep 17 00:00:00 2001
From: Bo Wu 
Date: Wed, 31 May 2023 10:11:56 -0700
Subject: [PATCH 012/200] [storage] explicitly request a valid target version
 in db restore

---
 .../backup/backup-cli/src/coordinators/restore.rs    | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/storage/backup/backup-cli/src/coordinators/restore.rs b/storage/backup/backup-cli/src/coordinators/restore.rs
index a4f054f6a96f6..db85a91e90740 100644
--- a/storage/backup/backup-cli/src/coordinators/restore.rs
+++ b/storage/backup/backup-cli/src/coordinators/restore.rs
@@ -119,13 +119,17 @@ impl RestoreCoordinator {
         )
         .await?;
 
-        let target_version = self.global_opt.target_version;
-        COORDINATOR_TARGET_VERSION.set(target_version as i64);
-
         // calculate the start_version and replay_version
         let max_txn_ver = metadata_view
             .max_transaction_version()?
             .ok_or_else(|| anyhow!("No transaction backup found."))?;
+        let target_version = std::cmp::min(self.global_opt.target_version, max_txn_ver);
+        info!(
+            "User specified target version: {}, max transaction version: {}, Target version is set to {}",
+            self.global_opt.target_version, max_txn_ver, target_version
+        );
+
+        COORDINATOR_TARGET_VERSION.set(target_version as i64);
         let lhs = self.ledger_history_start_version();
 
         let latest_tree_version = self
@@ -185,7 +189,7 @@ impl RestoreCoordinator {
             snapshot.unwrap()
         } else {
             metadata_view
-                .select_state_snapshot(std::cmp::min(self.target_version(), max_txn_ver))?
+                .select_state_snapshot(target_version)?
                 .expect("Cannot find tree snapshot before target version")
         };
 

From 846e5b93a555b819f6a0f58ed4949b0057cdd1c5 Mon Sep 17 00:00:00 2001
From: Bo Wu 
Date: Wed, 24 May 2023 10:23:07 -0700
Subject: [PATCH 013/200] [storage] reuse previous test

---
 testsuite/smoke-test/src/genesis.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/testsuite/smoke-test/src/genesis.rs b/testsuite/smoke-test/src/genesis.rs
index 0094584e89613..abf21ef8bb505 100644
--- a/testsuite/smoke-test/src/genesis.rs
+++ b/testsuite/smoke-test/src/genesis.rs
@@ -233,7 +233,7 @@ async fn test_genesis_transaction_flow() {
         (response.inner().epoch, response.inner().version)
     };
 
-    let (backup_path, snapshot_ver) = db_backup(
+    let (backup_path, _) = db_backup(
         env.validators()
             .next()
             .unwrap()
@@ -272,7 +272,7 @@ async fn test_genesis_transaction_flow() {
         db_dir.as_path(),
         &[waypoint],
         node.config().storage.rocksdb_configs.use_state_kv_db,
-        Some(snapshot_ver),
+        None,
     );
 
     node.start().unwrap();

From d1e15cde208f383148c66bdc1dd1b0de480af9d2 Mon Sep 17 00:00:00 2001
From: Rati Gelashvili 
Date: Thu, 1 Jun 2023 00:40:28 -0400
Subject: [PATCH 014/200] fix flush error when running tests concurrently
 (#8453)

---
 aptos-move/aptos-vm/src/block_executor/mod.rs | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/aptos-move/aptos-vm/src/block_executor/mod.rs b/aptos-move/aptos-vm/src/block_executor/mod.rs
index 2d9b3d9d93514..9679e2a01e962 100644
--- a/aptos-move/aptos-vm/src/block_executor/mod.rs
+++ b/aptos-move/aptos-vm/src/block_executor/mod.rs
@@ -23,7 +23,7 @@ use aptos_block_executor::{
     },
 };
 use aptos_infallible::Mutex;
-use aptos_state_view::StateView;
+use aptos_state_view::{StateView, StateViewId};
 use aptos_types::{
     state_store::state_key::StateKey,
     transaction::{Transaction, TransactionOutput, TransactionStatus},
@@ -156,7 +156,11 @@ impl BlockAptosVM {
         drop(signature_verification_timer);
 
         let num_txns = signature_verified_block.len();
-        init_speculative_logs(num_txns);
+        if state_view.id() != StateViewId::Miscellaneous {
+            // Speculation is disabled in Miscellaneous context, which is used by testing and
+            // can even lead to concurrent execute_block invocations, leading to errors on flush.
+            init_speculative_logs(num_txns);
+        }
 
         BLOCK_EXECUTOR_CONCURRENCY.set(concurrency_level as i64);
         let executor = BlockExecutor::, S>::new(
@@ -177,7 +181,11 @@ impl BlockAptosVM {
                 // Flush the speculative logs of the committed transactions.
                 let pos = output_vec.partition_point(|o| !o.status().is_retry());
 
-                flush_speculative_logs(pos);
+                if state_view.id() != StateViewId::Miscellaneous {
+                    // Speculation is disabled in Miscellaneous context, which is used by testing and
+                    // can even lead to concurrent execute_block invocations, leading to errors on flush.
+                    flush_speculative_logs(pos);
+                }
 
                 Ok(output_vec)
             },

From 55a27cc092113b3d05457f7432860f309d4dbc1c Mon Sep 17 00:00:00 2001
From: Jin <128556004+0xjinn@users.noreply.github.com>
Date: Wed, 31 May 2023 21:57:02 -0700
Subject: [PATCH 015/200] [aptos-ledger] added fetching and update get public
 key method (#8342)

* added fetching and update get public key method

* fixes from comment

* update method comment, and change fetch range limit from 20 to 10
---
 Cargo.lock                     |   2 +
 crates/aptos-ledger/Cargo.toml |   8 ++-
 crates/aptos-ledger/src/lib.rs | 110 +++++++++++++++++++++++++++++----
 3 files changed, 106 insertions(+), 14 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 11dba01eeda23..7fbdbb1f3c7ba 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1874,6 +1874,8 @@ dependencies = [
 name = "aptos-ledger"
 version = "0.2.0"
 dependencies = [
+ "aptos-crypto",
+ "aptos-types",
  "hex",
  "ledger-apdu",
  "ledger-transport-hid",
diff --git a/crates/aptos-ledger/Cargo.toml b/crates/aptos-ledger/Cargo.toml
index c5400c2a104ed..50032bcb9cc42 100644
--- a/crates/aptos-ledger/Cargo.toml
+++ b/crates/aptos-ledger/Cargo.toml
@@ -13,8 +13,10 @@ repository = "https://github.com/aptos-labs/aptos-core/tree/main/crates/aptos-le
 rust-version = { workspace = true }
 
 [dependencies]
-hex = "0.4.3"
+aptos-crypto = { workspace = true }
+aptos-types = { workspace = true }
+hex = { workspace = true }
 ledger-apdu = "0.10.0"
 ledger-transport-hid = "0.10.0"
-once_cell = "1.10.0"
-thiserror = "1.0.37"
+once_cell = { workspace = true }
+thiserror = { workspace = true }
diff --git a/crates/aptos-ledger/src/lib.rs b/crates/aptos-ledger/src/lib.rs
index 461cd6b489e4d..72f9812d100bc 100644
--- a/crates/aptos-ledger/src/lib.rs
+++ b/crates/aptos-ledger/src/lib.rs
@@ -7,21 +7,24 @@
 
 #![deny(missing_docs)]
 
+use aptos_crypto::{ed25519::Ed25519PublicKey, ValidCryptoMaterialStringExt};
+use aptos_types::{account_address::AccountAddress, transaction::authenticator::AuthenticationKey};
 use hex::encode;
 use ledger_apdu::APDUCommand;
 use ledger_transport_hid::{hidapi::HidApi, LedgerHIDError, TransportNativeHID};
-use once_cell::sync::Lazy;
 use std::{
+    collections::HashMap,
     fmt,
     fmt::{Debug, Display},
+    ops::Range,
     str,
+    string::ToString,
 };
 use thiserror::Error;
 
 // A piece of data which tells a wallet how to derive a specific key within a tree of keys
 // 637 is the key for Aptos
-// TODO: Add support for multiple index
-const DERIVATIVE_PATH: &str = "m/44'/637'/0'/0'/0'";
+const DERIVATIVE_PATH: &str = "m/44'/637'/{index}'/0'/0'";
 
 const CLA_APTOS: u8 = 0x5B; // Aptos CLA Instruction class
 const INS_GET_VERSION: u8 = 0x03; // Get version instruction code
@@ -37,8 +40,6 @@ const P1_START: u8 = 0x00;
 const P2_MORE: u8 = 0x80;
 const P2_LAST: u8 = 0x00;
 
-static SERIALIZED_BIP32: Lazy> = Lazy::new(|| serialize_bip32(DERIVATIVE_PATH));
-
 #[derive(Debug, Error)]
 /// Aptos Ledger Error
 pub enum AptosLedgerError {
@@ -143,17 +144,96 @@ pub fn get_app_name() -> Result {
     }
 }
 
-/// Returns the public key of your Aptos account in Ledger device
+/// Returns the the batch/HashMap of the accounts for the account index in index_range
+/// Note: We only allow a range of 10 for performance purpose
+///
+/// # Arguments
+///
+/// * `index_range` - start(inclusive) - end(exclusive) acounts, that you want to fetch, if None default to 0-10
+pub fn fetch_batch_accounts(
+    index_range: Option>,
+) -> Result, AptosLedgerError> {
+    let range = if let Some(range) = index_range {
+        range
+    } else {
+        0..10
+    };
+
+    // Make sure the range is within 10 counts
+    if range.end - range.start > 10 {
+        return Err(AptosLedgerError::UnexpectedError(
+            "Unexpected Error: Make sure the range is less than or equal to 10".to_string(),
+            None,
+        ));
+    }
+
+    // Open connection to ledger
+    let transport = open_ledger_transport()?;
+
+    let mut accounts = HashMap::new();
+    for i in range {
+        let path = DERIVATIVE_PATH.replace("{index}", &i.to_string());
+        let cdata = serialize_bip32(&path);
+
+        match transport.exchange(&APDUCommand {
+            cla: CLA_APTOS,
+            ins: INS_GET_PUB_KEY,
+            p1: P1_NON_CONFIRM,
+            p2: P2_LAST,
+            data: cdata,
+        }) {
+            Ok(response) => {
+                // Got the response from ledger after user has confirmed on the ledger wallet
+                if response.retcode() == APDU_CODE_SUCCESS {
+                    // Extract the Public key from the response data
+                    let mut offset = 0;
+                    let response_buffer = response.data();
+                    let pub_key_len: usize = (response_buffer[offset] - 1).into();
+                    offset += 1;
+
+                    // Skipping weird 0x04 - because of how the Aptos Ledger parse works when return pub key
+                    offset += 1;
+
+                    let pub_key_buffer = response_buffer[offset..offset + pub_key_len].to_vec();
+                    let hex_string = encode(pub_key_buffer);
+                    let public_key = match Ed25519PublicKey::from_encoded_string(&hex_string) {
+                        Ok(pk) => Ok(pk),
+                        Err(err) => Err(AptosLedgerError::UnexpectedError(
+                            err.to_string(),
+                            Some(response.retcode()),
+                        )),
+                    };
+                    let account = account_address_from_public_key(&public_key?);
+                    accounts.insert(path, account);
+                } else {
+                    let error_string = response
+                        .error_code()
+                        .map(|error_code| error_code.to_string())
+                        .unwrap_or_else(|retcode| format!("Error with retcode: {:x}", retcode));
+                    return Err(AptosLedgerError::UnexpectedError(
+                        error_string,
+                        Option::from(response.retcode()),
+                    ));
+                }
+            },
+            Err(err) => return Err(AptosLedgerError::from(err)),
+        }
+    }
+
+    Ok(accounts)
+}
+
+/// Returns the public key of your Aptos account in Ledger device at index 0
 ///
 /// # Arguments
 ///
 /// * `display` - If true, the public key will be displayed on the Ledger device, and confirmation is needed
-pub fn get_public_key(display: bool) -> Result {
+pub fn get_public_key(path: &str, display: bool) -> Result {
     // Open connection to ledger
     let transport = open_ledger_transport()?;
 
     // Serialize the derivative path
-    let cdata = SERIALIZED_BIP32.clone();
+    let cdata = serialize_bip32(path);
 
     // APDU command's instruction parameter 1 or p1
     let p1: u8 = match display {
@@ -182,7 +262,10 @@ pub fn get_public_key(display: bool) -> Result {
 
                 let pub_key_buffer = response_buffer[offset..offset + pub_key_len].to_vec();
                 let hex_string = encode(pub_key_buffer);
-                Ok(hex_string)
+                match Ed25519PublicKey::from_encoded_string(&hex_string) {
+                    Ok(pk) => Ok(pk),
+                    Err(err) => Err(AptosLedgerError::UnexpectedError(err.to_string(), None)),
+                }
             } else {
                 let error_string = response
                     .error_code()
@@ -203,12 +286,12 @@ pub fn get_public_key(display: bool) -> Result {
 /// # Arguments
 ///
 /// * `raw_txn` - the serialized raw transaction that need to be signed
-pub fn sign_txn(raw_txn: Vec) -> Result, AptosLedgerError> {
+pub fn sign_txn(path: &str, raw_txn: Vec) -> Result, AptosLedgerError> {
     // open connection to ledger
     let transport = open_ledger_transport()?;
 
     // Serialize the derivative path
-    let derivative_path_bytes = SERIALIZED_BIP32.clone();
+    let derivative_path_bytes = serialize_bip32(path);
 
     // Send the derivative path over as first message
     let sign_start = transport.exchange(&APDUCommand {
@@ -307,3 +390,8 @@ fn open_ledger_transport() -> Result {
 
     Ok(transport)
 }
+
+fn account_address_from_public_key(public_key: &Ed25519PublicKey) -> AccountAddress {
+    let auth_key = AuthenticationKey::ed25519(public_key);
+    AccountAddress::new(*auth_key.derived_address())
+}

From 931f8105a89a8f3b72facfba464ab885bf28c81a Mon Sep 17 00:00:00 2001
From: "Daniel Porteous (dport)" 
Date: Thu, 1 Jun 2023 05:58:42 +0100
Subject: [PATCH 016/200] Add get-latest-cli action (#8447)

---
 .github/actions/get-latest-cli/action.yaml | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)
 create mode 100644 .github/actions/get-latest-cli/action.yaml

diff --git a/.github/actions/get-latest-cli/action.yaml b/.github/actions/get-latest-cli/action.yaml
new file mode 100644
index 0000000000000..edc450368f63f
--- /dev/null
+++ b/.github/actions/get-latest-cli/action.yaml
@@ -0,0 +1,21 @@
+name: "Get latest Aptos CLI"
+description: |
+  Fetches the latest released Aptos CLI.
+inputs:
+  destination_directory:
+    description: "Directory to install the CLI in"
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Setup python
+      uses: actions/setup-python@13ae5bb136fac2878aff31522b9efb785519f984 # pin@v4
+    - name: Get installation script
+      shell: bash
+      run: |
+        curl -fsSL "https://aptos.dev/scripts/install_cli.py" > install_cli.py
+    - name: Run installation script
+      shell: bash
+      run: |
+        python3 install_cli.py --bin-dir ${{ inputs.destination_directory }}

From 1c84db68e6904db0599646b2e25236ffef73e8f5 Mon Sep 17 00:00:00 2001
From: Junkil Park 
Date: Wed, 31 May 2023 22:23:53 -0700
Subject: [PATCH 017/200] Added a typescript client for the Ambassador token
 example (#8200)

---
 .../token_objects/ambassador/Move.toml        |  10 +
 .../token_objects/ambassador/move/Move.toml   |  10 -
 .../{move => }/sources/ambassador.move        |  41 ++++-
 .../sdk/examples/typescript/ambassador.ts     | 171 ++++++++++++++++++
 .../typescript/metadata/ambassador/Bronze     |   6 +
 .../typescript/metadata/ambassador/Bronze.png | Bin 0 -> 740712 bytes
 .../typescript/metadata/ambassador/Gold       |   6 +
 .../typescript/metadata/ambassador/Gold.png   | Bin 0 -> 1149061 bytes
 .../typescript/metadata/ambassador/Silver     |   6 +
 .../typescript/metadata/ambassador/Silver.png | Bin 0 -> 709378 bytes
 .../sdk/examples/typescript/package.json      |   5 +-
 .../sdk/examples/typescript/pnpm-lock.yaml    | 110 ++++++-----
 testsuite/module-publish/src/main.rs          |   2 +-
 13 files changed, 304 insertions(+), 63 deletions(-)
 create mode 100644 aptos-move/move-examples/token_objects/ambassador/Move.toml
 delete mode 100644 aptos-move/move-examples/token_objects/ambassador/move/Move.toml
 rename aptos-move/move-examples/token_objects/ambassador/{move => }/sources/ambassador.move (88%)
 create mode 100644 ecosystem/typescript/sdk/examples/typescript/ambassador.ts
 create mode 100644 ecosystem/typescript/sdk/examples/typescript/metadata/ambassador/Bronze
 create mode 100644 ecosystem/typescript/sdk/examples/typescript/metadata/ambassador/Bronze.png
 create mode 100644 ecosystem/typescript/sdk/examples/typescript/metadata/ambassador/Gold
 create mode 100644 ecosystem/typescript/sdk/examples/typescript/metadata/ambassador/Gold.png
 create mode 100644 ecosystem/typescript/sdk/examples/typescript/metadata/ambassador/Silver
 create mode 100644 ecosystem/typescript/sdk/examples/typescript/metadata/ambassador/Silver.png

diff --git a/aptos-move/move-examples/token_objects/ambassador/Move.toml b/aptos-move/move-examples/token_objects/ambassador/Move.toml
new file mode 100644
index 0000000000000..7a3cded854dab
--- /dev/null
+++ b/aptos-move/move-examples/token_objects/ambassador/Move.toml
@@ -0,0 +1,10 @@
+[package]
+name = 'ambassador_token'
+version = '1.0.0'
+
+[addresses]
+token_objects = "0xCAFE"
+
+[dependencies]
+AptosFramework = { local = "../../../framework/aptos-framework" }
+AptosTokenObjects = { local = "../../../framework/aptos-token-objects" }
diff --git a/aptos-move/move-examples/token_objects/ambassador/move/Move.toml b/aptos-move/move-examples/token_objects/ambassador/move/Move.toml
deleted file mode 100644
index 00e7a47c45b47..0000000000000
--- a/aptos-move/move-examples/token_objects/ambassador/move/Move.toml
+++ /dev/null
@@ -1,10 +0,0 @@
-[package]
-name = 'ambassador_token'
-version = '1.0.0'
-
-[addresses]
-token_objects = "0xCAFE"
-
-[dependencies]
-AptosFramework = { local = "../../../../framework/aptos-framework" }
-AptosTokenObjects = { local = "../../../../framework/aptos-token-objects" }
diff --git a/aptos-move/move-examples/token_objects/ambassador/move/sources/ambassador.move b/aptos-move/move-examples/token_objects/ambassador/sources/ambassador.move
similarity index 88%
rename from aptos-move/move-examples/token_objects/ambassador/move/sources/ambassador.move
rename to aptos-move/move-examples/token_objects/ambassador/sources/ambassador.move
index c379bb6d033c0..5c86020ebddf1 100644
--- a/aptos-move/move-examples/token_objects/ambassador/move/sources/ambassador.move
+++ b/aptos-move/move-examples/token_objects/ambassador/sources/ambassador.move
@@ -8,6 +8,8 @@
 /// The rank is determined by the level such that the rank is Bronze if the level is between 0 and 9,
 /// Silver if the level is between 10 and 19, and Gold if the level is 20 or greater.
 /// The rank is stored in the property map, thus displayed in a wallet as a trait of the token.
+/// The token uri is the concatenation of the base uri and the rank, where the base uri is given
+/// as an argument of the minting function. So, the token uri changes when the rank changes.
 module token_objects::ambassador {
     use std::error;
     use std::option;
@@ -47,12 +49,16 @@ module token_objects::ambassador {
 
     /// The ambassador token
     struct AmbassadorToken has key {
+        /// Used to mutate the token uri
+        mutator_ref: token::MutatorRef,
         /// Used to burn.
         burn_ref: token::BurnRef,
         /// Used to mutate properties
         property_mutator_ref: property_map::MutatorRef,
         /// Used to emit LevelUpdateEvent
         level_update_events: event::EventHandle,
+        /// the base URI of the token
+        base_uri: String,
     }
 
     /// The ambassador level
@@ -86,6 +92,20 @@ module token_objects::ambassador {
         property_map::read_string(&token, &string::utf8(b"Rank"))
     }
 
+    #[view]
+    /// Returns the ambassador level of the token of the address
+    public fun ambassador_level_from_address(addr: address): u64 acquires AmbassadorLevel {
+        let token = object::address_to_object(addr);
+        ambassador_level(token)
+    }
+
+    #[view]
+    /// Returns the ambassador rank of the token of the address
+    public fun ambassador_rank_from_address(addr: address): String {
+        let token = object::address_to_object(addr);
+        ambassador_rank(token)
+    }
+
     /// Creates the ambassador collection. This function creates a collection with unlimited supply using
     /// the module constants for description, name, and URI, defined above. The collection will not have
     /// any royalty configuration because the tokens in this collection will not be transferred or sold.
@@ -121,13 +141,15 @@ module token_objects::ambassador {
         creator: &signer,
         description: String,
         name: String,
-        uri: String,
+        base_uri: String,
         soul_bound_to: address,
     ) {
         // The collection name is used to locate the collection object and to create a new token object.
         let collection = string::utf8(COLLECTION_NAME);
         // Creates the ambassador token, and get the constructor ref of the token. The constructor ref
         // is used to generate the refs of the token.
+        let uri = base_uri;
+        string::append(&mut uri, string::utf8(RANK_BRONZE));
         let constructor_ref = token::create_named_token(
             creator,
             collection,
@@ -141,6 +163,7 @@ module token_objects::ambassador {
         // (e.g., AmbassadorLevel) under the token object address. The refs are used to manage the token.
         let object_signer = object::generate_signer(&constructor_ref);
         let transfer_ref = object::generate_transfer_ref(&constructor_ref);
+        let mutator_ref = token::generate_mutator_ref(&constructor_ref);
         let burn_ref = token::generate_burn_ref(&constructor_ref);
         let property_mutator_ref = property_map::generate_mutator_ref(&constructor_ref);
 
@@ -165,9 +188,11 @@ module token_objects::ambassador {
 
         // Publishes the AmbassadorToken resource with the refs and the event handle for `LevelUpdateEvent`.
         let ambassador_token = AmbassadorToken {
+            mutator_ref,
             burn_ref,
             property_mutator_ref,
             level_update_events: object::new_event_handle(&object_signer),
+            base_uri
         };
         move_to(&object_signer, ambassador_token);
     }
@@ -178,9 +203,11 @@ module token_objects::ambassador {
         authorize_creator(creator, &token);
         let ambassador_token = move_from(object::object_address(&token));
         let AmbassadorToken {
+            mutator_ref: _,
             burn_ref,
             property_mutator_ref,
             level_update_events,
+            base_uri: _
         } = ambassador_token;
 
         event::destroy_handle(level_update_events);
@@ -229,10 +256,15 @@ module token_objects::ambassador {
         };
 
         let token_address = object::object_address(&token);
+        let ambassador_token = borrow_global(token_address);
         // Gets `property_mutator_ref` to update the rank in the property map.
-        let property_mutator_ref = &borrow_global(token_address).property_mutator_ref;
+        let property_mutator_ref = &ambassador_token.property_mutator_ref;
         // Updates the rank in the property map.
         property_map::update_typed(property_mutator_ref, &string::utf8(b"Rank"), string::utf8(new_rank));
+        // Updates the token URI based on the new rank.
+        let uri = ambassador_token.base_uri;
+        string::append(&mut uri, string::utf8(new_rank));
+        token::set_uri(&ambassador_token.mutator_ref, uri);
     }
 
     /// Authorizes the creator of the token. Asserts that the token exists and the creator of the token
@@ -261,7 +293,7 @@ module token_objects::ambassador {
         // -------------------------------------------
         let token_name = string::utf8(b"Ambassador Token #1");
         let token_description = string::utf8(b"Ambassador Token #1 Description");
-        let token_uri = string::utf8(b"Ambassador Token #1 URI");
+        let token_uri = string::utf8(b"Ambassador Token #1 URI/");
         let user1_addr = signer::address_of(user1);
         // Creates the Ambassador token for User1.
         mint_ambassador_token(
@@ -288,12 +320,13 @@ module token_objects::ambassador {
         assert!(ambassador_level(token) == 0, 2);
         // Asserts that the initial rank of the token is "Bronze".
         assert!(ambassador_rank(token) == string::utf8(RANK_BRONZE), 3);
+        assert!(token::uri(token) == string::utf8(b"Ambassador Token #1 URI/Bronze"), 4);
         // `creator` sets the level to 15.
         set_ambassador_level(creator, token, 15);
         // Asserts that the level is updated to 15.
         assert!(ambassador_level(token) == 15, 4);
         // Asserts that the rank is updated to "Silver" which is the expected rank for level 15.
-        assert!(ambassador_rank(token) == string::utf8(RANK_SILVER), 5);
+        assert!(token::uri(token) == string::utf8(b"Ambassador Token #1 URI/Silver"), 5);
 
         // ------------------------
         // Creator burns the token.
diff --git a/ecosystem/typescript/sdk/examples/typescript/ambassador.ts b/ecosystem/typescript/sdk/examples/typescript/ambassador.ts
new file mode 100644
index 0000000000000..2e5eab2e9581b
--- /dev/null
+++ b/ecosystem/typescript/sdk/examples/typescript/ambassador.ts
@@ -0,0 +1,171 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+import { AptosAccount, HexString, Provider, Network, Types, FaucetClient, BCS } from "aptos";
+import { NODE_URL, FAUCET_URL } from "./common";
+
+const provider = new Provider(Network.DEVNET);
+const faucetClient = new FaucetClient(NODE_URL, FAUCET_URL);
+
+async function getTokenAddr(ownerAddr: HexString, tokenName: string): Promise {
+  const tokenOwnership = await provider.getOwnedTokens(ownerAddr);
+  for (const ownership of tokenOwnership.current_token_ownerships_v2) {
+    if (ownership.current_token_data.token_name === tokenName) {
+      return new HexString(ownership.current_token_data.token_data_id);
+    }
+  }
+  console.log(`Token ${tokenName} not found`);
+  process.exit(1);
+}
+
+async function waitForEnter() {
+  return new Promise((resolve, reject) => {
+    const rl = require("readline").createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    rl.question("Please press the Enter key to proceed ...\n", () => {
+      rl.close();
+      resolve();
+    });
+  });
+}
+
+class AmbassadorClient {
+  async setAmbassadorLevel(
+    creator: AptosAccount,
+    token: HexString,
+    new_ambassador_level: BCS.AnyNumber,
+  ): Promise {
+    const rawTxn = await provider.generateTransaction(creator.address(), {
+      function: `${creator.address()}::ambassador::set_ambassador_level`,
+      type_arguments: [],
+      arguments: [token.hex(), new_ambassador_level],
+    });
+
+    const bcsTxn = await provider.signTransaction(creator, rawTxn);
+    const pendingTxn = await provider.submitTransaction(bcsTxn);
+
+    return pendingTxn.hash;
+  }
+
+  async burn(creator: AptosAccount, token: HexString): Promise {
+    const rawTxn = await provider.generateTransaction(creator.address(), {
+      function: `${creator.address()}::ambassador::burn`,
+      type_arguments: [],
+      arguments: [token.hex()],
+    });
+
+    const bcsTxn = await provider.signTransaction(creator, rawTxn);
+    const pendingTxn = await provider.submitTransaction(bcsTxn);
+
+    return pendingTxn.hash;
+  }
+
+  async mintAmbassadorToken(
+    creator: AptosAccount,
+    description: string,
+    name: string,
+    uri: string,
+    soul_bound_to: HexString,
+  ): Promise {
+    const rawTxn = await provider.generateTransaction(creator.address(), {
+      function: `${creator.address()}::ambassador::mint_ambassador_token`,
+      type_arguments: [],
+      arguments: [description, name, uri, soul_bound_to.hex()],
+    });
+
+    const bcsTxn = await provider.signTransaction(creator, rawTxn);
+    const pendingTxn = await provider.submitTransaction(bcsTxn);
+
+    return pendingTxn.hash;
+  }
+
+  async ambassadorLevel(creator_addr: HexString, token_addr: HexString): Promise {
+    const payload: Types.ViewRequest = {
+      function: `${creator_addr.hex()}::ambassador::ambassador_level`,
+      type_arguments: [],
+      arguments: [token_addr.hex()],
+    };
+
+    const result = await provider.view(payload);
+    return BigInt(result[0] as any);
+  }
+}
+
+/** run our demo! */
+async function main(): Promise {
+  const client = new AmbassadorClient();
+
+  const admin = new AptosAccount();
+  const user = new AptosAccount();
+
+  await faucetClient.fundAccount(admin.address(), 100_000_000);
+  await faucetClient.fundAccount(user.address(), 100_000_000);
+
+  console.log(
+    "\nCompile and publish the Ambassador module (`aptos-core/aptos-move/move-examples/token_objects/ambassador`) using the following profile, and press enter:",
+  );
+  console.log(`  ambassador_admin:`);
+  console.log(`    private_key: "${admin.toPrivateKeyObject().privateKeyHex}"`);
+  console.log(`    public_key: "${admin.pubKey()}"`);
+  console.log(`    account: ${admin.address()}`);
+  console.log(`    rest_url: "https://fullnode.devnet.aptoslabs.com"`);
+  console.log(`    faucet_url: "https://faucet.devnet.aptoslabs.com"`);
+
+  await waitForEnter();
+
+  const adminAddr = admin.address();
+  const userAddr = user.address();
+  const tokenName = "Aptos Ambassador #1";
+
+  console.log("\n=== Addresses ===");
+  console.log(`Admin: ${adminAddr} `);
+  console.log(`User: ${userAddr} `);
+
+  // Mint Ambassador Token
+  let txnHash = await client.mintAmbassadorToken(
+    admin,
+    "Aptos Ambassador Token",
+    tokenName,
+    "https://raw.githubusercontent.com/aptos-labs/aptos-core/main/ecosystem/typescript/sdk/examples/typescript/metadata/ambassador/",
+    userAddr,
+  );
+  await provider.waitForTransaction(txnHash, { checkSuccess: true });
+  console.log("\n=== Ambassador Token Minted ===");
+  console.log(`Txn: https://explorer.aptoslabs.com/txn/${txnHash}?network=devnet`);
+  // Get the address of the minted token
+  const tokenAddr = await getTokenAddr(userAddr, tokenName);
+  console.log(`The address of the minted token: ${tokenAddr}`);
+  console.log(`The level of the token: ${await client.ambassadorLevel(adminAddr, tokenAddr)}`);
+  await waitForEnter();
+
+  // Set Ambassador Level to 15
+  txnHash = await client.setAmbassadorLevel(admin, tokenAddr, 15);
+  await provider.waitForTransaction(txnHash, { checkSuccess: true });
+  console.log("\n=== Level set to 15 ===");
+  console.log(`Txn: https://explorer.aptoslabs.com/txn/${txnHash}?network=devnet`);
+  console.log(`The level of the token: ${await client.ambassadorLevel(adminAddr, tokenAddr)}`);
+  await waitForEnter();
+
+  // Set Ambassador Level to 25
+  txnHash = await client.setAmbassadorLevel(admin, tokenAddr, 25);
+  await provider.waitForTransaction(txnHash, { checkSuccess: true });
+  console.log("\n=== Level set to 25 ===");
+  console.log(`Txn: https://explorer.aptoslabs.com/txn/${txnHash}?network=devnet`);
+  console.log(`The level of the token: ${await client.ambassadorLevel(adminAddr, tokenAddr)}`);
+  await waitForEnter();
+
+  // Burn the token
+  txnHash = await client.burn(admin, tokenAddr);
+  await provider.waitForTransaction(txnHash, { checkSuccess: true });
+  console.log("\n=== Token burned ===");
+  console.log(`Txn: https://explorer.aptoslabs.com/txn/${txnHash}?network=devnet`);
+  await waitForEnter();
+}
+
+main().then(() => {
+  console.log("Done!");
+  process.exit(0);
+});
diff --git a/ecosystem/typescript/sdk/examples/typescript/metadata/ambassador/Bronze b/ecosystem/typescript/sdk/examples/typescript/metadata/ambassador/Bronze
new file mode 100644
index 0000000000000..266637b8f7898
--- /dev/null
+++ b/ecosystem/typescript/sdk/examples/typescript/metadata/ambassador/Bronze
@@ -0,0 +1,6 @@
+{
+  "name": "Ambassador #1",
+  "description": "Aptos Ambassador Token",
+  "image": "https://raw.githubusercontent.com/aptos-labs/aptos-core/main/aptos-move/move-examples/token_objects/ambassador/metadata/Bronze.png",
+  "attributes": []
+}
\ No newline at end of file
diff --git a/ecosystem/typescript/sdk/examples/typescript/metadata/ambassador/Bronze.png b/ecosystem/typescript/sdk/examples/typescript/metadata/ambassador/Bronze.png
new file mode 100644
index 0000000000000000000000000000000000000000..44e6522d2747c62361f708f458f814f8aa984855
GIT binary patch
literal 740712
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
z
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
z
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
Ra=
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	f^HqS0P>QcGSAtx^B#z
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%0DX>%Exz-d`5oro;7T?
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
o$(mKZ?W$pG6r9h7x
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
1;rhvmCBX45lP_ugbk
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
oYnQXTDdeaW3cOn)!~68
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
l7-6Y>!=k=r=scx%0^@1y;1L1S9fq&%a%>3*b0
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

literal 0
HcmV?d00001

diff --git a/ecosystem/typescript/sdk/examples/typescript/metadata/ambassador/Gold b/ecosystem/typescript/sdk/examples/typescript/metadata/ambassador/Gold
new file mode 100644
index 0000000000000..7d1fc928aa1ad
--- /dev/null
+++ b/ecosystem/typescript/sdk/examples/typescript/metadata/ambassador/Gold
@@ -0,0 +1,6 @@
+{
+  "name": "Ambassador #1",
+  "description": "Aptos Ambassador Token",
+  "image": "https://raw.githubusercontent.com/aptos-labs/aptos-core/main/aptos-move/move-examples/token_objects/ambassador/metadata/Gold.png",
+  "attributes": []
+}
\ No newline at end of file
diff --git a/ecosystem/typescript/sdk/examples/typescript/metadata/ambassador/Gold.png b/ecosystem/typescript/sdk/examples/typescript/metadata/ambassador/Gold.png
new file mode 100644
index 0000000000000000000000000000000000000000..7b50a69c47254676a773a3b91d2c03dc4b725091
GIT binary patch
literal 1149061
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
    i`|>$4
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
    vgpLb&R{t>ZdfgVCP
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

 
@@ -282,13 +279,10 @@ Batch version of transfer_coins.
         error::invalid_argument(EMISMATCHING_RECIPIENTS_AND_AMOUNTS_LENGTH),
     );
 
-    let i = 0;
-    while (i < recipients_len) {
-        let to = *vector::borrow(&recipients, i);
+    vector::enumerate_ref(&recipients, |i, to| {
         let amount = *vector::borrow(&amounts, i);
-        transfer_coins<CoinType>(from, to, amount);
-        i = i + 1;
-    };
+        transfer_coins<CoinType>(from, *to, amount);
+    });
 }
diff --git a/aptos-move/framework/aptos-framework/doc/aptos_coin.md b/aptos-move/framework/aptos-framework/doc/aptos_coin.md index 3fc8267a11470..f6834ab4e1830 100644 --- a/aptos-move/framework/aptos-framework/doc/aptos_coin.md +++ b/aptos-move/framework/aptos-framework/doc/aptos_coin.md @@ -378,12 +378,10 @@ Create delegated token for the address so the account could claim MintCapability 
public entry fun delegate_mint_capability(account: signer, to: address) acquires Delegations {
     system_addresses::assert_core_resource(&account);
     let delegations = &mut borrow_global_mut<Delegations>(@core_resources).inner;
-    let i = 0;
-    while (i < vector::length(delegations)) {
-        let element = vector::borrow(delegations, i);
+    vector::for_each_ref(delegations, |element| {
+        let element: &DelegatedMintCapability = element;
         assert!(element.to != to, error::invalid_argument(EALREADY_DELEGATED));
-        i = i + 1;
-    };
+    });
     vector::push_back(delegations, DelegatedMintCapability { to });
 }
diff --git a/aptos-move/framework/aptos-framework/doc/code.md b/aptos-move/framework/aptos-framework/doc/code.md index 35eaac3bfc69b..3e2f788a8ae8d 100644 --- a/aptos-move/framework/aptos-framework/doc/code.md +++ b/aptos-move/framework/aptos-framework/doc/code.md @@ -554,10 +554,9 @@ package. let packages = &mut borrow_global_mut<PackageRegistry>(addr).packages; let len = vector::length(packages); let index = len; - let i = 0; let upgrade_number = 0; - while (i < len) { - let old = vector::borrow(packages, i); + vector::enumerate_ref(packages, |i, old| { + let old: &PackageMetadata = old; if (old.name == pack.name) { upgrade_number = old.upgrade_number + 1; check_upgradability(old, &pack, &module_names); @@ -565,8 +564,7 @@ package. } else { check_coexistence(old, &module_names) }; - i = i + 1; - }; + }); // Assign the upgrade counter. pack.upgrade_number = upgrade_number; @@ -643,14 +641,13 @@ Checks whether the given package is upgradable, and returns true if a compatibil assert!(can_change_upgrade_policy_to(old_pack.upgrade_policy, new_pack.upgrade_policy), error::invalid_argument(EUPGRADE_WEAKER_POLICY)); let old_modules = get_module_names(old_pack); - let i = 0; - while (i < vector::length(&old_modules)) { + + vector::for_each_ref(&old_modules, |old_module| { assert!( - vector::contains(new_modules, vector::borrow(&old_modules, i)), + vector::contains(new_modules, old_module), EMODULE_MISSING ); - i = i + 1; - } + }); } @@ -676,17 +673,15 @@ Checks whether a new package with given names can co-exist with old package. 
fun check_coexistence(old_pack: &PackageMetadata, new_modules: &vector<String>) {
     // The modules introduced by each package must not overlap with `names`.
-    let i = 0;
-    while (i < vector::length(&old_pack.modules)) {
-        let old_mod = vector::borrow(&old_pack.modules, i);
+    vector::for_each_ref(&old_pack.modules, |old_mod| {
+        let old_mod: &ModuleMetadata = old_mod;
         let j = 0;
         while (j < vector::length(new_modules)) {
             let name = vector::borrow(new_modules, j);
             assert!(&old_mod.name != name, error::already_exists(EMODULE_NAME_CLASH));
             j = j + 1;
         };
-        i = i + 1;
-    }
+    });
 }
@@ -716,54 +711,47 @@ is passed on to the native layer to verify that bytecode dependencies are actual acquires PackageRegistry { let allowed_module_deps = vector::empty(); let deps = &pack.deps; - let i = 0; - let n = vector::length(deps); - while (i < n) { - let dep = vector::borrow(deps, i); + vector::for_each_ref(deps, |dep| { + let dep: &PackageDep = dep; assert!(exists<PackageRegistry>(dep.account), error::not_found(EPACKAGE_DEP_MISSING)); if (is_policy_exempted_address(dep.account)) { // Allow all modules from this address, by using "" as a wildcard in the AllowedDep - let account = dep.account; + let account: address = dep.account; let module_name = string::utf8(b""); vector::push_back(&mut allowed_module_deps, AllowedDep { account, module_name }); - i = i + 1; - continue - }; - let registry = borrow_global<PackageRegistry>(dep.account); - let j = 0; - let m = vector::length(®istry.packages); - let found = false; - while (j < m) { - let dep_pack = vector::borrow(®istry.packages, j); - if (dep_pack.name == dep.package_name) { - found = true; - // Check policy - assert!( - dep_pack.upgrade_policy.policy >= pack.upgrade_policy.policy, - error::invalid_argument(EDEP_WEAKER_POLICY) - ); - if (dep_pack.upgrade_policy == upgrade_policy_arbitrary()) { + } else { + let registry = borrow_global<PackageRegistry>(dep.account); + let found = vector::any(®istry.packages, |dep_pack| { + let dep_pack: &PackageMetadata = dep_pack; + if (dep_pack.name == dep.package_name) { + // Check policy assert!( - dep.account == publish_address, - error::invalid_argument(EDEP_ARBITRARY_NOT_SAME_ADDRESS) - ) - }; - // Add allowed deps - let k = 0; - let r = vector::length(&dep_pack.modules); - while (k < r) { + dep_pack.upgrade_policy.policy >= pack.upgrade_policy.policy, + error::invalid_argument(EDEP_WEAKER_POLICY) + ); + if (dep_pack.upgrade_policy == upgrade_policy_arbitrary()) { + assert!( + dep.account == publish_address, + error::invalid_argument(EDEP_ARBITRARY_NOT_SAME_ADDRESS) + ) + }; + // Add allowed deps let account = dep.account; - let module_name = vector::borrow(&dep_pack.modules, k).name; - vector::push_back(&mut allowed_module_deps, AllowedDep { account, module_name }); - k = k + 1; - }; - break - }; - j = j + 1; + let k = 0; + let r = vector::length(&dep_pack.modules); + while (k < r) { + let module_name = vector::borrow(&dep_pack.modules, k).name; + vector::push_back(&mut allowed_module_deps, AllowedDep { account, module_name }); + k = k + 1; + }; + true + } else { + false + } + }); + assert!(found, error::not_found(EPACKAGE_DEP_MISSING)); }; - assert!(found, error::not_found(EPACKAGE_DEP_MISSING)); - i = i + 1; - }; + }); allowed_module_deps } @@ -818,11 +806,10 @@ Get the names of the modules in a package. 
fun get_module_names(pack: &PackageMetadata): vector<String> {
     let module_names = vector::empty();
-    let i = 0;
-    while (i < vector::length(&pack.modules)) {
-        vector::push_back(&mut module_names, vector::borrow(&pack.modules, i).name);
-        i = i + 1
-    };
+    vector::for_each_ref(&pack.modules, |pack_module| {
+        let pack_module: &ModuleMetadata = pack_module;
+        vector::push_back(&mut module_names, pack_module.name);
+    });
     module_names
 }
diff --git a/aptos-move/framework/aptos-framework/doc/gas_schedule.md b/aptos-move/framework/aptos-framework/doc/gas_schedule.md index 40d4c1bf1873b..4880dc4be03e6 100644 --- a/aptos-move/framework/aptos-framework/doc/gas_schedule.md +++ b/aptos-move/framework/aptos-framework/doc/gas_schedule.md @@ -318,7 +318,7 @@ This can be called by on-chain governance to update the gas schedule. -
pragma timeout = 100;
+
pragma verify_duration_estimate = 200;
 requires exists<stake::ValidatorFees>(@aptos_framework);
 requires exists<CoinInfo<AptosCoin>>(@aptos_framework);
 include system_addresses::AbortsIfNotAptosFramework{ account: aptos_framework };
diff --git a/aptos-move/framework/aptos-framework/doc/genesis.md b/aptos-move/framework/aptos-framework/doc/genesis.md
index 75043570e080b..90607e0d4356b 100644
--- a/aptos-move/framework/aptos-framework/doc/genesis.md
+++ b/aptos-move/framework/aptos-framework/doc/genesis.md
@@ -444,12 +444,9 @@ Only called for testnets and e2e tests.
 
 
 
fun create_accounts(aptos_framework: &signer, accounts: vector<AccountMap>) {
-    let i = 0;
-    let num_accounts = vector::length(&accounts);
     let unique_accounts = vector::empty();
-
-    while (i < num_accounts) {
-        let account_map = vector::borrow(&accounts, i);
+    vector::for_each_ref(&accounts, |account_map| {
+        let account_map: &AccountMap = account_map;
         assert!(
             !vector::contains(&unique_accounts, &account_map.account_address),
             error::already_exists(EDUPLICATE_ACCOUNT),
@@ -461,9 +458,7 @@ Only called for testnets and e2e tests.
             account_map.account_address,
             account_map.balance,
         );
-
-        i = i + 1;
-    };
+    });
 }
 

 
@@ -524,13 +519,11 @@ If it exists, it just returns the signer.
     employee_vesting_period_duration: u64,
     employees: vector<EmployeeAccountMap>,
 ) {
-    let i = 0;
-    let num_employee_groups = vector::length(&employees);
     let unique_accounts = vector::empty();
 
-    while (i < num_employee_groups) {
+    vector::for_each_ref(&employees, |employee_group| {
         let j = 0;
-        let employee_group = vector::borrow(&employees, i);
+        let employee_group: &EmployeeAccountMap = employee_group;
         let num_employees_in_group = vector::length(&employee_group.accounts);
 
         let buy_ins = simple_map::create();
@@ -604,9 +597,7 @@ If it exists, it just returns the signer.
         if (employee_group.validator.join_during_genesis) {
             initialize_validator(pool_address, validator);
         };
-
-        i = i + 1;
-    }
+    });
 }
 

 
@@ -634,14 +625,10 @@ If it exists, it just returns the signer.
     use_staking_contract: bool,
     validators: vector<ValidatorConfigurationWithCommission>,
 ) {
-    let i = 0;
-    let num_validators = vector::length(&validators);
-    while (i < num_validators) {
-        let validator = vector::borrow(&validators, i);
+    vector::for_each_ref(&validators, |validator| {
+        let validator: &ValidatorConfigurationWithCommission = validator;
         create_initialize_validator(aptos_framework, validator, use_staking_contract);
-
-        i = i + 1;
-    };
+    });
 
     // Destroy the aptos framework account's ability to mint coins now that we're done with setting up the initial
     // validators.
@@ -681,21 +668,15 @@ encoded in a single BCS byte array.
 
 
 
fun create_initialize_validators(aptos_framework: &signer, validators: vector<ValidatorConfiguration>) {
-    let i = 0;
-    let num_validators = vector::length(&validators);
-
     let validators_with_commission = vector::empty();
-
-    while (i < num_validators) {
+    vector::for_each_reverse(validators, |validator| {
         let validator_with_commission = ValidatorConfigurationWithCommission {
-            validator_config: vector::pop_back(&mut validators),
+            validator_config: validator,
             commission_percentage: 0,
             join_during_genesis: true,
         };
         vector::push_back(&mut validators_with_commission, validator_with_commission);
-
-        i = i + 1;
-    };
+    });
 
     create_initialize_validators_with_commission(aptos_framework, false, validators_with_commission);
 }
diff --git a/aptos-move/framework/aptos-framework/doc/stake.md b/aptos-move/framework/aptos-framework/doc/stake.md
index 2e32dfd15cda9..de7e8ad6ec8ef 100644
--- a/aptos-move/framework/aptos-framework/doc/stake.md
+++ b/aptos-move/framework/aptos-framework/doc/stake.md
@@ -2960,23 +2960,17 @@ power.
     let validator_perf = borrow_global_mut<ValidatorPerformance>(@aptos_framework);
 
     // Process pending stake and distribute transaction fees and rewards for each currently active validator.
-    let i = 0;
-    let len = vector::length(&validator_set.active_validators);
-    while (i < len) {
-        let validator = vector::borrow(&validator_set.active_validators, i);
+    vector::for_each_ref(&validator_set.active_validators, |validator| {
+        let validator: &ValidatorInfo = validator;
         update_stake_pool(validator_perf, validator.addr, &config);
-        i = i + 1;
-    };
+    });
 
     // Process pending stake and distribute transaction fees and rewards for each currently pending_inactive validator
     // (requested to leave but not removed yet).
-    let i = 0;
-    let len = vector::length(&validator_set.pending_inactive);
-    while (i < len) {
-        let validator = vector::borrow(&validator_set.pending_inactive, i);
+    vector::for_each_ref(&validator_set.pending_inactive, |validator| {
+        let validator: &ValidatorInfo = validator;
         update_stake_pool(validator_perf, validator.addr, &config);
-        i = i + 1;
-    };
+    });
 
     // Activate currently pending_active validators.
     append(&mut validator_set.active_validators, &mut validator_set.pending_active);
diff --git a/aptos-move/framework/aptos-framework/doc/staking_contract.md b/aptos-move/framework/aptos-framework/doc/staking_contract.md
index 81728ee607b9e..3c64f4bf0fa1a 100644
--- a/aptos-move/framework/aptos-framework/doc/staking_contract.md
+++ b/aptos-move/framework/aptos-framework/doc/staking_contract.md
@@ -1866,10 +1866,8 @@ Calculate accumulated rewards and commissions since last update.
     // Charge all stakeholders (except for the operator themselves) commission on any rewards earnt relatively to the
     // previous value of the distribution pool.
     let shareholders = &pool_u64::shareholders(distribution_pool);
-    let len = vector::length(shareholders);
-    let i = 0;
-    while (i < len) {
-        let shareholder = *vector::borrow(shareholders, i);
+    vector::for_each_ref(shareholders, |shareholder| {
+        let shareholder: address = *shareholder;
         if (shareholder != operator) {
             let shares = pool_u64::shares(distribution_pool, shareholder);
             let previous_worth = pool_u64::balance(distribution_pool, shareholder);
@@ -1882,9 +1880,7 @@ Calculate accumulated rewards and commissions since last update.
                 distribution_pool, unpaid_commission, updated_total_coins);
             pool_u64::transfer_shares(distribution_pool, shareholder, operator, shares_to_transfer);
         };
-
-        i = i + 1;
-    };
+    });
 
     pool_u64::update_total_coins(distribution_pool, updated_total_coins);
 }
diff --git a/aptos-move/framework/aptos-framework/doc/staking_proxy.md b/aptos-move/framework/aptos-framework/doc/staking_proxy.md
index 60cdf4579c99e..e4e9c7d5e4e38 100644
--- a/aptos-move/framework/aptos-framework/doc/staking_proxy.md
+++ b/aptos-move/framework/aptos-framework/doc/staking_proxy.md
@@ -102,16 +102,13 @@
 
public entry fun set_vesting_contract_operator(owner: &signer, old_operator: address, new_operator: address) {
     let owner_address = signer::address_of(owner);
     let vesting_contracts = &vesting::vesting_contracts(owner_address);
-    let i = 0;
-    let len = vector::length(vesting_contracts);
-    while (i < len) {
-        let vesting_contract = *vector::borrow(vesting_contracts, i);
+    vector::for_each_ref(vesting_contracts, |vesting_contract| {
+        let vesting_contract = *vesting_contract;
         if (vesting::operator(vesting_contract) == old_operator) {
             let current_commission_percentage = vesting::operator_commission_percentage(vesting_contract);
             vesting::update_operator(owner, vesting_contract, new_operator, current_commission_percentage);
         };
-        i = i + 1;
-    }
+    });
 }
 

 
@@ -192,15 +189,12 @@
 
public entry fun set_vesting_contract_voter(owner: &signer, operator: address, new_voter: address) {
     let owner_address = signer::address_of(owner);
     let vesting_contracts = &vesting::vesting_contracts(owner_address);
-    let i = 0;
-    let len = vector::length(vesting_contracts);
-    while (i < len) {
-        let vesting_contract = *vector::borrow(vesting_contracts, i);
+    vector::for_each_ref(vesting_contracts, |vesting_contract| {
+        let vesting_contract = *vesting_contract;
         if (vesting::operator(vesting_contract) == operator) {
             vesting::update_voter(owner, vesting_contract, new_voter);
         };
-        i = i + 1;
-    }
+    });
 }
 

 
@@ -363,6 +357,22 @@ One of them are not exists
 
 
 
+
+
+
+
+
schema SetStakePoolOperator {
+    owner: &signer;
+    new_operator: address;
+    let owner_address = signer::address_of(owner);
+    let ownership_cap = borrow_global<stake::OwnerCapability>(owner_address);
+    let pool_address = ownership_cap.pool_address;
+    aborts_if stake::stake_pool_exists(owner_address) && !(exists<stake::OwnerCapability>(owner_address) && stake::stake_pool_exists(pool_address));
+}
+

+
+
+
 
 
 ### Function `set_vesting_contract_voter`
diff --git a/aptos-move/framework/aptos-framework/doc/vesting.md b/aptos-move/framework/aptos-framework/doc/vesting.md
index 7485b72557c31..50f672f7290ea 100644
--- a/aptos-move/framework/aptos-framework/doc/vesting.md
+++ b/aptos-move/framework/aptos-framework/doc/vesting.md
@@ -1557,18 +1557,17 @@ This returns 0x0 if no shareholder is found for the given beneficiary / the addr
         return shareholder_or_beneficiary
     };
     let vesting_contract = borrow_global<VestingContract>(vesting_contract_address);
-    let i = 0;
-    let len = vector::length(shareholders);
-    while (i < len) {
-        let shareholder = *vector::borrow(shareholders, i);
-        // This will still return the shareholder if shareholder == beneficiary.
-        if (shareholder_or_beneficiary == get_beneficiary(vesting_contract, shareholder)) {
-            return shareholder
-        };
-        i = i + 1;
-    };
+    let result = @0x0;
+    vector::any(shareholders, |shareholder| {
+        if (shareholder_or_beneficiary == get_beneficiary(vesting_contract, *shareholder)) {
+            result = *shareholder;
+            true
+        } else {
+            false
+        }
+    });
 
-    @0x0
+    result
 }
 

 
@@ -1660,22 +1659,18 @@ Create a vesting contract with a given configurations.
     let grant = coin::zero<AptosCoin>();
     let grant_amount = 0;
     let grant_pool = pool_u64::create(MAXIMUM_SHAREHOLDERS);
-    let len = vector::length(shareholders);
-    let i = 0;
-    while (i < len) {
-        let shareholder = *vector::borrow(shareholders, i);
+    vector::for_each_ref(shareholders, |shareholder| {
+        let shareholder: address = *shareholder;
         let (_, buy_in) = simple_map::remove(&mut buy_ins, &shareholder);
         let buy_in_amount = coin::value(&buy_in);
         coin::merge(&mut grant, buy_in);
         pool_u64::buy_in(
             &mut grant_pool,
-            *vector::borrow(shareholders, i),
+            shareholder,
             buy_in_amount,
         );
         grant_amount = grant_amount + buy_in_amount;
-
-        i = i + 1;
-    };
+    });
     assert!(grant_amount > 0, error::invalid_argument(EZERO_GRANT));
 
     // If this is the first time this admin account has created a vesting contract, initialize the admin store.
@@ -1789,12 +1784,10 @@ Call unlock_rewards for many vesting contracts.
 
     assert!(len != 0, error::invalid_argument(EVEC_EMPTY_FOR_MANY_FUNCTION));
 
-    let i = 0;
-    while (i < len) {
-        let contract_address = *vector::borrow(&contract_addresses, i);
+    vector::for_each_ref(&contract_addresses, |contract_address| {
+        let contract_address: address = *contract_address;
         unlock_rewards(contract_address);
-        i = i + 1;
-    };
+    });
 }
@@ -1896,12 +1889,10 @@ Call vest for many vesting contracts. assert!(len != 0, error::invalid_argument(EVEC_EMPTY_FOR_MANY_FUNCTION)); - let i = 0; - while (i < len) { - let contract_address = *vector::borrow(&contract_addresses, i); + vector::for_each_ref(&contract_addresses, |contract_address| { + let contract_address = *contract_address; vest(contract_address); - i = i + 1; - }; + }); } @@ -1939,18 +1930,14 @@ Distribute any withdrawable stake from the stake pool. // Distribute coins to all shareholders in the vesting contract. let grant_pool = &vesting_contract.grant_pool; let shareholders = &pool_u64::shareholders(grant_pool); - let len = vector::length(shareholders); - let i = 0; - while (i < len) { - let shareholder = *vector::borrow(shareholders, i); + vector::for_each_ref(shareholders, |shareholder| { + let shareholder = *shareholder; let shares = pool_u64::shares(grant_pool, shareholder); let amount = pool_u64::shares_to_amount_with_total_coins(grant_pool, shares, total_distribution_amount); let share_of_coins = coin::extract(&mut coins, amount); let recipient_address = get_beneficiary(vesting_contract, shareholder); aptos_account::deposit_coins(recipient_address, share_of_coins); - - i = i + 1; - }; + }); // Send any remaining "dust" (leftover due to rounding error) to the withdrawal address. if (coin::value(&coins) > 0) { @@ -1995,12 +1982,10 @@ Call distribute for many vesting contracts. assert!(len != 0, error::invalid_argument(EVEC_EMPTY_FOR_MANY_FUNCTION)); - let i = 0; - while (i < len) { - let contract_address = *vector::borrow(&contract_addresses, i); + vector::for_each_ref(&contract_addresses, |contract_address| { + let contract_address = *contract_address; distribute(contract_address); - i = i + 1; - }; + }); } diff --git a/aptos-move/framework/aptos-framework/sources/aptos_account.move b/aptos-move/framework/aptos-framework/sources/aptos_account.move index e6b12f90aac24..ff9074ebc8a2f 100644 --- a/aptos-move/framework/aptos-framework/sources/aptos_account.move +++ b/aptos-move/framework/aptos-framework/sources/aptos_account.move @@ -52,13 +52,10 @@ module aptos_framework::aptos_account { error::invalid_argument(EMISMATCHING_RECIPIENTS_AND_AMOUNTS_LENGTH), ); - let i = 0; - while (i < recipients_len) { - let to = *vector::borrow(&recipients, i); + vector::enumerate_ref(&recipients, |i, to| { let amount = *vector::borrow(&amounts, i); - transfer(source, to, amount); - i = i + 1; - }; + transfer(source, *to, amount); + }); } /// Convenient function to transfer APT to a recipient account that might not exist. @@ -84,13 +81,10 @@ module aptos_framework::aptos_account { error::invalid_argument(EMISMATCHING_RECIPIENTS_AND_AMOUNTS_LENGTH), ); - let i = 0; - while (i < recipients_len) { - let to = *vector::borrow(&recipients, i); + vector::enumerate_ref(&recipients, |i, to| { let amount = *vector::borrow(&amounts, i); - transfer_coins(from, to, amount); - i = i + 1; - }; + transfer_coins(from, *to, amount); + }); } /// Convenient function to transfer a custom CoinType to a recipient account that might not exist. diff --git a/aptos-move/framework/aptos-framework/sources/aptos_coin.move b/aptos-move/framework/aptos-framework/sources/aptos_coin.move index 2eb0f870aebea..c3e656e9c8ca4 100644 --- a/aptos-move/framework/aptos-framework/sources/aptos_coin.move +++ b/aptos-move/framework/aptos-framework/sources/aptos_coin.move @@ -112,12 +112,10 @@ module aptos_framework::aptos_coin { public entry fun delegate_mint_capability(account: signer, to: address) acquires Delegations { system_addresses::assert_core_resource(&account); let delegations = &mut borrow_global_mut(@core_resources).inner; - let i = 0; - while (i < vector::length(delegations)) { - let element = vector::borrow(delegations, i); + vector::for_each_ref(delegations, |element| { + let element: &DelegatedMintCapability = element; assert!(element.to != to, error::invalid_argument(EALREADY_DELEGATED)); - i = i + 1; - }; + }); vector::push_back(delegations, DelegatedMintCapability { to }); } diff --git a/aptos-move/framework/aptos-framework/sources/code.move b/aptos-move/framework/aptos-framework/sources/code.move index 1e6c8a295aaf9..a2ae9c40af2ac 100644 --- a/aptos-move/framework/aptos-framework/sources/code.move +++ b/aptos-move/framework/aptos-framework/sources/code.move @@ -149,10 +149,9 @@ module aptos_framework::code { let packages = &mut borrow_global_mut(addr).packages; let len = vector::length(packages); let index = len; - let i = 0; let upgrade_number = 0; - while (i < len) { - let old = vector::borrow(packages, i); + vector::enumerate_ref(packages, |i, old| { + let old: &PackageMetadata = old; if (old.name == pack.name) { upgrade_number = old.upgrade_number + 1; check_upgradability(old, &pack, &module_names); @@ -160,8 +159,7 @@ module aptos_framework::code { } else { check_coexistence(old, &module_names) }; - i = i + 1; - }; + }); // Assign the upgrade counter. pack.upgrade_number = upgrade_number; @@ -201,30 +199,27 @@ module aptos_framework::code { assert!(can_change_upgrade_policy_to(old_pack.upgrade_policy, new_pack.upgrade_policy), error::invalid_argument(EUPGRADE_WEAKER_POLICY)); let old_modules = get_module_names(old_pack); - let i = 0; - while (i < vector::length(&old_modules)) { + + vector::for_each_ref(&old_modules, |old_module| { assert!( - vector::contains(new_modules, vector::borrow(&old_modules, i)), + vector::contains(new_modules, old_module), EMODULE_MISSING ); - i = i + 1; - } + }); } /// Checks whether a new package with given names can co-exist with old package. fun check_coexistence(old_pack: &PackageMetadata, new_modules: &vector) { // The modules introduced by each package must not overlap with `names`. - let i = 0; - while (i < vector::length(&old_pack.modules)) { - let old_mod = vector::borrow(&old_pack.modules, i); + vector::for_each_ref(&old_pack.modules, |old_mod| { + let old_mod: &ModuleMetadata = old_mod; let j = 0; while (j < vector::length(new_modules)) { let name = vector::borrow(new_modules, j); assert!(&old_mod.name != name, error::already_exists(EMODULE_NAME_CLASH)); j = j + 1; }; - i = i + 1; - } + }); } /// Check that the upgrade policies of all packages are equal or higher quality than this package. Also @@ -234,54 +229,47 @@ module aptos_framework::code { acquires PackageRegistry { let allowed_module_deps = vector::empty(); let deps = &pack.deps; - let i = 0; - let n = vector::length(deps); - while (i < n) { - let dep = vector::borrow(deps, i); + vector::for_each_ref(deps, |dep| { + let dep: &PackageDep = dep; assert!(exists(dep.account), error::not_found(EPACKAGE_DEP_MISSING)); if (is_policy_exempted_address(dep.account)) { // Allow all modules from this address, by using "" as a wildcard in the AllowedDep - let account = dep.account; + let account: address = dep.account; let module_name = string::utf8(b""); vector::push_back(&mut allowed_module_deps, AllowedDep { account, module_name }); - i = i + 1; - continue - }; - let registry = borrow_global(dep.account); - let j = 0; - let m = vector::length(®istry.packages); - let found = false; - while (j < m) { - let dep_pack = vector::borrow(®istry.packages, j); - if (dep_pack.name == dep.package_name) { - found = true; - // Check policy - assert!( - dep_pack.upgrade_policy.policy >= pack.upgrade_policy.policy, - error::invalid_argument(EDEP_WEAKER_POLICY) - ); - if (dep_pack.upgrade_policy == upgrade_policy_arbitrary()) { + } else { + let registry = borrow_global(dep.account); + let found = vector::any(®istry.packages, |dep_pack| { + let dep_pack: &PackageMetadata = dep_pack; + if (dep_pack.name == dep.package_name) { + // Check policy assert!( - dep.account == publish_address, - error::invalid_argument(EDEP_ARBITRARY_NOT_SAME_ADDRESS) - ) - }; - // Add allowed deps - let k = 0; - let r = vector::length(&dep_pack.modules); - while (k < r) { + dep_pack.upgrade_policy.policy >= pack.upgrade_policy.policy, + error::invalid_argument(EDEP_WEAKER_POLICY) + ); + if (dep_pack.upgrade_policy == upgrade_policy_arbitrary()) { + assert!( + dep.account == publish_address, + error::invalid_argument(EDEP_ARBITRARY_NOT_SAME_ADDRESS) + ) + }; + // Add allowed deps let account = dep.account; - let module_name = vector::borrow(&dep_pack.modules, k).name; - vector::push_back(&mut allowed_module_deps, AllowedDep { account, module_name }); - k = k + 1; - }; - break - }; - j = j + 1; + let k = 0; + let r = vector::length(&dep_pack.modules); + while (k < r) { + let module_name = vector::borrow(&dep_pack.modules, k).name; + vector::push_back(&mut allowed_module_deps, AllowedDep { account, module_name }); + k = k + 1; + }; + true + } else { + false + } + }); + assert!(found, error::not_found(EPACKAGE_DEP_MISSING)); }; - assert!(found, error::not_found(EPACKAGE_DEP_MISSING)); - i = i + 1; - }; + }); allowed_module_deps } @@ -296,11 +284,10 @@ module aptos_framework::code { /// Get the names of the modules in a package. fun get_module_names(pack: &PackageMetadata): vector { let module_names = vector::empty(); - let i = 0; - while (i < vector::length(&pack.modules)) { - vector::push_back(&mut module_names, vector::borrow(&pack.modules, i).name); - i = i + 1 - }; + vector::for_each_ref(&pack.modules, |pack_module| { + let pack_module: &ModuleMetadata = pack_module; + vector::push_back(&mut module_names, pack_module.name); + }); module_names } diff --git a/aptos-move/framework/aptos-framework/sources/configs/gas_schedule.spec.move b/aptos-move/framework/aptos-framework/sources/configs/gas_schedule.spec.move index 0ba4a949e4174..ded0038308818 100644 --- a/aptos-move/framework/aptos-framework/sources/configs/gas_schedule.spec.move +++ b/aptos-move/framework/aptos-framework/sources/configs/gas_schedule.spec.move @@ -42,7 +42,7 @@ spec aptos_framework::gas_schedule { use aptos_framework::transaction_fee; use aptos_framework::staking_config; - pragma timeout = 100; + pragma verify_duration_estimate = 200; requires exists(@aptos_framework); requires exists>(@aptos_framework); diff --git a/aptos-move/framework/aptos-framework/sources/genesis.move b/aptos-move/framework/aptos-framework/sources/genesis.move index 20cbe67e0fae9..2d089cb9346df 100644 --- a/aptos-move/framework/aptos-framework/sources/genesis.move +++ b/aptos-move/framework/aptos-framework/sources/genesis.move @@ -158,12 +158,9 @@ module aptos_framework::genesis { } fun create_accounts(aptos_framework: &signer, accounts: vector) { - let i = 0; - let num_accounts = vector::length(&accounts); let unique_accounts = vector::empty(); - - while (i < num_accounts) { - let account_map = vector::borrow(&accounts, i); + vector::for_each_ref(&accounts, |account_map| { + let account_map: &AccountMap = account_map; assert!( !vector::contains(&unique_accounts, &account_map.account_address), error::already_exists(EDUPLICATE_ACCOUNT), @@ -175,9 +172,7 @@ module aptos_framework::genesis { account_map.account_address, account_map.balance, ); - - i = i + 1; - }; + }); } /// This creates an funds an account if it doesn't exist. @@ -198,13 +193,11 @@ module aptos_framework::genesis { employee_vesting_period_duration: u64, employees: vector, ) { - let i = 0; - let num_employee_groups = vector::length(&employees); let unique_accounts = vector::empty(); - while (i < num_employee_groups) { + vector::for_each_ref(&employees, |employee_group| { let j = 0; - let employee_group = vector::borrow(&employees, i); + let employee_group: &EmployeeAccountMap = employee_group; let num_employees_in_group = vector::length(&employee_group.accounts); let buy_ins = simple_map::create(); @@ -278,9 +271,7 @@ module aptos_framework::genesis { if (employee_group.validator.join_during_genesis) { initialize_validator(pool_address, validator); }; - - i = i + 1; - } + }); } fun create_initialize_validators_with_commission( @@ -288,14 +279,10 @@ module aptos_framework::genesis { use_staking_contract: bool, validators: vector, ) { - let i = 0; - let num_validators = vector::length(&validators); - while (i < num_validators) { - let validator = vector::borrow(&validators, i); + vector::for_each_ref(&validators, |validator| { + let validator: &ValidatorConfigurationWithCommission = validator; create_initialize_validator(aptos_framework, validator, use_staking_contract); - - i = i + 1; - }; + }); // Destroy the aptos framework account's ability to mint coins now that we're done with setting up the initial // validators. @@ -315,21 +302,15 @@ module aptos_framework::genesis { /// Network address fields are a vector per account, where each entry is a vector of addresses /// encoded in a single BCS byte array. fun create_initialize_validators(aptos_framework: &signer, validators: vector) { - let i = 0; - let num_validators = vector::length(&validators); - let validators_with_commission = vector::empty(); - - while (i < num_validators) { + vector::for_each_reverse(validators, |validator| { let validator_with_commission = ValidatorConfigurationWithCommission { - validator_config: vector::pop_back(&mut validators), + validator_config: validator, commission_percentage: 0, join_during_genesis: true, }; vector::push_back(&mut validators_with_commission, validator_with_commission); - - i = i + 1; - }; + }); create_initialize_validators_with_commission(aptos_framework, false, validators_with_commission); } diff --git a/aptos-move/framework/aptos-framework/sources/stake.move b/aptos-move/framework/aptos-framework/sources/stake.move index 2511fc960e23d..9ae0a75f25900 100644 --- a/aptos-move/framework/aptos-framework/sources/stake.move +++ b/aptos-move/framework/aptos-framework/sources/stake.move @@ -1040,23 +1040,17 @@ module aptos_framework::stake { let validator_perf = borrow_global_mut(@aptos_framework); // Process pending stake and distribute transaction fees and rewards for each currently active validator. - let i = 0; - let len = vector::length(&validator_set.active_validators); - while (i < len) { - let validator = vector::borrow(&validator_set.active_validators, i); + vector::for_each_ref(&validator_set.active_validators, |validator| { + let validator: &ValidatorInfo = validator; update_stake_pool(validator_perf, validator.addr, &config); - i = i + 1; - }; + }); // Process pending stake and distribute transaction fees and rewards for each currently pending_inactive validator // (requested to leave but not removed yet). - let i = 0; - let len = vector::length(&validator_set.pending_inactive); - while (i < len) { - let validator = vector::borrow(&validator_set.pending_inactive, i); + vector::for_each_ref(&validator_set.pending_inactive, |validator| { + let validator: &ValidatorInfo = validator; update_stake_pool(validator_perf, validator.addr, &config); - i = i + 1; - }; + }); // Activate currently pending_active validators. append(&mut validator_set.active_validators, &mut validator_set.pending_active); @@ -2586,15 +2580,12 @@ module aptos_framework::stake { #[test_only] public fun set_validator_perf_at_least_one_block() acquires ValidatorPerformance { let validator_perf = borrow_global_mut(@aptos_framework); - let len = vector::length(&validator_perf.validators); - let i = 0; - while (i < len) { - let validator = vector::borrow_mut(&mut validator_perf.validators, i); + vector::for_each_mut(&mut validator_perf.validators, |validator|{ + let validator: &mut IndividualValidatorPerformance = validator; if (validator.successful_proposals + validator.failed_proposals < 1) { validator.successful_proposals = 1; }; - i = i + 1; - }; + }); } #[test(aptos_framework = @0x1, validator_1 = @0x123, validator_2 = @0x234)] diff --git a/aptos-move/framework/aptos-framework/sources/staking_contract.move b/aptos-move/framework/aptos-framework/sources/staking_contract.move index d22841dbac877..9aee053363268 100644 --- a/aptos-move/framework/aptos-framework/sources/staking_contract.move +++ b/aptos-move/framework/aptos-framework/sources/staking_contract.move @@ -703,10 +703,8 @@ module aptos_framework::staking_contract { // Charge all stakeholders (except for the operator themselves) commission on any rewards earnt relatively to the // previous value of the distribution pool. let shareholders = &pool_u64::shareholders(distribution_pool); - let len = vector::length(shareholders); - let i = 0; - while (i < len) { - let shareholder = *vector::borrow(shareholders, i); + vector::for_each_ref(shareholders, |shareholder| { + let shareholder: address = *shareholder; if (shareholder != operator) { let shares = pool_u64::shares(distribution_pool, shareholder); let previous_worth = pool_u64::balance(distribution_pool, shareholder); @@ -719,9 +717,7 @@ module aptos_framework::staking_contract { distribution_pool, unpaid_commission, updated_total_coins); pool_u64::transfer_shares(distribution_pool, shareholder, operator, shares_to_transfer); }; - - i = i + 1; - }; + }); pool_u64::update_total_coins(distribution_pool, updated_total_coins); } diff --git a/aptos-move/framework/aptos-framework/sources/staking_proxy.move b/aptos-move/framework/aptos-framework/sources/staking_proxy.move index 3ac513bfa7df8..26d1aa33372ce 100644 --- a/aptos-move/framework/aptos-framework/sources/staking_proxy.move +++ b/aptos-move/framework/aptos-framework/sources/staking_proxy.move @@ -21,16 +21,13 @@ module aptos_framework::staking_proxy { public entry fun set_vesting_contract_operator(owner: &signer, old_operator: address, new_operator: address) { let owner_address = signer::address_of(owner); let vesting_contracts = &vesting::vesting_contracts(owner_address); - let i = 0; - let len = vector::length(vesting_contracts); - while (i < len) { - let vesting_contract = *vector::borrow(vesting_contracts, i); + vector::for_each_ref(vesting_contracts, |vesting_contract| { + let vesting_contract = *vesting_contract; if (vesting::operator(vesting_contract) == old_operator) { let current_commission_percentage = vesting::operator_commission_percentage(vesting_contract); vesting::update_operator(owner, vesting_contract, new_operator, current_commission_percentage); }; - i = i + 1; - } + }); } public entry fun set_staking_contract_operator(owner: &signer, old_operator: address, new_operator: address) { @@ -51,15 +48,12 @@ module aptos_framework::staking_proxy { public entry fun set_vesting_contract_voter(owner: &signer, operator: address, new_voter: address) { let owner_address = signer::address_of(owner); let vesting_contracts = &vesting::vesting_contracts(owner_address); - let i = 0; - let len = vector::length(vesting_contracts); - while (i < len) { - let vesting_contract = *vector::borrow(vesting_contracts, i); + vector::for_each_ref(vesting_contracts, |vesting_contract| { + let vesting_contract = *vesting_contract; if (vesting::operator(vesting_contract) == operator) { vesting::update_voter(owner, vesting_contract, new_voter); }; - i = i + 1; - } + }); } public entry fun set_staking_contract_voter(owner: &signer, operator: address, new_voter: address) { diff --git a/aptos-move/framework/aptos-framework/sources/vesting.move b/aptos-move/framework/aptos-framework/sources/vesting.move index 0e6231274b2c8..18ae2c2675500 100644 --- a/aptos-move/framework/aptos-framework/sources/vesting.move +++ b/aptos-move/framework/aptos-framework/sources/vesting.move @@ -401,18 +401,17 @@ module aptos_framework::vesting { return shareholder_or_beneficiary }; let vesting_contract = borrow_global(vesting_contract_address); - let i = 0; - let len = vector::length(shareholders); - while (i < len) { - let shareholder = *vector::borrow(shareholders, i); - // This will still return the shareholder if shareholder == beneficiary. - if (shareholder_or_beneficiary == get_beneficiary(vesting_contract, shareholder)) { - return shareholder - }; - i = i + 1; - }; + let result = @0x0; + vector::any(shareholders, |shareholder| { + if (shareholder_or_beneficiary == get_beneficiary(vesting_contract, *shareholder)) { + result = *shareholder; + true + } else { + false + } + }); - @0x0 + result } /// Create a vesting schedule with the given schedule of distributions, a vesting start time and period duration. @@ -464,22 +463,18 @@ module aptos_framework::vesting { let grant = coin::zero(); let grant_amount = 0; let grant_pool = pool_u64::create(MAXIMUM_SHAREHOLDERS); - let len = vector::length(shareholders); - let i = 0; - while (i < len) { - let shareholder = *vector::borrow(shareholders, i); + vector::for_each_ref(shareholders, |shareholder| { + let shareholder: address = *shareholder; let (_, buy_in) = simple_map::remove(&mut buy_ins, &shareholder); let buy_in_amount = coin::value(&buy_in); coin::merge(&mut grant, buy_in); pool_u64::buy_in( &mut grant_pool, - *vector::borrow(shareholders, i), + shareholder, buy_in_amount, ); grant_amount = grant_amount + buy_in_amount; - - i = i + 1; - }; + }); assert!(grant_amount > 0, error::invalid_argument(EZERO_GRANT)); // If this is the first time this admin account has created a vesting contract, initialize the admin store. @@ -553,12 +548,10 @@ module aptos_framework::vesting { assert!(len != 0, error::invalid_argument(EVEC_EMPTY_FOR_MANY_FUNCTION)); - let i = 0; - while (i < len) { - let contract_address = *vector::borrow(&contract_addresses, i); + vector::for_each_ref(&contract_addresses, |contract_address| { + let contract_address: address = *contract_address; unlock_rewards(contract_address); - i = i + 1; - }; + }); } /// Unlock any vested portion of the grant. @@ -620,12 +613,10 @@ module aptos_framework::vesting { assert!(len != 0, error::invalid_argument(EVEC_EMPTY_FOR_MANY_FUNCTION)); - let i = 0; - while (i < len) { - let contract_address = *vector::borrow(&contract_addresses, i); + vector::for_each_ref(&contract_addresses, |contract_address| { + let contract_address = *contract_address; vest(contract_address); - i = i + 1; - }; + }); } /// Distribute any withdrawable stake from the stake pool. @@ -643,18 +634,14 @@ module aptos_framework::vesting { // Distribute coins to all shareholders in the vesting contract. let grant_pool = &vesting_contract.grant_pool; let shareholders = &pool_u64::shareholders(grant_pool); - let len = vector::length(shareholders); - let i = 0; - while (i < len) { - let shareholder = *vector::borrow(shareholders, i); + vector::for_each_ref(shareholders, |shareholder| { + let shareholder = *shareholder; let shares = pool_u64::shares(grant_pool, shareholder); let amount = pool_u64::shares_to_amount_with_total_coins(grant_pool, shares, total_distribution_amount); let share_of_coins = coin::extract(&mut coins, amount); let recipient_address = get_beneficiary(vesting_contract, shareholder); aptos_account::deposit_coins(recipient_address, share_of_coins); - - i = i + 1; - }; + }); // Send any remaining "dust" (leftover due to rounding error) to the withdrawal address. if (coin::value(&coins) > 0) { @@ -679,12 +666,10 @@ module aptos_framework::vesting { assert!(len != 0, error::invalid_argument(EVEC_EMPTY_FOR_MANY_FUNCTION)); - let i = 0; - while (i < len) { - let contract_address = *vector::borrow(&contract_addresses, i); + vector::for_each_ref(&contract_addresses, |contract_address| { + let contract_address = *contract_address; distribute(contract_address); - i = i + 1; - }; + }); } /// Terminate the vesting contract and send all funds back to the withdrawal address. @@ -1017,15 +1002,12 @@ module aptos_framework::vesting { stake::initialize_for_test_custom(aptos_framework, MIN_STAKE, GRANT_AMOUNT * 10, 3600, true, 10, 10000, 1000000); - let len = vector::length(accounts); - let i = 0; - while (i < len) { - let addr = *vector::borrow(accounts, i); + vector::for_each_ref(accounts, |addr| { + let addr: address = *addr; if (!account::exists_at(addr)) { create_account(addr); }; - i = i + 1; - }; + }); } #[test_only] @@ -1058,13 +1040,9 @@ module aptos_framework::vesting { vesting_denominator: u64, ): address acquires AdminStore { let schedule = vector::empty(); - let i = 0; - let len = vector::length(vesting_numerators); - while (i < len) { - let num = *vector::borrow(vesting_numerators, i); - vector::push_back(&mut schedule, fixed_point32::create_from_rational(num, vesting_denominator)); - i = i + 1; - }; + vector::for_each_ref(vesting_numerators, |num| { + vector::push_back(&mut schedule, fixed_point32::create_from_rational(*num, vesting_denominator)); + }); let vesting_schedule = create_vesting_schedule( schedule, timestamp::now_seconds() + VESTING_SCHEDULE_CLIFF, @@ -1073,13 +1051,10 @@ module aptos_framework::vesting { let admin_address = signer::address_of(admin); let buy_ins = simple_map::create>(); - let i = 0; - let len = vector::length(shares); - while (i < len) { + vector::enumerate_ref(shares, |i, share| { let shareholder = *vector::borrow(shareholders, i); - simple_map::add(&mut buy_ins, shareholder, stake::mint_coins(*vector::borrow(shares, i))); - i = i + 1; - }; + simple_map::add(&mut buy_ins, shareholder, stake::mint_coins(*share)); + }); create_vesting_contract( admin, diff --git a/aptos-move/framework/aptos-stdlib/doc/big_vector.md b/aptos-move/framework/aptos-stdlib/doc/big_vector.md index b378efa9e92af..a92da6cf7e232 100644 --- a/aptos-move/framework/aptos-stdlib/doc/big_vector.md +++ b/aptos-move/framework/aptos-stdlib/doc/big_vector.md @@ -557,17 +557,13 @@ Disclaimer: This function is costly. Use it at your own discretion. while (num_buckets_left > 0) { let pop_bucket = table_with_length::remove(&mut v.buckets, num_buckets_left - 1); - let pop_bucket_length = vector::length(&pop_bucket); - let i = 0; - while(i < pop_bucket_length){ - vector::push_back(&mut push_bucket, vector::pop_back(&mut pop_bucket)); + vector::for_each_reverse(pop_bucket, |val| { + vector::push_back(&mut push_bucket, val); if (vector::length(&push_bucket) == v.bucket_size) { vector::push_back(&mut new_buckets, push_bucket); push_bucket = vector[]; }; - i = i + 1; - }; - vector::destroy_empty(pop_bucket); + }); num_buckets_left = num_buckets_left - 1; }; diff --git a/aptos-move/framework/aptos-stdlib/sources/data_structures/big_vector.move b/aptos-move/framework/aptos-stdlib/sources/data_structures/big_vector.move index 809c8db79232e..80dfd8df1a804 100644 --- a/aptos-move/framework/aptos-stdlib/sources/data_structures/big_vector.move +++ b/aptos-move/framework/aptos-stdlib/sources/data_structures/big_vector.move @@ -211,17 +211,13 @@ module aptos_std::big_vector { while (num_buckets_left > 0) { let pop_bucket = table_with_length::remove(&mut v.buckets, num_buckets_left - 1); - let pop_bucket_length = vector::length(&pop_bucket); - let i = 0; - while(i < pop_bucket_length){ - vector::push_back(&mut push_bucket, vector::pop_back(&mut pop_bucket)); + vector::for_each_reverse(pop_bucket, |val| { + vector::push_back(&mut push_bucket, val); if (vector::length(&push_bucket) == v.bucket_size) { vector::push_back(&mut new_buckets, push_bucket); push_bucket = vector[]; }; - i = i + 1; - }; - vector::destroy_empty(pop_bucket); + }); num_buckets_left = num_buckets_left - 1; }; diff --git a/aptos-move/framework/aptos-token/doc/token.md b/aptos-move/framework/aptos-token/doc/token.md index c32f1676137ef..3c1435ad9faa1 100644 --- a/aptos-move/framework/aptos-token/doc/token.md +++ b/aptos-move/framework/aptos-token/doc/token.md @@ -4517,17 +4517,14 @@ Deposit the token balance into the recipients account and emit an event. 
fun assert_non_standard_reserved_property(keys: &vector<String>) {
-    let len = vector::length(keys);
-    let i = 0;
-    while ( i < len) {
-        let key = vector::borrow(keys, i);
+    vector::for_each_ref(keys, |key| {
+        let key: &String = key;
         let length = string::length(key);
         if (length >= 6) {
             let prefix = string::sub_string(&*key, 0, 6);
             assert!(prefix != string::utf8(b"TOKEN_"), error::permission_denied(EPROPERTY_RESERVED_BY_STANDARD));
         };
-        i = i + 1;
-    };
+    });
 }
diff --git a/aptos-move/framework/aptos-token/sources/token.move b/aptos-move/framework/aptos-token/sources/token.move index 0daa58bf15d38..168a6fab2299e 100644 --- a/aptos-move/framework/aptos-token/sources/token.move +++ b/aptos-move/framework/aptos-token/sources/token.move @@ -1660,17 +1660,14 @@ module aptos_token::token { } fun assert_non_standard_reserved_property(keys: &vector) { - let len = vector::length(keys); - let i = 0; - while ( i < len) { - let key = vector::borrow(keys, i); + vector::for_each_ref(keys, |key| { + let key: &String = key; let length = string::length(key); if (length >= 6) { let prefix = string::sub_string(&*key, 0, 6); assert!(prefix != string::utf8(b"TOKEN_"), error::permission_denied(EPROPERTY_RESERVED_BY_STANDARD)); }; - i = i + 1; - }; + }); } // ****************** TEST-ONLY FUNCTIONS ************** diff --git a/aptos-move/framework/move-stdlib/doc/bit_vector.md b/aptos-move/framework/move-stdlib/doc/bit_vector.md index f847b7777c18f..89c80fd9773dc 100644 --- a/aptos-move/framework/move-stdlib/doc/bit_vector.md +++ b/aptos-move/framework/move-stdlib/doc/bit_vector.md @@ -219,13 +219,9 @@ bitvector's length the bitvector will be zeroed out. 
public fun shift_left(bitvector: &mut BitVector, amount: u64) {
     if (amount >= bitvector.length) {
-       let len = vector::length(&bitvector.bit_field);
-       let i = 0;
-       while (i < len) {
-           let elem = vector::borrow_mut(&mut bitvector.bit_field, i);
-           *elem = false;
-           i = i + 1;
-       };
+        vector::for_each_mut(&mut bitvector.bit_field, |elem| {
+            *elem = false;
+        });
     } else {
         let i = amount;
 
diff --git a/aptos-move/framework/move-stdlib/doc/features.md b/aptos-move/framework/move-stdlib/doc/features.md
index 96c26cbd06b8b..b4e73ba58b3e2 100644
--- a/aptos-move/framework/move-stdlib/doc/features.md
+++ b/aptos-move/framework/move-stdlib/doc/features.md
@@ -997,18 +997,12 @@ Function to enable and disable features. Can only be called by a signer of @std.
         move_to<Features>(framework, Features{features: vector[]})
     };
     let features = &mut borrow_global_mut<Features>(@std).features;
-    let i = 0;
-    let n = vector::length(&enable);
-    while (i < n) {
-        set(features, *vector::borrow(&enable, i), true);
-        i = i + 1
-    };
-    let i = 0;
-    let n = vector::length(&disable);
-    while (i < n) {
-        set(features, *vector::borrow(&disable, i), false);
-        i = i + 1
-    };
+    vector::for_each_ref(&enable, |feature| {
+        set(features, *feature, true);
+    });
+    vector::for_each_ref(&disable, |feature| {
+        set(features, *feature, false);
+    });
 }
diff --git a/aptos-move/framework/move-stdlib/doc/vector.md b/aptos-move/framework/move-stdlib/doc/vector.md index 2374b89f7a7e0..52f1002a82ca8 100644 --- a/aptos-move/framework/move-stdlib/doc/vector.md +++ b/aptos-move/framework/move-stdlib/doc/vector.md @@ -41,7 +41,9 @@ the return on investment didn't seem worth it for these simple functions. - [Function `for_each`](#0x1_vector_for_each) - [Function `for_each_reverse`](#0x1_vector_for_each_reverse) - [Function `for_each_ref`](#0x1_vector_for_each_ref) +- [Function `enumerate_ref`](#0x1_vector_enumerate_ref) - [Function `for_each_mut`](#0x1_vector_for_each_mut) +- [Function `enumerate_mut`](#0x1_vector_enumerate_mut) - [Function `fold`](#0x1_vector_fold) - [Function `foldr`](#0x1_vector_foldr) - [Function `map_ref`](#0x1_vector_map_ref) @@ -796,6 +798,36 @@ Apply the function to a reference of each element in the vector. + + + + +## Function `enumerate_ref` + +Apply the function to a reference of each element in the vector with its index. + + +
public fun enumerate_ref<Element>(v: &vector<Element>, f: |(u64, &Element)|())
+
+ + + +
+Implementation + + +
public inline fun enumerate_ref<Element>(v: &vector<Element>, f: |u64, &Element|) {
+    let i = 0;
+    let len = length(v);
+    while (i < len) {
+        f(i, borrow(v, i));
+        i = i + 1;
+    };
+}
+
+ + +
@@ -826,6 +858,36 @@ Apply the function to a mutable reference to each element in the vector. + + + + +## Function `enumerate_mut` + +Apply the function to a mutable reference of each element in the vector with its index. + + +
public fun enumerate_mut<Element>(v: &mut vector<Element>, f: |(u64, &mut Element)|())
+
+ + + +
+Implementation + + +
public inline fun enumerate_mut<Element>(v: &mut vector<Element>, f: |u64, &mut Element|) {
+    let i = 0;
+    let len = length(v);
+    while (i < len) {
+        f(i, borrow_mut(v, i));
+        i = i + 1;
+    };
+}
+
+ + +
diff --git a/aptos-move/framework/move-stdlib/sources/bit_vector.move b/aptos-move/framework/move-stdlib/sources/bit_vector.move index e89795422c373..e0202f13b849c 100644 --- a/aptos-move/framework/move-stdlib/sources/bit_vector.move +++ b/aptos-move/framework/move-stdlib/sources/bit_vector.move @@ -85,13 +85,9 @@ module std::bit_vector { /// bitvector's length the bitvector will be zeroed out. public fun shift_left(bitvector: &mut BitVector, amount: u64) { if (amount >= bitvector.length) { - let len = vector::length(&bitvector.bit_field); - let i = 0; - while (i < len) { - let elem = vector::borrow_mut(&mut bitvector.bit_field, i); - *elem = false; - i = i + 1; - }; + vector::for_each_mut(&mut bitvector.bit_field, |elem| { + *elem = false; + }); } else { let i = amount; diff --git a/aptos-move/framework/move-stdlib/sources/configs/features.move b/aptos-move/framework/move-stdlib/sources/configs/features.move index 1e327ea9fe5b5..8f76a00cd6305 100644 --- a/aptos-move/framework/move-stdlib/sources/configs/features.move +++ b/aptos-move/framework/move-stdlib/sources/configs/features.move @@ -205,18 +205,12 @@ module std::features { move_to(framework, Features{features: vector[]}) }; let features = &mut borrow_global_mut(@std).features; - let i = 0; - let n = vector::length(&enable); - while (i < n) { - set(features, *vector::borrow(&enable, i), true); - i = i + 1 - }; - let i = 0; - let n = vector::length(&disable); - while (i < n) { - set(features, *vector::borrow(&disable, i), false); - i = i + 1 - }; + vector::for_each_ref(&enable, |feature| { + set(features, *feature, true); + }); + vector::for_each_ref(&disable, |feature| { + set(features, *feature, false); + }); } /// Check whether the feature is enabled. diff --git a/aptos-move/framework/move-stdlib/sources/vector.move b/aptos-move/framework/move-stdlib/sources/vector.move index d0b8d3fd7b773..1fdb2a2a29ea2 100644 --- a/aptos-move/framework/move-stdlib/sources/vector.move +++ b/aptos-move/framework/move-stdlib/sources/vector.move @@ -263,6 +263,16 @@ module std::vector { } } + /// Apply the function to a reference of each element in the vector with its index. + public inline fun enumerate_ref(v: &vector, f: |u64, &Element|) { + let i = 0; + let len = length(v); + while (i < len) { + f(i, borrow(v, i)); + i = i + 1; + }; + } + /// Apply the function to a mutable reference to each element in the vector. public inline fun for_each_mut(v: &mut vector, f: |&mut Element|) { let i = 0; @@ -273,6 +283,16 @@ module std::vector { } } + /// Apply the function to a mutable reference of each element in the vector with its index. + public inline fun enumerate_mut(v: &mut vector, f: |u64, &mut Element|) { + let i = 0; + let len = length(v); + while (i < len) { + f(i, borrow_mut(v, i)); + i = i + 1; + }; + } + /// Fold the function over the elements. For example, `fold(vector[1,2,3], 0, f)` will execute /// `f(f(f(0, 1), 2), 3)` public inline fun fold( diff --git a/aptos-move/framework/move-stdlib/tests/vector_tests.move b/aptos-move/framework/move-stdlib/tests/vector_tests.move index d686783d5dcb5..ea2c540d9880d 100644 --- a/aptos-move/framework/move-stdlib/tests/vector_tests.move +++ b/aptos-move/framework/move-stdlib/tests/vector_tests.move @@ -588,6 +588,19 @@ module std::vector_tests { assert!(s == 6, 0) } + #[test] + fun test_enumerate_ref() { + let v = vector[1, 2, 3]; + let i_s = 0; + let s = 0; + V::enumerate_ref(&v, |i, e| { + i_s = i_s + i; + s = s + *e; + }); + assert!(i_s == 3, 0); + assert!(s == 6, 0); + } + #[test] fun test_for_each_ref() { let v = vector[1, 2, 3]; @@ -604,6 +617,20 @@ module std::vector_tests { assert!(v == vector[2, 3, 4], 0) } + #[test] + fun test_enumerate_mut() { + let v = vector[1, 2, 3]; + let i_s = 0; + let s = 2; + V::enumerate_mut(&mut v, |i, e| { + i_s = i_s + i; + *e = s; + s = s + 1 + }); + assert!(i_s == 3, 0); + assert!(v == vector[2, 3, 4], 0); + } + #[test] fun test_fold() { let v = vector[1, 2, 3]; diff --git a/aptos-move/move-examples/dao/nft_dao/sources/bucket_table.move b/aptos-move/move-examples/dao/nft_dao/sources/bucket_table.move index c27e8f48529b9..97727ff5037f6 100644 --- a/aptos-move/move-examples/dao/nft_dao/sources/bucket_table.move +++ b/aptos-move/move-examples/dao/nft_dao/sources/bucket_table.move @@ -68,13 +68,10 @@ module dao_platform::bucket_table { let hash = sip_hash_from_value(&key); let index = bucket_index(map.level, map.num_buckets, hash); let bucket = table_with_length::borrow_mut(&mut map.buckets, index); - let i = 0; - let len = vector::length(bucket); - while (i < len) { - let entry = vector::borrow(bucket, i); + vector::for_each_ref(bucket, |entry| { + let entry: &Entry = entry; assert!(&entry.key != &key, error::invalid_argument(EALREADY_EXIST)); - i = i + 1; - }; + }); vector::push_back(bucket, Entry {hash, key, value}); map.len = map.len + 1; @@ -177,16 +174,10 @@ module dao_platform::bucket_table { public fun contains(map: &BucketTable, key: &K): bool { let index = bucket_index(map.level, map.num_buckets, sip_hash_from_value(key)); let bucket = table_with_length::borrow(&map.buckets, index); - let i = 0; - let len = vector::length(bucket); - while (i < len) { - let entry = vector::borrow(bucket, i); - if (&entry.key == key) { - return true - }; - i = i + 1; - }; - false + vector::any(bucket, |entry| { + let entry: &Entry = entry; + &entry.key == key + }) } /// Remove from `table` and return the value which `key` maps to. diff --git a/aptos-move/move-examples/dao/nft_dao/sources/nft_dao.move b/aptos-move/move-examples/dao/nft_dao/sources/nft_dao.move index 7cd9e2dbaa2b0..659d0858b2be5 100644 --- a/aptos-move/move-examples/dao/nft_dao/sources/nft_dao.move +++ b/aptos-move/move-examples/dao/nft_dao/sources/nft_dao.move @@ -343,9 +343,7 @@ module dao_platform::nft_dao { }; let function_args = vector::empty(); - let cnt = 0; - while (cnt < fcnt) { - let fname = vector::borrow(&function_names, cnt); + vector::enumerate_ref(&function_names, |cnt, fname| { let arg_names = vector::borrow(&arg_names, cnt); let arg_values = vector::borrow(&arg_values, cnt); let arg_types = vector::borrow(&arg_types, cnt); @@ -353,8 +351,7 @@ module dao_platform::nft_dao { let pm = property_map::new(*arg_names, *arg_values, *arg_types); assert_function_valid(*fname, &pm); vector::push_back(&mut function_args, pm); - cnt = cnt + 1; - }; + }); // verify the start_time is in future let now = timestamp::now_seconds(); @@ -429,10 +426,9 @@ module dao_platform::nft_dao { let stats = table::borrow_mut(&mut prop_stats.proposals, proposal_id); let voter_addr = signer::address_of(account); - let i = 0; // loop through all NFTs used for voting and update the voting result - while (i < vector::length(&token_names)) { - let token_name = *vector::borrow(&token_names, i); + vector::enumerate_ref(&token_names, |i, token_name| { + let token_name = *token_name; let property_version = *vector::borrow(&property_versions, i); let token_id = token::create_token_id_raw(gtoken.creator, gtoken.collection, token_name, property_version); // check if this token already voted @@ -448,8 +444,7 @@ module dao_platform::nft_dao { stats.total_no = stats.total_no + 1; bucket_table::add(&mut stats.no_votes, token_id, voter_addr); }; - i = i + 1; - }; + }); nft_dao_events::emit_voting_event( voter_addr, @@ -691,10 +686,7 @@ module dao_platform::nft_dao { /// Internal function for executing a DAO's proposal fun execute_proposal(proposal: &Proposal, dao: &DAO){ - let fcnt = vector::length(&proposal.function_names); - let i = 0; - while (i < fcnt) { - let function_name = vector::borrow(&proposal.function_names, i); + vector::enumerate_ref(&proposal.function_names, |i, function_name| { let args = vector::borrow(&proposal.function_args, i); if (function_name == &string::utf8(b"transfer_fund")) { let res_signer = create_signer_with_capability(&dao.dao_signer_capability); @@ -712,8 +704,7 @@ module dao_platform::nft_dao { } else { assert!(function_name == &string::utf8(b"no_op"), error::invalid_argument(ENOT_SUPPROTED_FUNCTION)); }; - i = i + 1; - }; + }); } /// Resolve an proposal @@ -764,18 +755,16 @@ module dao_platform::nft_dao { dao: &DAO ): u64 { let gtoken = &dao.governance_token; - let i = 0; let used_token_ids = vector::empty(); let total = vector::length(token_names); - while (i < total) { - let token_name = *vector::borrow(token_names, i); + vector::enumerate_ref(token_names, |i, token_name| { + let token_name = *token_name; let property_version = *vector::borrow(property_versions, i); let token_id = token::create_token_id_raw(gtoken.creator, gtoken.collection, token_name, property_version); assert!(!vector::contains(&used_token_ids, &token_id), error::already_exists(ETOKEN_USED_FOR_CREATING_PROPOSAL)); vector::push_back(&mut used_token_ids, token_id); assert!(token::balance_of(signer::address_of(account), token_id) == 1, error::permission_denied(ENOT_OWN_THE_VOTING_DAO_TOKEN)); - i = i + 1; - }; + }); total } diff --git a/aptos-move/move-examples/defi/sources/locked_coins.move b/aptos-move/move-examples/defi/sources/locked_coins.move index 8790bf7d3966f..adc13d861c5d6 100644 --- a/aptos-move/move-examples/defi/sources/locked_coins.move +++ b/aptos-move/move-examples/defi/sources/locked_coins.move @@ -156,13 +156,10 @@ module defi::locked_coins { sponsor: &signer, recipients: vector
, amounts: vector, unlock_time_secs: u64) acquires Locks { let len = vector::length(&recipients); assert!(len == vector::length(&amounts), error::invalid_argument(EINVALID_RECIPIENTS_LIST_LENGTH)); - let i = 0; - while (i < len) { - let recipient = *vector::borrow(&recipients, i); + vector::enumerate_ref(&recipients, |i, recipient| { let amount = *vector::borrow(&amounts, i); - add_locked_coins(sponsor, recipient, amount, unlock_time_secs); - i = i + 1; - } + add_locked_coins(sponsor, *recipient, amount, unlock_time_secs); + }); } /// `Sponsor` can add locked coins for `recipient` with given unlock timestamp (in seconds). @@ -213,13 +210,9 @@ module defi::locked_coins { let sponsor_address = signer::address_of(sponsor); assert!(exists>(sponsor_address), error::not_found(ESPONSOR_ACCOUNT_NOT_INITIALIZED)); - let len = vector::length(&recipients); - let i = 0; - while (i < len) { - let recipient = *vector::borrow(&recipients, i); - update_lockup(sponsor, recipient, new_unlock_time_secs); - i = i + 1; - }; + vector::for_each_ref(&recipients, |recipient| { + update_lockup(sponsor, *recipient, new_unlock_time_secs); + }); } /// Sponsor can update the lockup of an existing lock. @@ -246,13 +239,9 @@ module defi::locked_coins { let sponsor_address = signer::address_of(sponsor); assert!(exists>(sponsor_address), error::not_found(ESPONSOR_ACCOUNT_NOT_INITIALIZED)); - let len = vector::length(&recipients); - let i = 0; - while (i < len) { - let recipient = *vector::borrow(&recipients, i); - cancel_lockup(sponsor, recipient); - i = i + 1; - }; + vector::for_each_ref(&recipients, |recipient| { + cancel_lockup(sponsor, *recipient); + }); } /// Sponsor can cancel an existing lock. diff --git a/aptos-move/move-examples/post_mint_reveal_nft/sources/bucket_table.move b/aptos-move/move-examples/post_mint_reveal_nft/sources/bucket_table.move index 3a0bbd3113f0a..fa1d601fb0535 100644 --- a/aptos-move/move-examples/post_mint_reveal_nft/sources/bucket_table.move +++ b/aptos-move/move-examples/post_mint_reveal_nft/sources/bucket_table.move @@ -71,13 +71,10 @@ module post_mint_reveal_nft::bucket_table { let hash = sip_hash_from_value(&key); let index = bucket_index(map.level, map.num_buckets, hash); let bucket = table_with_length::borrow_mut(&mut map.buckets, index); - let i = 0; - let len = vector::length(bucket); - while (i < len) { - let entry = vector::borrow(bucket, i); + vector::for_each_ref(bucket, |entry|{ + let entry: &Entry = entry; assert!(&entry.key != &key, error::invalid_argument(EALREADY_EXIST)); - i = i + 1; - }; + }); vector::push_back(bucket, Entry {hash, key, value}); map.len = map.len + 1; @@ -180,16 +177,10 @@ module post_mint_reveal_nft::bucket_table { public fun contains(map: &BucketTable, key: &K): bool { let index = bucket_index(map.level, map.num_buckets, sip_hash_from_value(key)); let bucket = table_with_length::borrow(&map.buckets, index); - let i = 0; - let len = vector::length(bucket); - while (i < len) { - let entry = vector::borrow(bucket, i); - if (&entry.key == key) { - return true - }; - i = i + 1; - }; - false + vector::any(bucket, |entry| { + let entry: &Entry = entry; + &entry.key == key + }) } /// Remove from `table` and return the value which `key` maps to. diff --git a/aptos-move/move-examples/post_mint_reveal_nft/sources/minting.move b/aptos-move/move-examples/post_mint_reveal_nft/sources/minting.move index 49e0147f5d8aa..0940e28232260 100644 --- a/aptos-move/move-examples/post_mint_reveal_nft/sources/minting.move +++ b/aptos-move/move-examples/post_mint_reveal_nft/sources/minting.move @@ -374,9 +374,7 @@ module post_mint_reveal_nft::minting { assert!(vector::length(&token_uris) + big_vector::length(&collection_config.tokens) <= collection_config.destination_collection_maximum || collection_config.destination_collection_maximum == 0, error::invalid_argument(EEXCEEDS_COLLECTION_MAXIMUM)); - let i = 0; - while (i < vector::length(&token_uris)) { - let token_uri = vector::borrow(&token_uris, i); + vector::enumerate_ref(&token_uris, |i, token_uri| { assert!(!bucket_table::contains(&collection_config.deduped_tokens, token_uri), error::invalid_argument(EDUPLICATE_TOKEN_URI)); big_vector::push_back(&mut collection_config.tokens, TokenAsset { token_uri: *token_uri, @@ -385,8 +383,7 @@ module post_mint_reveal_nft::minting { property_types: *vector::borrow(&property_types, i), }); bucket_table::add(&mut collection_config.deduped_tokens, *token_uri, true); - i = i + 1; - }; + }); } /// Mint source certificate. diff --git a/aptos-move/move-examples/post_mint_reveal_nft/sources/whitelist.move b/aptos-move/move-examples/post_mint_reveal_nft/sources/whitelist.move index 16186e841d3a4..c05c3de4b9547 100644 --- a/aptos-move/move-examples/post_mint_reveal_nft/sources/whitelist.move +++ b/aptos-move/move-examples/post_mint_reveal_nft/sources/whitelist.move @@ -134,11 +134,8 @@ module post_mint_reveal_nft::whitelist { let now = timestamp::now_seconds(); assert!(now < whitelist_stage.whitelist_minting_end_time, error::invalid_argument(EINVALID_UPDATE_AFTER_MINTING)); - let i = 0; - while (i < vector::length(&wl_addresses)) { - let wl_address = vector::borrow(&wl_addresses, i); + vector::for_each_ref(&wl_addresses, |wl_address| { bucket_table::add(&mut whitelist_stage.whitelisted_address, *wl_address, mint_limit); - i = i + 1; - }; + }); } } diff --git a/aptos-move/move-examples/shared_account/sources/shared_account.move b/aptos-move/move-examples/shared_account/sources/shared_account.move index 0479181588a4a..d71c9414eb892 100644 --- a/aptos-move/move-examples/shared_account/sources/shared_account.move +++ b/aptos-move/move-examples/shared_account/sources/shared_account.move @@ -30,22 +30,20 @@ module shared_account::SharedAccount { // Create and initialize a shared account public entry fun initialize(source: &signer, seed: vector, addresses: vector
, numerators: vector) { - let i = 0; let total = 0; let share_record = vector::empty(); - while (i < vector::length(&addresses)) { + vector::enumerate_ref(&addresses, |i, addr|{ + let addr = *addr; let num_shares = *vector::borrow(&numerators, i); - let addr = *vector::borrow(&addresses, i); // make sure that the account exists, so when we call disperse() it wouldn't fail // because one of the accounts does not exist assert!(account::exists_at(addr), error::invalid_argument(EACCOUNT_NOT_FOUND)); - vector::push_back(&mut share_record, Share { share_holder: addr, num_shares: num_shares }); + vector::push_back(&mut share_record, Share { share_holder: addr, num_shares }); total = total + num_shares; - i = i + 1; - }; + }); let (resource_signer, resource_signer_cap) = account::create_resource_account(source, seed); @@ -73,13 +71,11 @@ module shared_account::SharedAccount { let shared_account = borrow_global(resource_addr); let resource_signer = account::create_signer_with_capability(&shared_account.signer_capability); - let i = 0; - while (i < vector::length(&shared_account.share_record)) { - let share_record = vector::borrow(&shared_account.share_record, i); - let current_amount = share_record.num_shares * total_balance / shared_account.total_shares; - coin::transfer(&resource_signer, share_record.share_holder, current_amount); - i = i + 1; - }; + vector::for_each_ref(&shared_account.share_record, |shared_record|{ + let shared_record: &Share = shared_record; + let current_amount = shared_record.num_shares * total_balance / shared_account.total_shares; + coin::transfer(&resource_signer, shared_record.share_holder, current_amount); + }); } #[test_only] From 3fcf9adc0d8f48c5c7c15394ee38bb337aa1181a Mon Sep 17 00:00:00 2001 From: Rustie Lin Date: Mon, 5 Jun 2023 12:06:40 -0700 Subject: [PATCH 071/200] [tf/gcp][fullnode] make NAP use PFN service account (#8527) * [helm][fullnode] fix affinity block * [tf/gcp][fullnode] make NAP use PFN service account --- terraform/fullnode/gcp/cluster.tf | 4 ++++ terraform/helm/fullnode/templates/backup-verify.yaml | 6 +++--- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/terraform/fullnode/gcp/cluster.tf b/terraform/fullnode/gcp/cluster.tf index 8d0eebdc4b4bf..23972cc4b0257 100644 --- a/terraform/fullnode/gcp/cluster.tf +++ b/terraform/fullnode/gcp/cluster.tf @@ -74,6 +74,10 @@ resource "google_container_cluster" "aptos" { maximum = resource_limits.value } } + auto_provisioning_defaults { + oauth_scopes = ["https://www.googleapis.com/auth/cloud-platform"] + service_account = google_service_account.gke.email + } } } diff --git a/terraform/helm/fullnode/templates/backup-verify.yaml b/terraform/helm/fullnode/templates/backup-verify.yaml index 3282111f5c6f2..d5900203888d8 100644 --- a/terraform/helm/fullnode/templates/backup-verify.yaml +++ b/terraform/helm/fullnode/templates/backup-verify.yaml @@ -78,15 +78,15 @@ spec: fsGroup: 6180 {{- with .nodeSelector }} nodeSelector: - {{- toYaml . | nindent 8 }} + {{- toYaml . | nindent 12 }} {{- end }} {{- with .affinity }} affinity: - {{- toYaml . | nindent 8 }} + {{- toYaml . | nindent 12 }} {{- end }} {{- with .tolerations }} tolerations: - {{- toYaml . | nindent 8 }} + {{- toYaml . | nindent 12 }} {{- end }} {{- end }} volumes: From 95ff72e2e871cf16aeba05a444eaca7dfe031357 Mon Sep 17 00:00:00 2001 From: Stelian Ionescu Date: Mon, 5 Jun 2023 19:58:48 -0400 Subject: [PATCH 072/200] [TF] More fixes for GCP DNS (#8253) --- terraform/aptos-node-testnet/aws/variables.tf | 1 - terraform/aptos-node-testnet/gcp/addons.tf | 137 +++++++++++++++++- terraform/aptos-node-testnet/gcp/main.tf | 4 +- terraform/aptos-node-testnet/gcp/variables.tf | 20 +++ terraform/aptos-node/gcp/cluster.tf | 4 + terraform/aptos-node/gcp/dns.tf | 8 +- terraform/aptos-node/gcp/kubernetes.tf | 8 + terraform/aptos-node/gcp/outputs.tf | 4 + terraform/aptos-node/gcp/security.tf | 32 +--- terraform/aptos-node/gcp/variables.tf | 53 ++++--- terraform/aptos-node/gcp/versions.tf | 6 +- terraform/helm/aptos-node/values.yaml | 6 +- .../testnet-addons/templates/ingress.yaml | 30 +++- .../testnet-addons/templates/service.yaml | 25 ++++ terraform/helm/testnet-addons/values.yaml | 7 +- 15 files changed, 280 insertions(+), 65 deletions(-) diff --git a/terraform/aptos-node-testnet/aws/variables.tf b/terraform/aptos-node-testnet/aws/variables.tf index 8a32a7756033e..c9d58a14ae6cd 100644 --- a/terraform/aptos-node-testnet/aws/variables.tf +++ b/terraform/aptos-node-testnet/aws/variables.tf @@ -71,7 +71,6 @@ variable "chain_id" { default = 4 } - variable "era" { description = "Chain era, used to start a clean chain" default = 15 diff --git a/terraform/aptos-node-testnet/gcp/addons.tf b/terraform/aptos-node-testnet/gcp/addons.tf index 529d124632118..7773fb4c7cc20 100644 --- a/terraform/aptos-node-testnet/gcp/addons.tf +++ b/terraform/aptos-node-testnet/gcp/addons.tf @@ -1,5 +1,6 @@ locals { - chaos_mesh_helm_chart_path = "${path.module}/../../helm/chaos" + chaos_mesh_helm_chart_path = "${path.module}/../../helm/chaos" + testnet_addons_helm_chart_path = "${path.module}/../../helm/testnet-addons" } resource "kubernetes_namespace" "chaos-mesh" { @@ -56,3 +57,137 @@ resource "helm_release" "chaos-mesh" { value = sha1(join("", [for f in fileset(local.chaos_mesh_helm_chart_path, "**") : filesha1("${local.chaos_mesh_helm_chart_path}/${f}")])) } } + +resource "google_service_account" "k8s-gcp-integrations" { + project = var.project + account_id = "${local.workspace_name}-testnet-gcp" +} + +resource "google_project_iam_member" "k8s-gcp-integrations-dns" { + project = local.zone_project + role = "roles/dns.admin" + member = "serviceAccount:${google_service_account.k8s-gcp-integrations.email}" +} + +resource "google_service_account_iam_binding" "k8s-gcp-integrations" { + service_account_id = google_service_account.k8s-gcp-integrations.name + role = "roles/iam.workloadIdentityUser" + members = ["serviceAccount:${module.validator.gke_cluster_workload_identity_config[0].workload_pool}[kube-system/k8s-gcp-integrations]"] +} + +resource "kubernetes_service_account" "k8s-gcp-integrations" { + metadata { + name = "k8s-gcp-integrations" + namespace = "kube-system" + annotations = { + "iam.gke.io/gcp-service-account" = google_service_account.k8s-gcp-integrations.email + } + } +} + +data "google_dns_managed_zone" "testnet" { + count = var.zone_name != "" ? 1 : 0 + name = var.zone_name + project = local.zone_project +} + +locals { + zone_project = var.zone_project != "" ? var.zone_project : var.project + dns_prefix = var.workspace_dns ? "${local.workspace_name}." : "" + domain = var.zone_name != "" ? trimsuffix("${local.dns_prefix}${data.google_dns_managed_zone.testnet[0].dns_name}", ".") : null +} + +resource "helm_release" "external-dns" { + count = var.zone_name != "" ? 1 : 0 + name = "external-dns" + repository = "https://kubernetes-sigs.github.io/external-dns" + chart = "external-dns" + version = "1.11.0" + namespace = "kube-system" + max_history = 5 + wait = false + + values = [ + jsonencode({ + serviceAccount = { + create = false + name = kubernetes_service_account.k8s-gcp-integrations.metadata[0].name + } + provider = "google" + domainFilters = var.zone_name != "" ? [data.google_dns_managed_zone.testnet[0].dns_name] : [] + extraArgs = [ + "--google-project=${local.zone_project}", + "--txt-owner-id=aptos-${local.workspace_name}", + # "--txt-prefix=aptos-", + ] + }) + ] +} + +resource "google_compute_global_address" "testnet-addons-ingress" { + count = var.zone_name != "" ? 1 : 0 + project = var.project + name = "aptos-${local.workspace_name}-testnet-addons-ingress" +} + +# This kind of certificate is a GCE resource, and has to be +# added to the ingress using ingress.gcp.kubernetes.io/pre-shared-cert. +# K8s ManagedCertificate resources use +# networking.gke.io/managed-certificates instead. +resource "google_compute_managed_ssl_certificate" "testnet-addons" { + count = var.zone_name != "" ? 1 : 0 + project = var.project + name = "aptos-${local.workspace_name}-testnet-addons" + lifecycle { + create_before_destroy = true + } + managed { + domains = [ + "${local.domain}.", + "api.${local.domain}.", + ] + } +} + +resource "helm_release" "testnet-addons" { + count = var.enable_forge ? 0 : 1 + name = "testnet-addons" + chart = local.testnet_addons_helm_chart_path + max_history = 5 + wait = false + + values = [ + jsonencode({ + cloud = "GKE" + imageTag = var.image_tag + # The addons need to be able to refer to the Genesis parameters + genesis = { + era = var.era + username_prefix = local.aptos_node_helm_prefix + chain_id = var.chain_id + numValidators = var.num_validators + } + service = { + domain = local.domain + } + ingress = { + gcp_static_ip = "aptos-${local.workspace_name}-testnet-addons-ingress" + gcp_certificate = "aptos-${local.workspace_name}-testnet-addons" + } + load_test = { + fullnodeGroups = try(var.aptos_node_helm_values.fullnode.groups, []) + config = { + numFullnodeGroups = var.num_fullnode_groups + } + } + }), + ] + dynamic "set" { + for_each = var.manage_via_tf ? toset([""]) : toset([]) + content { + # inspired by https://stackoverflow.com/a/66501021 to trigger redeployment whenever any of the charts file contents change. + name = "chart_sha1" + value = sha1(join("", [for f in fileset(local.testnet_addons_helm_chart_path, "**") : filesha1("${local.testnet_addons_helm_chart_path}/${f}")])) + } + } +} diff --git a/terraform/aptos-node-testnet/gcp/main.tf b/terraform/aptos-node-testnet/gcp/main.tf index 3a512ca20dfc3..00b5de61353a6 100644 --- a/terraform/aptos-node-testnet/gcp/main.tf +++ b/terraform/aptos-node-testnet/gcp/main.tf @@ -31,7 +31,8 @@ module "validator" { record_name = var.record_name # do not create the main fullnode and validator DNS records # instead, rely on external-dns from the testnet-addons - create_dns_records = false + create_dns_records = var.create_dns_records + dns_ttl = var.dns_ttl # General chain config era = var.era @@ -99,6 +100,7 @@ resource "helm_release" "genesis" { genesis = { numValidators = var.num_validators username_prefix = local.aptos_node_helm_prefix + domain = local.domain validator = { enable_onchain_discovery = false } diff --git a/terraform/aptos-node-testnet/gcp/variables.tf b/terraform/aptos-node-testnet/gcp/variables.tf index 638924c5c9cf8..1daff33e24e02 100644 --- a/terraform/aptos-node-testnet/gcp/variables.tf +++ b/terraform/aptos-node-testnet/gcp/variables.tf @@ -50,6 +50,16 @@ variable "image_tag" { ### DNS config +variable "workspace_dns" { + description = "Include Terraform workspace name in DNS records" + default = true +} + +variable "dns_prefix_name" { + description = "DNS prefix for fullnode url" + default = "fullnode" +} + variable "zone_name" { description = "Zone name of GCP Cloud DNS zone to create records in" default = "" @@ -65,6 +75,16 @@ variable "record_name" { default = ".aptos" } +variable "create_dns_records" { + description = "Creates DNS records in var.zone_name that point to k8s service, as opposed to using external-dns or other means" + default = true +} + +variable "dns_ttl" { + description = "Time-to-Live for the Validator and Fullnode DNS records" + default = 300 +} + ### Testnet config variable "workspace_name_override" { diff --git a/terraform/aptos-node/gcp/cluster.tf b/terraform/aptos-node/gcp/cluster.tf index 5bf9d08c5c15e..d36a71d781af6 100644 --- a/terraform/aptos-node/gcp/cluster.tf +++ b/terraform/aptos-node/gcp/cluster.tf @@ -13,6 +13,10 @@ resource "google_container_cluster" "aptos" { channel = "REGULAR" } + pod_security_policy_config { + enabled = false + } + master_auth { client_certificate_config { issue_client_certificate = false diff --git a/terraform/aptos-node/gcp/dns.tf b/terraform/aptos-node/gcp/dns.tf index 9cc8286e5239b..b0518237b831b 100644 --- a/terraform/aptos-node/gcp/dns.tf +++ b/terraform/aptos-node/gcp/dns.tf @@ -10,13 +10,14 @@ resource "random_string" "validator-dns" { } locals { + dns_prefix = var.workspace_dns ? "${local.workspace_name}." : "" record_name = replace(var.record_name, "", local.workspace_name) + domain = var.zone_name != "" ? "${local.dns_prefix}${data.google_dns_managed_zone.aptos[0].dns_name}" : null } data "kubernetes_service" "validator-lb" { count = var.zone_name != "" && var.create_dns_records ? 1 : 0 metadata { - # This is the main validator LB service that is created by the aptos-node helm chart name = "${local.workspace_name}-aptos-node-0-validator-lb" } depends_on = [time_sleep.lb_creation] @@ -25,7 +26,6 @@ data "kubernetes_service" "validator-lb" { data "kubernetes_service" "fullnode-lb" { count = var.zone_name != "" && var.create_dns_records ? 1 : 0 metadata { - # This is the main fullnode LB service that is created by the aptos-node helm chart name = "${local.workspace_name}-aptos-node-0-fullnode-lb" } depends_on = [time_sleep.lb_creation] @@ -43,7 +43,7 @@ resource "google_dns_record_set" "validator" { project = data.google_dns_managed_zone.aptos[0].project name = "${random_string.validator-dns.result}.${local.record_name}.${data.google_dns_managed_zone.aptos[0].dns_name}" type = "A" - ttl = 3600 + ttl = var.dns_ttl rrdatas = [data.kubernetes_service.validator-lb[0].status[0].load_balancer[0].ingress[0].ip] } @@ -53,7 +53,7 @@ resource "google_dns_record_set" "fullnode" { project = data.google_dns_managed_zone.aptos[0].project name = "${local.record_name}.${data.google_dns_managed_zone.aptos[0].dns_name}" type = "A" - ttl = 3600 + ttl = var.dns_ttl rrdatas = [data.kubernetes_service.fullnode-lb[0].status[0].load_balancer[0].ingress[0].ip] } diff --git a/terraform/aptos-node/gcp/kubernetes.tf b/terraform/aptos-node/gcp/kubernetes.tf index 00bda9f43e2d8..970b4487b94c8 100644 --- a/terraform/aptos-node/gcp/kubernetes.tf +++ b/terraform/aptos-node/gcp/kubernetes.tf @@ -77,6 +77,14 @@ resource "helm_release" "validator" { effect = "NoExecute" }] } + haproxy = { + nodeSelector = var.gke_enable_node_autoprovisioning ? {} : { + "cloud.google.com/gke-nodepool" = google_container_node_pool.utilities.name + } + } + service = { + domain = local.domain + } }), var.helm_values_file != "" ? file(var.helm_values_file) : "{}", jsonencode(var.helm_values), diff --git a/terraform/aptos-node/gcp/outputs.tf b/terraform/aptos-node/gcp/outputs.tf index 6bee1c3500050..f44a9de4df365 100644 --- a/terraform/aptos-node/gcp/outputs.tf +++ b/terraform/aptos-node/gcp/outputs.tf @@ -9,3 +9,7 @@ output "gke_cluster_endpoint" { output "gke_cluster_ca_certificate" { value = google_container_cluster.aptos.master_auth[0].cluster_ca_certificate } + +output "gke_cluster_workload_identity_config" { + value = google_container_cluster.aptos.workload_identity_config +} diff --git a/terraform/aptos-node/gcp/security.tf b/terraform/aptos-node/gcp/security.tf index e2c74e54f273f..c230c9edca577 100644 --- a/terraform/aptos-node/gcp/security.tf +++ b/terraform/aptos-node/gcp/security.tf @@ -1,44 +1,20 @@ # Security-related resources -data "kubernetes_all_namespaces" "all" { - count = var.cluster_bootstrap ? 0 : 1 -} - locals { - kubernetes_master_version = substr(google_container_cluster.aptos.master_version, 0, 4) - baseline_pss_labels = { + # Enforce "privileged" PSS (i.e. allow everything), but warn about + # infractions of "baseline" profile + privileged_pss_labels = { "pod-security.kubernetes.io/audit" = "baseline" "pod-security.kubernetes.io/warn" = "baseline" "pod-security.kubernetes.io/enforce" = "privileged" } } -# FIXME: Remove after migration to K8s 1.25 -resource "kubernetes_role_binding" "disable-psp" { - for_each = toset(var.cluster_bootstrap ? [] : local.kubernetes_master_version <= "1.24" ? data.kubernetes_all_namespaces.all[0].namespaces : []) - metadata { - name = "privileged-psp" - namespace = each.value - } - - role_ref { - api_group = "rbac.authorization.k8s.io" - kind = "ClusterRole" - name = "gce:podsecuritypolicy:privileged" - } - - subject { - api_group = "rbac.authorization.k8s.io" - kind = "Group" - name = "system:serviceaccounts:${each.value}" - } -} - resource "kubernetes_labels" "pss-default" { api_version = "v1" kind = "Namespace" metadata { name = "default" } - labels = local.baseline_pss_labels + labels = local.privileged_pss_labels } diff --git a/terraform/aptos-node/gcp/variables.tf b/terraform/aptos-node/gcp/variables.tf index 81f73c42d1510..96b3911cc66d5 100644 --- a/terraform/aptos-node/gcp/variables.tf +++ b/terraform/aptos-node/gcp/variables.tf @@ -46,26 +46,6 @@ variable "image_tag" { default = "devnet" } -variable "zone_name" { - description = "Zone name of GCP Cloud DNS zone to create records in" - default = "" -} - -variable "zone_project" { - description = "GCP project which the DNS zone is in (if different)" - default = "" -} - -variable "record_name" { - description = "DNS record name to use ( is replaced with the TF workspace name)" - default = ".aptos" -} - -variable "create_dns_records" { - description = "Creates DNS records in var.zone_name that point to k8s service, as opposed to using external-dns or other means" - default = true -} - variable "helm_chart" { description = "Path to aptos-validator Helm chart file" default = "" @@ -171,8 +151,39 @@ variable "manage_via_tf" { default = true } -### Autoscaling +### DNS +variable "zone_name" { + description = "Zone name of GCP Cloud DNS zone to create records in" + default = "" +} + +variable "zone_project" { + description = "GCP project which the DNS zone is in (if different)" + default = "" +} + +variable "workspace_dns" { + description = "Include Terraform workspace name in DNS records" + default = true +} + +variable "record_name" { + description = "DNS record name to use ( is replaced with the TF workspace name)" + default = ".aptos" +} + +variable "create_dns_records" { + description = "Creates DNS records in var.zone_name that point to k8s service, as opposed to using external-dns or other means" + default = true +} + +variable "dns_ttl" { + description = "Time-to-Live for the Validator and Fullnode DNS records" + default = 300 +} + +### Autoscaling variable "gke_enable_node_autoprovisioning" { description = "Enable node autoprovisioning for GKE cluster. See https://cloud.google.com/kubernetes-engine/docs/how-to/node-auto-provisioning" diff --git a/terraform/aptos-node/gcp/versions.tf b/terraform/aptos-node/gcp/versions.tf index f88de6cbc2a7e..2b8786efb55aa 100644 --- a/terraform/aptos-node/gcp/versions.tf +++ b/terraform/aptos-node/gcp/versions.tf @@ -2,10 +2,12 @@ terraform { required_version = "~> 1.3.6" required_providers { google = { - source = "hashicorp/google" + source = "hashicorp/google" + version = "~> 4.54.0" } google-beta = { - source = "hashicorp/google-beta" + source = "hashicorp/google-beta" + version = "~> 4.54.0" } helm = { source = "hashicorp/helm" diff --git a/terraform/helm/aptos-node/values.yaml b/terraform/helm/aptos-node/values.yaml index da6cd16b84d4b..1dda86b09216e 100644 --- a/terraform/helm/aptos-node/values.yaml +++ b/terraform/helm/aptos-node/values.yaml @@ -16,7 +16,7 @@ numFullnodeGroups: 1 # -- Options for multicluster mode. This is *experimental only*. multicluster: - enabled: false + enabled: false targetClusters: ["cluster1", "cluster2", "cluster3"] # -- Specify validator and fullnode NodeConfigs via named ConfigMaps, rather than the generated ones from this chart. @@ -151,7 +151,7 @@ service: # -- Enable the REST API on the validator enableRestApi: true # -- Enable the metrics port on the validator - enableMetricsPort: true + enableMetricsPort: false fullnode: external: # -- The Kubernetes ServiceType to use for fullnodes' HAProxy @@ -167,7 +167,7 @@ service: # -- Enable the REST API on fullnodes enableRestApi: true # -- Enable the metrics port on fullnodes - enableMetricsPort: true + enableMetricsPort: false serviceAccount: # -- Specifies whether a service account should be created diff --git a/terraform/helm/testnet-addons/templates/ingress.yaml b/terraform/helm/testnet-addons/templates/ingress.yaml index 865cf19c0f0bc..5ae3b596ac921 100644 --- a/terraform/helm/testnet-addons/templates/ingress.yaml +++ b/terraform/helm/testnet-addons/templates/ingress.yaml @@ -5,15 +5,17 @@ metadata: labels: {{- include "testnet-addons.labels" . | nindent 4 }} annotations: + {{- if .Values.service.domain }} + external-dns.alpha.kubernetes.io/hostname: {{ .Values.service.domain }} + {{- end }} + # EKS annotations + {{- if eq .Values.cloud "EKS" }} kubernetes.io/ingress.class: alb alb.ingress.kubernetes.io/scheme: internet-facing alb.ingress.kubernetes.io/tags: {{ .Values.service.aws_tags | quote }} {{- if .Values.ingress.loadBalancerSourceRanges }} alb.ingress.kubernetes.io/inbound-cidrs: {{ join "," .Values.ingress.loadBalancerSourceRanges }} {{- end }} - {{- if .Values.service.domain }} - external-dns.alpha.kubernetes.io/hostname: {{ .Values.service.domain }} - {{- end }} {{- if .Values.ingress.acm_certificate }} alb.ingress.kubernetes.io/certificate-arn: {{ .Values.ingress.acm_certificate }} alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}]' @@ -27,6 +29,16 @@ metadata: alb.ingress.kubernetes.io/target-group-attributes: stickiness.enabled=true,stickiness.lb_cookie.duration_seconds={{ .Values.ingress.cookieDurationSeconds }} alb.ingress.kubernetes.io/target-type: ip {{- end }} + {{- end }} # "EKS" + # GKE annotations + {{- if eq .Values.cloud "GKE" }} + kubernetes.io/ingress.class: "gce" + # Allow HTTP but always return 301 because we have redirectToHttps enabled + kubernetes.io/ingress.allow-http: "true" + kubernetes.io/ingress.global-static-ip-name: {{ .Values.ingress.gcp_static_ip }} + ingress.gcp.kubernetes.io/pre-shared-cert: {{ .Values.ingress.gcp_certificate }} + networking.gke.io/v1beta1.FrontendConfig: {{ include "testnet-addons.fullname" . }}-api + {{- end }} # "GKE" spec: rules: {{- if .Values.service.domain }} @@ -64,3 +76,15 @@ spec: name: {{ include "testnet-addons.fullname" . }}-api port: number: 80 +--- +{{- if eq .Values.cloud "GKE" }} +apiVersion: networking.gke.io/v1beta1 +kind: FrontendConfig +metadata: + name: {{ include "testnet-addons.fullname" . }}-api + namespace: default +spec: + redirectToHttps: + enabled: true +{{- end }} +--- diff --git a/terraform/helm/testnet-addons/templates/service.yaml b/terraform/helm/testnet-addons/templates/service.yaml index aeb9028060907..74416c999ce53 100644 --- a/terraform/helm/testnet-addons/templates/service.yaml +++ b/terraform/helm/testnet-addons/templates/service.yaml @@ -6,7 +6,13 @@ metadata: labels: {{- include "testnet-addons.labels" . | nindent 4 }} annotations: + {{- if eq .Values.cloud "EKS" }} alb.ingress.kubernetes.io/healthcheck-path: /v1/-/healthy + {{- end }} + {{- if eq .Values.cloud "GKE" }} + cloud.google.com/backend-config: '{"default":"{{ include "testnet-addons.fullname" . }}-api"}' + cloud.google.com/neg: '{"ingress": true}' + {{- end }} spec: selector: app.kubernetes.io/part-of: aptos-node @@ -16,3 +22,22 @@ spec: targetPort: 8080 type: NodePort externalTrafficPolicy: Local +--- +{{- if eq .Values.cloud "GKE" }} +apiVersion: cloud.google.com/v1 +kind: BackendConfig +metadata: + name: {{ include "testnet-addons.fullname" . }}-api + namespace: default +spec: + healthCheck: + checkIntervalSec: 30 + timeoutSec: 5 + healthyThreshold: 1 + unhealthyThreshold: 2 + type: HTTP + requestPath: /v1/-/healthy + # container targetPort + port: 8080 +{{- end }} +--- diff --git a/terraform/helm/testnet-addons/values.yaml b/terraform/helm/testnet-addons/values.yaml index 7c9b15bfb8750..e9e5974ef483b 100644 --- a/terraform/helm/testnet-addons/values.yaml +++ b/terraform/helm/testnet-addons/values.yaml @@ -1,3 +1,6 @@ +# Cloud provider +cloud: EKS + # -- Default image tag to use for all aptos images imageTag: devnet @@ -50,7 +53,7 @@ load_test: # -- The fullnode groups to target fullnode: groups: - - name: fullnode + - name: fullnode config: # -- The number of fullnode groups to run traffic against numFullnodeGroups: @@ -80,6 +83,8 @@ service: ingress: # -- The ACM certificate to install on the ingress acm_certificate: + # -- The GCP certificate to install on the ingress + gcp_certificate: # -- The ARN of the WAF ACL to install on the ingress wafAclArn: # -- List of CIDRs to accept traffic from From 09359aa961e909699939783bd438e967ca381bdb Mon Sep 17 00:00:00 2001 From: Kevin <105028215+movekevin@users.noreply.github.com> Date: Mon, 5 Jun 2023 19:00:30 -0500 Subject: [PATCH 073/200] Update gas metering (#8526) * Add accurate resource group gas metering * Add accurate resource group gas metering * fix * add test * Correct feature version * change trait signature * Clear any resource cache after proloque * bump gas feature * add comment * fix trigger condition for build jobs * test loadtest * add improvement * Fix respawn session whatever that maybe --------- Co-authored-by: gerben Co-authored-by: geekflyer --- aptos-move/aptos-gas/src/gas_meter.rs | 4 +- aptos-move/aptos-vm/src/aptos_vm.rs | 35 +++++++--- aptos-move/aptos-vm/src/aptos_vm_impl.rs | 2 +- .../aptos-vm/src/block_executor/vm_wrapper.rs | 5 +- aptos-move/aptos-vm/src/data_cache.rs | 65 +++++++++++++------ .../aptos-vm/src/move_vm_ext/resolver.rs | 4 +- .../src/move_vm_ext/respawned_session.rs | 10 ++- .../aptos-vm/src/move_vm_ext/session.rs | 23 ++++--- .../async/move-async-vm/tests/testsuite.rs | 6 +- .../move/move-core/types/src/resolver.rs | 15 ++++- .../src/tests/bad_storage_tests.rs | 2 +- .../move/move-vm/runtime/src/data_cache.rs | 4 +- .../src/unit_tests/vm_arguments_tests.rs | 2 +- .../move/move-vm/test-utils/src/storage.rs | 14 ++-- .../src/sandbox/utils/on_disk_state_view.rs | 7 +- 15 files changed, 131 insertions(+), 67 deletions(-) diff --git a/aptos-move/aptos-gas/src/gas_meter.rs b/aptos-move/aptos-gas/src/gas_meter.rs index 4b249d34ab338..3851f84aef59e 100644 --- a/aptos-move/aptos-gas/src/gas_meter.rs +++ b/aptos-move/aptos-gas/src/gas_meter.rs @@ -33,6 +33,8 @@ use move_vm_types::{ use std::collections::BTreeMap; // Change log: +// - V9 +// - Accurate tracking of the cost of loading resource groups // - V8 // - Added BLS12-381 operations. // - V7 @@ -59,7 +61,7 @@ use std::collections::BTreeMap; // global operations. // - V1 // - TBA -pub const LATEST_GAS_FEATURE_VERSION: u64 = 8; +pub const LATEST_GAS_FEATURE_VERSION: u64 = 9; pub(crate) const EXECUTION_GAS_MULTIPLIER: u64 = 20; diff --git a/aptos-move/aptos-vm/src/aptos_vm.rs b/aptos-move/aptos-vm/src/aptos_vm.rs index a3a1a1298255a..0f8699434cfb5 100644 --- a/aptos-move/aptos-vm/src/aptos_vm.rs +++ b/aptos-move/aptos-vm/src/aptos_vm.rs @@ -9,7 +9,7 @@ use crate::{ aptos_vm_impl::{get_transaction_output, AptosVMImpl, AptosVMInternals}, block_executor::BlockAptosVM, counters::*, - data_cache::{AsMoveResolver, StorageAdapter}, + data_cache::StorageAdapter, errors::expect_only_successful_execution, move_vm_ext::{MoveResolverExt, RespawnedSession, SessionExt, SessionId}, sharded_block_executor::ShardedBlockExecutor, @@ -244,6 +244,14 @@ impl AptosVM { .1 } + pub fn as_move_resolver<'a, S: StateView>(&self, state_view: &'a S) -> StorageAdapter<'a, S> { + StorageAdapter::new_with_cached_config( + state_view, + self.0.get_gas_feature_version(), + self.0.get_features(), + ) + } + fn failed_transaction_cleanup_and_keep_vm_status( &self, error_code: VMStatus, @@ -1019,6 +1027,9 @@ impl AptosVM { // have been previously cached in the prologue. // // TODO(Gas): Do this in a better way in the future, perhaps without forcing the data cache to be flushed. + // By releasing resource group cache, we start with a fresh slate for resource group + // cost accounting. + resolver.release_resource_group_cache(); session = self.0.new_session(resolver, SessionId::txn(txn), true); } @@ -1137,8 +1148,7 @@ impl AptosVM { F: FnOnce(u64, AptosGasParameters, StorageGasParameters, Gas) -> Result, { // TODO(Gas): revisit this. - let resolver = StorageAdapter::new(state_view); - let vm = AptosVM::new(&resolver); + let vm = AptosVM::new(state_view); // TODO(Gas): avoid creating txn metadata twice. let balance = TransactionMetadata::new(txn).max_gas_amount(); @@ -1149,6 +1159,11 @@ impl AptosVM { balance, )?; + let resolver = StorageAdapter::new_with_cached_config( + state_view, + vm.0.get_gas_feature_version(), + vm.0.get_features(), + ); let (status, output) = vm.execute_user_transaction_impl(&resolver, txn, log_context, &mut gas_meter); @@ -1332,7 +1347,7 @@ impl AptosVM { // Try to simulate with aggregator enabled. let (vm_status, vm_output) = simulation_vm.simulate_signed_transaction( - &state_view.as_move_resolver(), + &simulation_vm.0.as_move_resolver(state_view), txn, &log_context, true, @@ -1349,7 +1364,7 @@ impl AptosVM { Err(_) => { // Conversion to TransactionOutput failed, re-simulate without aggregators. let (vm_status, vm_output) = simulation_vm.simulate_signed_transaction( - &state_view.as_move_resolver(), + &simulation_vm.0.as_move_resolver(state_view), txn, &log_context, false, @@ -1383,8 +1398,8 @@ impl AptosVM { vm.0.get_storage_gas_parameters(&log_context)?.clone(), gas_budget, ); - let resolver = &state_view.as_move_resolver(); - let mut session = vm.new_session(resolver, SessionId::Void, true); + let resolver = vm.as_move_resolver(state_view); + let mut session = vm.new_session(&resolver, SessionId::Void, true); let func_inst = session.load_function(&module_id, &func_name, &type_args)?; let metadata = vm.0.extract_module_metadata(&module_id); @@ -1557,11 +1572,11 @@ impl VMValidator for AptosVM { }, }; - let resolver = &state_view.as_move_resolver(); - let mut session = self.0.new_session(resolver, SessionId::txn(&txn), true); + let resolver = self.as_move_resolver(state_view); + let mut session = self.0.new_session(&resolver, SessionId::txn(&txn), true); let validation_result = self.validate_signature_checked_transaction( &mut session, - resolver, + &resolver, &txn, true, &log_context, diff --git a/aptos-move/aptos-vm/src/aptos_vm_impl.rs b/aptos-move/aptos-vm/src/aptos_vm_impl.rs index a8d75c2cc967b..c5006b4dbbb1a 100644 --- a/aptos-move/aptos-vm/src/aptos_vm_impl.rs +++ b/aptos-move/aptos-vm/src/aptos_vm_impl.rs @@ -163,7 +163,7 @@ impl AptosVMImpl { features, }; vm.version = Version::fetch_config(&storage); - vm.transaction_validation = Self::get_transaction_validation(&StorageAdapter::new(state)); + vm.transaction_validation = Self::get_transaction_validation(&storage); vm } diff --git a/aptos-move/aptos-vm/src/block_executor/vm_wrapper.rs b/aptos-move/aptos-vm/src/block_executor/vm_wrapper.rs index f87511d6a84da..97298ff64fe75 100644 --- a/aptos-move/aptos-vm/src/block_executor/vm_wrapper.rs +++ b/aptos-move/aptos-vm/src/block_executor/vm_wrapper.rs @@ -6,7 +6,6 @@ use crate::{ adapter_common::{PreprocessedTransaction, VMAdapter}, aptos_vm::AptosVM, block_executor::AptosTransactionOutput, - data_cache::{AsMoveResolver, StorageAdapter}, }; use aptos_block_executor::task::{ExecutionStatus, ExecutorTask}; use aptos_logger::{enabled, Level}; @@ -43,7 +42,7 @@ impl<'a, S: 'a + StateView + Sync> ExecutorTask for AptosExecutorTask<'a, S> { let _ = vm.load_module( &ModuleId::new(CORE_CODE_ADDRESS, ident_str!("account").to_owned()), - &StorageAdapter::new(argument), + &vm.as_move_resolver(argument), ); Self { @@ -66,7 +65,7 @@ impl<'a, S: 'a + StateView + Sync> ExecutorTask for AptosExecutorTask<'a, S> { match self .vm - .execute_single_transaction(txn, &view.as_move_resolver(), &log_context) + .execute_single_transaction(txn, &self.vm.as_move_resolver(view), &log_context) { Ok((vm_status, mut vm_output, sender)) => { if materialize_deltas { diff --git a/aptos-move/aptos-vm/src/data_cache.rs b/aptos-move/aptos-vm/src/data_cache.rs index b70b89300d127..9e6c0954e0bd2 100644 --- a/aptos-move/aptos-vm/src/data_cache.rs +++ b/aptos-move/aptos-vm/src/data_cache.rs @@ -21,7 +21,7 @@ use move_core_types::{ account_address::AccountAddress, language_storage::{ModuleId, StructTag}, metadata::Metadata, - resolver::{ModuleResolver, ResourceResolver}, + resolver::{resource_add_cost, ModuleResolver, ResourceResolver}, vm_status::StatusCode, }; use move_table_extension::{TableHandle, TableResolver}; @@ -42,16 +42,45 @@ pub(crate) fn get_resource_group_from_metadata( /// Adapter to convert a `StateView` into a `MoveResolverExt`. pub struct StorageAdapter<'a, S> { state_store: &'a S, + accurate_byte_count: bool, + max_binary_format_version: u32, resource_group_cache: RefCell>>>>, } impl<'a, S: StateView> StorageAdapter<'a, S> { + pub fn new_with_cached_config( + state_store: &'a S, + gas_feature_version: u64, + features: &Features, + ) -> Self { + let mut s = Self { + state_store, + accurate_byte_count: false, + max_binary_format_version: 0, + resource_group_cache: RefCell::new(BTreeMap::new()), + }; + if gas_feature_version >= 9 { + s.accurate_byte_count = true; + } + s.max_binary_format_version = get_max_binary_format_version(features, gas_feature_version); + s + } + pub fn new(state_store: &'a S) -> Self { - Self { + let mut s = Self { state_store, + accurate_byte_count: false, + max_binary_format_version: 0, resource_group_cache: RefCell::new(BTreeMap::new()), + }; + let (_, gas_feature_version) = gas_config(&s); + let features = Features::fetch_config(&s).unwrap_or_default(); + if gas_feature_version >= 9 { + s.accurate_byte_count = true; } + s.max_binary_format_version = get_max_binary_format_version(&features, gas_feature_version); + s } pub fn get(&self, access_path: AccessPath) -> PartialVMResult>> { @@ -65,7 +94,7 @@ impl<'a, S: StateView> StorageAdapter<'a, S> { address: &AccountAddress, struct_tag: &StructTag, metadata: &[Metadata], - ) -> Result>, VMError> { + ) -> Result, u64)>, VMError> { let resource_group = get_resource_group_from_metadata(struct_tag, metadata); if let Some(resource_group) = resource_group { let mut cache = self.resource_group_cache.borrow_mut(); @@ -73,10 +102,16 @@ impl<'a, S: StateView> StorageAdapter<'a, S> { if let Some(group_data) = cache.get_mut(&resource_group) { // This resource group is already cached for this address. So just return the // cached value. - return Ok(group_data.get(struct_tag).cloned()); + let buf = group_data.get(struct_tag).cloned(); + return Ok(resource_add_cost(buf, 0)); } let group_data = self.get_resource_group_data(address, &resource_group)?; if let Some(group_data) = group_data { + let len = if self.accurate_byte_count { + group_data.len() as u64 + } else { + 0 + }; let group_data: BTreeMap> = bcs::from_bytes(&group_data) .map_err(|_| { PartialVMError::new(StatusCode::UNKNOWN_INVARIANT_VIOLATION_ERROR) @@ -84,13 +119,14 @@ impl<'a, S: StateView> StorageAdapter<'a, S> { })?; let res = group_data.get(struct_tag).cloned(); cache.insert(resource_group, group_data); - Ok(res) + Ok(resource_add_cost(res, len)) } else { cache.insert(resource_group, BTreeMap::new()); Ok(None) } } else { - self.get_standard_resource(address, struct_tag) + let buf = self.get_standard_resource(address, struct_tag)?; + Ok(resource_add_cost(buf, 0)) } } } @@ -118,13 +154,8 @@ impl<'a, S: StateView> MoveResolverExt for StorageAdapter<'a, S> { fn release_resource_group_cache( &self, - address: &AccountAddress, - resource_group: &StructTag, - ) -> Option>> { - self.resource_group_cache - .borrow_mut() - .get_mut(address)? - .remove(resource_group) + ) -> BTreeMap>>> { + self.resource_group_cache.take() } } @@ -134,7 +165,7 @@ impl<'a, S: StateView> ResourceResolver for StorageAdapter<'a, S> { address: &AccountAddress, struct_tag: &StructTag, metadata: &[Metadata], - ) -> Result>, Error> { + ) -> anyhow::Result, u64)>> { Ok(self.get_any_resource(address, struct_tag, metadata)?) } } @@ -145,13 +176,9 @@ impl<'a, S: StateView> ModuleResolver for StorageAdapter<'a, S> { Ok(Some(bytes)) => bytes, _ => return vec![], }; - let (_, gas_feature_version) = gas_config(self); - let features = Features::fetch_config(self).unwrap_or_default(); - let max_binary_format_version = - get_max_binary_format_version(&features, gas_feature_version); let module = match CompiledModule::deserialize_with_max_version( &module_bytes, - max_binary_format_version, + self.max_binary_format_version, ) { Ok(module) => module, _ => return vec![], diff --git a/aptos-move/aptos-vm/src/move_vm_ext/resolver.rs b/aptos-move/aptos-vm/src/move_vm_ext/resolver.rs index 1081e9db0decd..f90654d6bc428 100644 --- a/aptos-move/aptos-vm/src/move_vm_ext/resolver.rs +++ b/aptos-move/aptos-vm/src/move_vm_ext/resolver.rs @@ -29,9 +29,7 @@ pub trait MoveResolverExt: fn release_resource_group_cache( &self, - address: &AccountAddress, - resource_group: &StructTag, - ) -> Option>>; + ) -> BTreeMap>>>; // Move to API does not belong here fn is_resource_group(&self, struct_tag: &StructTag) -> bool { diff --git a/aptos-move/aptos-vm/src/move_vm_ext/respawned_session.rs b/aptos-move/aptos-vm/src/move_vm_ext/respawned_session.rs index 31a0b34b22d01..7f901c03b4839 100644 --- a/aptos-move/aptos-vm/src/move_vm_ext/respawned_session.rs +++ b/aptos-move/aptos-vm/src/move_vm_ext/respawned_session.rs @@ -3,7 +3,7 @@ use crate::{ aptos_vm_impl::AptosVMImpl, - data_cache::{AsMoveResolver, StorageAdapter}, + data_cache::StorageAdapter, move_vm_ext::{SessionExt, SessionId}, }; use anyhow::{bail, Result}; @@ -44,7 +44,13 @@ impl<'r, 'l> RespawnedSession<'r, 'l> { Ok(RespawnedSessionBuilder { state_view, - resolver_builder: |state_view| state_view.as_move_resolver(), + resolver_builder: |state_view| { + StorageAdapter::new_with_cached_config( + state_view, + vm.get_gas_feature_version(), + vm.get_features(), + ) + }, session_builder: |resolver| Some(vm.new_session(resolver, session_id, true)), } .build()) diff --git a/aptos-move/aptos-vm/src/move_vm_ext/session.rs b/aptos-move/aptos-vm/src/move_vm_ext/session.rs index ec64ec725dbb2..63b748f68e458 100644 --- a/aptos-move/aptos-vm/src/move_vm_ext/session.rs +++ b/aptos-move/aptos-vm/src/move_vm_ext/session.rs @@ -38,6 +38,7 @@ use move_table_extension::{NativeTableContext, TableChangeSet}; use move_vm_runtime::{move_vm::MoveVM, session::Session}; use serde::{Deserialize, Serialize}; use std::{ + borrow::BorrowMut, collections::BTreeMap, ops::{Deref, DerefMut}, sync::Arc, @@ -199,19 +200,21 @@ impl<'r, 'l> SessionExt<'r, 'l> { let mut change_set_filtered = MoveChangeSet::new(); let mut resource_group_change_set = MoveChangeSet::new(); + let mut resource_group_cache = remote.release_resource_group_cache(); for (addr, account_changeset) in change_set.into_inner() { let mut resource_groups: BTreeMap = BTreeMap::new(); let mut resources_filtered = BTreeMap::new(); let (modules, resources) = account_changeset.into_inner(); for (struct_tag, blob_op) in resources { - let resource_group = runtime.with_module_metadata(&struct_tag.module_id(), |md| { - get_resource_group_from_metadata(&struct_tag, md) - }); + let resource_group_tag = runtime + .with_module_metadata(&struct_tag.module_id(), |md| { + get_resource_group_from_metadata(&struct_tag, md) + }); - if let Some(resource_group) = resource_group { + if let Some(resource_group_tag) = resource_group_tag { resource_groups - .entry(resource_group) + .entry(resource_group_tag) .or_insert_with(AccountChangeSet::new) .add_resource_op(struct_tag, blob_op) .map_err(|_| common_error())?; @@ -227,9 +230,11 @@ impl<'r, 'l> SessionExt<'r, 'l> { ) .map_err(|_| common_error())?; - for (resource_tag, resources) in resource_groups { - let mut source_data = remote - .release_resource_group_cache(&addr, &resource_tag) + for (resource_group_tag, resources) in resource_groups { + let mut source_data = resource_group_cache + .borrow_mut() + .get_mut(&addr) + .and_then(|t| t.remove(&resource_group_tag)) .unwrap_or_default(); let create = source_data.is_empty(); @@ -259,7 +264,7 @@ impl<'r, 'l> SessionExt<'r, 'l> { MoveStorageOp::Modify(bcs::to_bytes(&source_data).map_err(|_| common_error())?) }; resource_group_change_set - .add_resource_op(addr, resource_tag, op) + .add_resource_op(addr, resource_group_tag, op) .map_err(|_| common_error())?; } } diff --git a/third_party/move/extensions/async/move-async-vm/tests/testsuite.rs b/third_party/move/extensions/async/move-async-vm/tests/testsuite.rs index 705c4176b9f6e..46d8dde897456 100644 --- a/third_party/move/extensions/async/move-async-vm/tests/testsuite.rs +++ b/third_party/move/extensions/async/move-async-vm/tests/testsuite.rs @@ -23,7 +23,7 @@ use move_core_types::{ identifier::{IdentStr, Identifier}, language_storage::{ModuleId, StructTag}, metadata::Metadata, - resolver::{ModuleResolver, ResourceResolver}, + resolver::{resource_add_cost, ModuleResolver, ResourceResolver}, }; use move_prover_test_utils::{baseline_test::verify_or_update_baseline, extract_test_directives}; use move_vm_test_utils::gas_schedule::GasStatus; @@ -398,14 +398,14 @@ impl<'a> ResourceResolver for HarnessProxy<'a> { address: &AccountAddress, typ: &StructTag, _metadata: &[Metadata], - ) -> Result>, Error> { + ) -> anyhow::Result, u64)>> { let res = self .harness .resource_store .borrow() .get(&(*address, typ.clone())) .cloned(); - Ok(res) + Ok(resource_add_cost(res, 0)) } } diff --git a/third_party/move/move-core/types/src/resolver.rs b/third_party/move/move-core/types/src/resolver.rs index f61d82a23ae80..5b8e5f405be49 100644 --- a/third_party/move/move-core/types/src/resolver.rs +++ b/third_party/move/move-core/types/src/resolver.rs @@ -41,7 +41,14 @@ pub trait ResourceResolver { address: &AccountAddress, typ: &StructTag, metadata: &[Metadata], - ) -> Result>, Error>; + ) -> Result, u64)>, Error>; +} + +pub fn resource_add_cost(buf: Option>, extra: u64) -> Option<(Vec, u64)> { + buf.map(|b| { + let len = b.len() as u64 + extra; + (b, len) + }) } /// A persistent storage implementation that can resolve both resources and modules @@ -51,7 +58,9 @@ pub trait MoveResolver: ModuleResolver + ResourceResolver { address: &AccountAddress, typ: &StructTag, ) -> Result>, Error> { - self.get_resource_with_metadata(address, typ, &self.get_module_metadata(&typ.module_id())) + Ok(self + .get_resource_with_metadata(address, typ, &self.get_module_metadata(&typ.module_id()))? + .map(|(buf, _)| buf)) } } @@ -63,7 +72,7 @@ impl ResourceResolver for &T { address: &AccountAddress, tag: &StructTag, metadata: &[Metadata], - ) -> Result>, Error> { + ) -> Result, u64)>, Error> { (**self).get_resource_with_metadata(address, tag, metadata) } } diff --git a/third_party/move/move-vm/integration-tests/src/tests/bad_storage_tests.rs b/third_party/move/move-vm/integration-tests/src/tests/bad_storage_tests.rs index f73715b2869a1..69cc998a7275b 100644 --- a/third_party/move/move-vm/integration-tests/src/tests/bad_storage_tests.rs +++ b/third_party/move/move-vm/integration-tests/src/tests/bad_storage_tests.rs @@ -526,7 +526,7 @@ impl ResourceResolver for BogusStorage { _address: &AccountAddress, _tag: &StructTag, _metadata: &[Metadata], - ) -> Result>, anyhow::Error> { + ) -> anyhow::Result, u64)>> { Ok(Err( PartialVMError::new(self.bad_status_code).finish(Location::Undefined) )?) diff --git a/third_party/move/move-vm/runtime/src/data_cache.rs b/third_party/move/move-vm/runtime/src/data_cache.rs index f48f4b0406209..ad8e69c586b6c 100644 --- a/third_party/move/move-vm/runtime/src/data_cache.rs +++ b/third_party/move/move-vm/runtime/src/data_cache.rs @@ -193,8 +193,8 @@ impl<'r> TransactionDataCache<'r> { .remote .get_resource_with_metadata(&addr, &ty_tag, metadata) { - Ok(Some(blob)) => { - load_res = Some(Some(NumBytes::new(blob.len() as u64))); + Ok(Some((blob, bytes))) => { + load_res = Some(Some(NumBytes::new(bytes))); let val = match Value::simple_deserialize(&blob, &ty_layout) { Some(val) => val, None => { diff --git a/third_party/move/move-vm/runtime/src/unit_tests/vm_arguments_tests.rs b/third_party/move/move-vm/runtime/src/unit_tests/vm_arguments_tests.rs index 40e712d3a2cc8..0dea6cca8c0b1 100644 --- a/third_party/move/move-vm/runtime/src/unit_tests/vm_arguments_tests.rs +++ b/third_party/move/move-vm/runtime/src/unit_tests/vm_arguments_tests.rs @@ -265,7 +265,7 @@ impl ResourceResolver for RemoteStore { _address: &AccountAddress, _tag: &StructTag, _metadata: &[Metadata], - ) -> Result>, anyhow::Error> { + ) -> anyhow::Result, u64)>> { Ok(None) } } diff --git a/third_party/move/move-vm/test-utils/src/storage.rs b/third_party/move/move-vm/test-utils/src/storage.rs index 6df6246ab41e6..5f596e097ae2e 100644 --- a/third_party/move/move-vm/test-utils/src/storage.rs +++ b/third_party/move/move-vm/test-utils/src/storage.rs @@ -9,7 +9,7 @@ use move_core_types::{ identifier::Identifier, language_storage::{ModuleId, StructTag}, metadata::Metadata, - resolver::{ModuleResolver, MoveResolver, ResourceResolver}, + resolver::{resource_add_cost, ModuleResolver, MoveResolver, ResourceResolver}, }; #[cfg(feature = "table-extension")] use move_table_extension::{TableChangeSet, TableHandle, TableResolver}; @@ -44,7 +44,7 @@ impl ResourceResolver for BlankStorage { _address: &AccountAddress, _tag: &StructTag, _metadata: &[Metadata], - ) -> Result>> { + ) -> Result, u64)>> { Ok(None) } } @@ -90,10 +90,11 @@ impl<'a, 'b, S: ResourceResolver> ResourceResolver for DeltaStorage<'a, 'b, S> { address: &AccountAddress, tag: &StructTag, metadata: &[Metadata], - ) -> Result>, Error> { + ) -> Result, u64)>> { if let Some(account_storage) = self.delta.accounts().get(address) { if let Some(blob_opt) = account_storage.resources().get(tag) { - return Ok(blob_opt.clone().ok()); + let buf = blob_opt.clone().ok(); + return Ok(resource_add_cost(buf, 0)); } } @@ -303,9 +304,10 @@ impl ResourceResolver for InMemoryStorage { address: &AccountAddress, tag: &StructTag, _metadata: &[Metadata], - ) -> Result>, Error> { + ) -> Result, u64)>> { if let Some(account_storage) = self.accounts.get(address) { - return Ok(account_storage.resources.get(tag).cloned()); + let buf = account_storage.resources.get(tag).cloned(); + return Ok(resource_add_cost(buf, 0)); } Ok(None) } diff --git a/third_party/move/tools/move-cli/src/sandbox/utils/on_disk_state_view.rs b/third_party/move/tools/move-cli/src/sandbox/utils/on_disk_state_view.rs index fb1a85de9472d..04489f2f8254d 100644 --- a/third_party/move/tools/move-cli/src/sandbox/utils/on_disk_state_view.rs +++ b/third_party/move/tools/move-cli/src/sandbox/utils/on_disk_state_view.rs @@ -17,7 +17,7 @@ use move_core_types::{ language_storage::{ModuleId, StructTag, TypeTag}, metadata::Metadata, parser, - resolver::{ModuleResolver, ResourceResolver}, + resolver::{resource_add_cost, ModuleResolver, ResourceResolver}, }; use move_disassembler::disassembler::Disassembler; use move_ir_types::location::Spanned; @@ -418,8 +418,9 @@ impl ResourceResolver for OnDiskStateView { address: &AccountAddress, struct_tag: &StructTag, _metadata: &[Metadata], - ) -> Result>, anyhow::Error> { - self.get_resource_bytes(*address, struct_tag.clone()) + ) -> Result, u64)>> { + let buf = self.get_resource_bytes(*address, struct_tag.clone())?; + Ok(resource_add_cost(buf, 0)) } } From 41ecc62611a7074b4e150ad6cf5b9f7cbfbac817 Mon Sep 17 00:00:00 2001 From: Maayan Date: Tue, 6 Jun 2023 19:03:08 +0300 Subject: [PATCH 074/200] [TS SDK] make indexerUrl as an optional param (#8502) * make indexerUrl as an optional param * update changelog --- ecosystem/typescript/sdk/CHANGELOG.md | 1 + ecosystem/typescript/sdk/src/utils/api-endpoints.ts | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/ecosystem/typescript/sdk/CHANGELOG.md b/ecosystem/typescript/sdk/CHANGELOG.md index 3752a10f73bea..0251e58bc3902 100644 --- a/ecosystem/typescript/sdk/CHANGELOG.md +++ b/ecosystem/typescript/sdk/CHANGELOG.md @@ -6,6 +6,7 @@ All notable changes to the Aptos Node SDK will be captured in this file. This ch - Add `x-aptos-client` header to `IndexerClient` requests - Add `standardizeAddress` static function to `AccountAddress` class to standardizes an address to the format "0x" followed by 64 lowercase hexadecimal digits. +- Change `indexerUrl` param on `Provider` class to an optional parameter ## 1.9.1 (2023-05-24) diff --git a/ecosystem/typescript/sdk/src/utils/api-endpoints.ts b/ecosystem/typescript/sdk/src/utils/api-endpoints.ts index 7645b82783f60..dcb0c1e06d618 100644 --- a/ecosystem/typescript/sdk/src/utils/api-endpoints.ts +++ b/ecosystem/typescript/sdk/src/utils/api-endpoints.ts @@ -18,5 +18,5 @@ export enum Network { export interface CustomEndpoints { fullnodeUrl: string; - indexerUrl: string; + indexerUrl?: string; } From 17dbf16fe2078de469a7be53a240914eed2a006f Mon Sep 17 00:00:00 2001 From: Gerardo Di Giacomo <19227040+gedigi@users.noreply.github.com> Date: Tue, 6 Jun 2023 11:39:34 -0700 Subject: [PATCH 075/200] Fix docker-update-images workflow --- scripts/update_docker_images.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/scripts/update_docker_images.py b/scripts/update_docker_images.py index ad55a3f304ec8..89602778c851a 100755 --- a/scripts/update_docker_images.py +++ b/scripts/update_docker_images.py @@ -9,14 +9,14 @@ OS = "linux" IMAGES = { - "debian-base": "debian:bullseye", - "rust-base": "rust:1.66.1-bullseye", + "debian": "debian:bullseye", + "rust": "rust:1.66.1-bullseye", } def update() -> int: script_dir = os.path.dirname(os.path.realpath(__file__)) - dockerfile_path = os.path.join(script_dir, "..", "docker", "rust-all.Dockerfile") + dockerfile_path = os.path.join(script_dir, "..", "docker", "builder", "docker-bake-rust-all.hcl") update_exists = False @@ -24,7 +24,7 @@ def update() -> int: manifest = None digest = None current_digest = None - regex = f"FROM [\S]+ AS {base_image}" + regex = f"{base_image} = \"docker-image://{image_name}.*\"" print(f"Update {image_name}") manifest_inspect = subprocess.check_output(["docker", "manifest", "inspect", image_name]) @@ -48,8 +48,8 @@ def update() -> int: dockerfile_content = f.read() for line in dockerfile_content.splitlines(): - if re.match(regex, line): - current_digest = line.split()[1].split("@")[1] + if re.search(regex, line): + current_digest = line.split("@")[1].split("\"")[0] break if current_digest == None: @@ -61,7 +61,7 @@ def update() -> int: continue print(f"Found update for {image_name}: {current_digest} -> {digest}") - dockerfile_content = re.sub(regex, f"FROM {image_name}@{digest} AS {base_image}", dockerfile_content) + dockerfile_content = re.sub(regex, f"{base_image} = \"docker-image://{image_name}@{digest}\"", dockerfile_content) with open(dockerfile_path, "w") as f: f.write(dockerfile_content) From e3c9a87f04641ba6da2eed8475a4435a3442284e Mon Sep 17 00:00:00 2001 From: Kevin <105028215+movekevin@users.noreply.github.com> Date: Tue, 6 Jun 2023 14:16:52 -0500 Subject: [PATCH 076/200] Update release builder to use the correct reconfigure function (#8536) --- .../src/components/feature_flags.rs | 12 ++--- .../aptos-framework/doc/reconfiguration.md | 50 ------------------- .../sources/reconfiguration.move | 6 --- .../sources/reconfiguration.spec.move | 17 ------- 4 files changed, 3 insertions(+), 82 deletions(-) diff --git a/aptos-move/aptos-release-builder/src/components/feature_flags.rs b/aptos-move/aptos-release-builder/src/components/feature_flags.rs index ced7ff6cc6903..0dbc07b984529 100644 --- a/aptos-move/aptos-release-builder/src/components/feature_flags.rs +++ b/aptos-move/aptos-release-builder/src/components/feature_flags.rs @@ -91,7 +91,7 @@ pub fn generate_feature_upgrade_proposal( &writer, is_testnet, next_execution_hash.clone(), - &["std::features", "aptos_framework::reconfiguration"], + &["std::features"], |writer| { emit!(writer, "let enabled_blob: vector = "); generate_features_blob(writer, &enabled); @@ -106,19 +106,13 @@ pub fn generate_feature_upgrade_proposal( writer, "features::change_feature_flags(framework_signer, enabled_blob, disabled_blob);" ); - emitln!( - writer, - "reconfiguration::reconfigure_with_signer(framework_signer);" - ); + emitln!(writer, "aptos_governance::reconfigure(framework_signer);"); } else { emitln!( writer, "features::change_feature_flags(&framework_signer, enabled_blob, disabled_blob);" ); - emitln!( - writer, - "reconfiguration::reconfigure_with_signer(&framework_signer);" - ); + emitln!(writer, "aptos_governance::reconfigure(&framework_signer);"); } }, ); diff --git a/aptos-move/framework/aptos-framework/doc/reconfiguration.md b/aptos-move/framework/aptos-framework/doc/reconfiguration.md index 82cc29779f9cf..42e7249c37903 100644 --- a/aptos-move/framework/aptos-framework/doc/reconfiguration.md +++ b/aptos-move/framework/aptos-framework/doc/reconfiguration.md @@ -15,7 +15,6 @@ to synchronize configuration changes for the validators. - [Function `disable_reconfiguration`](#0x1_reconfiguration_disable_reconfiguration) - [Function `enable_reconfiguration`](#0x1_reconfiguration_enable_reconfiguration) - [Function `reconfiguration_enabled`](#0x1_reconfiguration_reconfiguration_enabled) -- [Function `reconfigure_with_signer`](#0x1_reconfiguration_reconfigure_with_signer) - [Function `reconfigure`](#0x1_reconfiguration_reconfigure) - [Function `last_reconfiguration_time`](#0x1_reconfiguration_last_reconfiguration_time) - [Function `current_epoch`](#0x1_reconfiguration_current_epoch) @@ -24,7 +23,6 @@ to synchronize configuration changes for the validators. - [Function `initialize`](#@Specification_1_initialize) - [Function `disable_reconfiguration`](#@Specification_1_disable_reconfiguration) - [Function `enable_reconfiguration`](#@Specification_1_enable_reconfiguration) - - [Function `reconfigure_with_signer`](#@Specification_1_reconfigure_with_signer) - [Function `reconfigure`](#@Specification_1_reconfigure) - [Function `last_reconfiguration_time`](#@Specification_1_last_reconfiguration_time) - [Function `current_epoch`](#@Specification_1_current_epoch) @@ -316,32 +314,6 @@ This function should only be used for offline WriteSet generation purpose and sh - - - - -## Function `reconfigure_with_signer` - -Signal validators to start using new configuration. Must be called from aptos_framework signer. - - -
public fun reconfigure_with_signer(aptos_framework: &signer)
-
- - - -
-Implementation - - -
public fun reconfigure_with_signer(aptos_framework: &signer) acquires Configuration {
-    system_addresses::assert_aptos_framework(aptos_framework);
-    reconfigure();
-}
-
- - -
@@ -593,28 +565,6 @@ Make sure the caller is admin and check the resource DisableReconfiguration. - - -### Function `reconfigure_with_signer` - - -
public fun reconfigure_with_signer(aptos_framework: &signer)
-
- - - - -
pragma verify_duration_estimate = 120;
-requires exists<stake::ValidatorFees>(@aptos_framework);
-requires exists<CoinInfo<AptosCoin>>(@aptos_framework);
-include transaction_fee::RequiresCollectedFeesPerValueLeqBlockAptosSupply;
-include AbortsIfNotAptosFramework;
-include staking_config::StakingRewardsConfigRequirement;
-aborts_if false;
-
- - - ### Function `reconfigure` diff --git a/aptos-move/framework/aptos-framework/sources/reconfiguration.move b/aptos-move/framework/aptos-framework/sources/reconfiguration.move index 92812d1c56545..deec0364228c8 100644 --- a/aptos-move/framework/aptos-framework/sources/reconfiguration.move +++ b/aptos-move/framework/aptos-framework/sources/reconfiguration.move @@ -92,12 +92,6 @@ module aptos_framework::reconfiguration { !exists(@aptos_framework) } - /// Signal validators to start using new configuration. Must be called from aptos_framework signer. - public fun reconfigure_with_signer(aptos_framework: &signer) acquires Configuration { - system_addresses::assert_aptos_framework(aptos_framework); - reconfigure(); - } - /// Signal validators to start using new configuration. Must be called from friend config modules. public(friend) fun reconfigure() acquires Configuration { // Do not do anything if genesis has not finished. diff --git a/aptos-move/framework/aptos-framework/sources/reconfiguration.spec.move b/aptos-move/framework/aptos-framework/sources/reconfiguration.spec.move index 9b0440e5f1708..8336c7cc0a823 100644 --- a/aptos-move/framework/aptos-framework/sources/reconfiguration.spec.move +++ b/aptos-move/framework/aptos-framework/sources/reconfiguration.spec.move @@ -61,23 +61,6 @@ spec aptos_framework::reconfiguration { aborts_if !exists(@aptos_framework); } - spec reconfigure_with_signer { - use aptos_framework::coin::CoinInfo; - use aptos_framework::aptos_coin::AptosCoin; - use aptos_framework::transaction_fee; - use aptos_framework::staking_config; - - pragma verify_duration_estimate = 120; // TODO: set because of timeout (property proved) - - requires exists(@aptos_framework); - requires exists>(@aptos_framework); - - include transaction_fee::RequiresCollectedFeesPerValueLeqBlockAptosSupply; - include AbortsIfNotAptosFramework; - include staking_config::StakingRewardsConfigRequirement; - aborts_if false; - } - spec reconfigure { use aptos_framework::coin::CoinInfo; use aptos_framework::aptos_coin::AptosCoin; From 416211f8ddec2f5bf12829c5a398726100457813 Mon Sep 17 00:00:00 2001 From: Gerardo Di Giacomo <19227040+gedigi@users.noreply.github.com> Date: Tue, 6 Jun 2023 12:17:53 -0700 Subject: [PATCH 077/200] Update Docker images (#8493) * Update Docker images * fix trigger condition for build jobs --------- Co-authored-by: gedigi Co-authored-by: geekflyer --- docker/builder/docker-bake-rust-all.hcl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docker/builder/docker-bake-rust-all.hcl b/docker/builder/docker-bake-rust-all.hcl index faa47cd481eb5..115dd2e5eaa12 100644 --- a/docker/builder/docker-bake-rust-all.hcl +++ b/docker/builder/docker-bake-rust-all.hcl @@ -68,7 +68,7 @@ group "forge-images" { target "debian-base" { dockerfile = "docker/builder/debian-base.Dockerfile" contexts = { - debian = "docker-image://debian:bullseye-20230502@sha256:32888a3c745e38e72a5f49161afc7bb52a263b8f5ea1b3b4a6af537678f29491" + debian = "docker-image://debian:bullseye@sha256:1bf0e24813ee8306c3fba1fe074793eb91c15ee580b61fff7f3f41662bc0031d" } } From f4ef764d7c44b1c870bdeb8d72643e37005175ba Mon Sep 17 00:00:00 2001 From: Maayan Date: Tue, 6 Jun 2023 23:08:07 +0300 Subject: [PATCH 078/200] [TS SDK] Add query to fetch all collections that an account has tokens for (#8498) * add query to get all collections that an account has tokens for * use token standard param in query condition * update changelog * address feedback --- ecosystem/typescript/sdk/CHANGELOG.md | 2 + .../sdk/src/indexer/generated/operations.ts | 14 +- .../sdk/src/indexer/generated/queries.ts | 35 +- .../sdk/src/indexer/generated/types.ts | 1018 ++++++++++++++++- .../getCollectionsWithOwnedTokens.graphql | 26 + .../indexer/queries/getOwnedTokens.graphql | 8 +- .../getTokenOwnedFromCollection.graphql | 12 +- .../typescript/sdk/src/providers/indexer.ts | 75 +- .../sdk/src/tests/e2e/indexer.test.ts | 25 + 9 files changed, 1172 insertions(+), 43 deletions(-) create mode 100644 ecosystem/typescript/sdk/src/indexer/queries/getCollectionsWithOwnedTokens.graphql diff --git a/ecosystem/typescript/sdk/CHANGELOG.md b/ecosystem/typescript/sdk/CHANGELOG.md index 0251e58bc3902..151f0b5be3108 100644 --- a/ecosystem/typescript/sdk/CHANGELOG.md +++ b/ecosystem/typescript/sdk/CHANGELOG.md @@ -7,6 +7,8 @@ All notable changes to the Aptos Node SDK will be captured in this file. This ch - Add `x-aptos-client` header to `IndexerClient` requests - Add `standardizeAddress` static function to `AccountAddress` class to standardizes an address to the format "0x" followed by 64 lowercase hexadecimal digits. - Change `indexerUrl` param on `Provider` class to an optional parameter +- Add `getCollectionsWithOwnedTokens` query to fetch all collections that an account has tokens for +- Support `tokenStandard` param in `getOwnedTokens` and `getTokenOwnedFromCollectionAddress` queries ## 1.9.1 (2023-05-24) diff --git a/ecosystem/typescript/sdk/src/indexer/generated/operations.ts b/ecosystem/typescript/sdk/src/indexer/generated/operations.ts index 63fa1aeb5585e..0b8b583328459 100644 --- a/ecosystem/typescript/sdk/src/indexer/generated/operations.ts +++ b/ecosystem/typescript/sdk/src/indexer/generated/operations.ts @@ -56,6 +56,15 @@ export type GetCollectionDataQueryVariables = Types.Exact<{ export type GetCollectionDataQuery = { __typename?: 'query_root', current_collections_v2: Array<{ __typename?: 'current_collections_v2', collection_id: string, token_standard: string, collection_name: string, creator_address: string, current_supply: any, description: string, uri: string }> }; +export type GetCollectionsWithOwnedTokensQueryVariables = Types.Exact<{ + where_condition: Types.Current_Collection_Ownership_V2_View_Bool_Exp; + offset?: Types.InputMaybe; + limit?: Types.InputMaybe; +}>; + + +export type GetCollectionsWithOwnedTokensQuery = { __typename?: 'query_root', current_collection_ownership_v2_view: Array<{ __typename?: 'current_collection_ownership_v2_view', distinct_tokens?: any | null, last_transaction_version?: any | null, current_collection?: { __typename?: 'current_collections_v2', creator_address: string, collection_name: string, token_standard: string, collection_id: string, description: string, table_handle_v1?: string | null, uri: string, total_minted_v2?: any | null, max_supply?: any | null } | null }> }; + export type GetDelegatedStakingActivitiesQueryVariables = Types.Exact<{ delegatorAddress?: Types.InputMaybe; poolAddress?: Types.InputMaybe; @@ -77,7 +86,7 @@ export type GetNumberOfDelegatorsQueryVariables = Types.Exact<{ export type GetNumberOfDelegatorsQuery = { __typename?: 'query_root', num_active_delegator_per_pool: Array<{ __typename?: 'num_active_delegator_per_pool', num_active_delegator?: any | null }> }; export type GetOwnedTokensQueryVariables = Types.Exact<{ - address: Types.Scalars['String']; + where_condition: Types.Current_Token_Ownerships_V2_Bool_Exp; offset?: Types.InputMaybe; limit?: Types.InputMaybe; }>; @@ -109,8 +118,7 @@ export type GetTokenDataQueryVariables = Types.Exact<{ export type GetTokenDataQuery = { __typename?: 'query_root', current_token_datas: Array<{ __typename?: 'current_token_datas', token_data_id_hash: string, name: string, collection_name: string, creator_address: string, default_properties: any, largest_property_version: any, maximum: any, metadata_uri: string, payee_address: string, royalty_points_denominator: any, royalty_points_numerator: any, supply: any }> }; export type GetTokenOwnedFromCollectionQueryVariables = Types.Exact<{ - collection_id: Types.Scalars['String']; - owner_address: Types.Scalars['String']; + where_condition: Types.Current_Token_Ownerships_V2_Bool_Exp; offset?: Types.InputMaybe; limit?: Types.InputMaybe; }>; diff --git a/ecosystem/typescript/sdk/src/indexer/generated/queries.ts b/ecosystem/typescript/sdk/src/indexer/generated/queries.ts index 33d71de4a5184..cfea440ee9244 100644 --- a/ecosystem/typescript/sdk/src/indexer/generated/queries.ts +++ b/ecosystem/typescript/sdk/src/indexer/generated/queries.ts @@ -150,6 +150,30 @@ export const GetCollectionData = ` } } `; +export const GetCollectionsWithOwnedTokens = ` + query getCollectionsWithOwnedTokens($where_condition: current_collection_ownership_v2_view_bool_exp!, $offset: Int, $limit: Int) { + current_collection_ownership_v2_view( + where: $where_condition + order_by: {last_transaction_version: desc} + offset: $offset + limit: $limit + ) { + current_collection { + creator_address + collection_name + token_standard + collection_id + description + table_handle_v1 + uri + total_minted_v2 + max_supply + } + distinct_tokens + last_transaction_version + } +} + `; export const GetDelegatedStakingActivities = ` query getDelegatedStakingActivities($delegatorAddress: String, $poolAddress: String) { delegated_staking_activities( @@ -182,9 +206,9 @@ export const GetNumberOfDelegators = ` } `; export const GetOwnedTokens = ` - query getOwnedTokens($address: String!, $offset: Int, $limit: Int) { + query getOwnedTokens($where_condition: current_token_ownerships_v2_bool_exp!, $offset: Int, $limit: Int) { current_token_ownerships_v2( - where: {owner_address: {_eq: $address}, amount: {_gt: 0}} + where: $where_condition offset: $offset limit: $limit ) { @@ -244,9 +268,9 @@ export const GetTokenData = ` } `; export const GetTokenOwnedFromCollection = ` - query getTokenOwnedFromCollection($collection_id: String!, $owner_address: String!, $offset: Int, $limit: Int) { + query getTokenOwnedFromCollection($where_condition: current_token_ownerships_v2_bool_exp!, $offset: Int, $limit: Int) { current_token_ownerships_v2( - where: {owner_address: {_eq: $owner_address}, current_token_data: {collection_id: {_eq: $collection_id}}, amount: {_gt: 0}} + where: $where_condition offset: $offset limit: $limit ) { @@ -308,6 +332,9 @@ export function getSdk(client: GraphQLClient, withWrapper: SdkFunctionWrapper = getCollectionData(variables: Types.GetCollectionDataQueryVariables, requestHeaders?: Dom.RequestInit["headers"]): Promise { return withWrapper((wrappedRequestHeaders) => client.request(GetCollectionData, variables, {...requestHeaders, ...wrappedRequestHeaders}), 'getCollectionData', 'query'); }, + getCollectionsWithOwnedTokens(variables: Types.GetCollectionsWithOwnedTokensQueryVariables, requestHeaders?: Dom.RequestInit["headers"]): Promise { + return withWrapper((wrappedRequestHeaders) => client.request(GetCollectionsWithOwnedTokens, variables, {...requestHeaders, ...wrappedRequestHeaders}), 'getCollectionsWithOwnedTokens', 'query'); + }, getDelegatedStakingActivities(variables?: Types.GetDelegatedStakingActivitiesQueryVariables, requestHeaders?: Dom.RequestInit["headers"]): Promise { return withWrapper((wrappedRequestHeaders) => client.request(GetDelegatedStakingActivities, variables, {...requestHeaders, ...wrappedRequestHeaders}), 'getDelegatedStakingActivities', 'query'); }, diff --git a/ecosystem/typescript/sdk/src/indexer/generated/types.ts b/ecosystem/typescript/sdk/src/indexer/generated/types.ts index dea693afaa9fc..51460bc8c49fc 100644 --- a/ecosystem/typescript/sdk/src/indexer/generated/types.ts +++ b/ecosystem/typescript/sdk/src/indexer/generated/types.ts @@ -75,11 +75,66 @@ export type String_Comparison_Exp = { _similar?: InputMaybe; }; +/** columns and relationships of "address_events_summary" */ +export type Address_Events_Summary = { + __typename?: 'address_events_summary'; + account_address?: Maybe; + /** An object relationship */ + block_metadata?: Maybe; + min_block_height?: Maybe; + num_distinct_versions?: Maybe; +}; + +/** Boolean expression to filter rows from the table "address_events_summary". All fields are combined with a logical 'AND'. */ +export type Address_Events_Summary_Bool_Exp = { + _and?: InputMaybe>; + _not?: InputMaybe; + _or?: InputMaybe>; + account_address?: InputMaybe; + block_metadata?: InputMaybe; + min_block_height?: InputMaybe; + num_distinct_versions?: InputMaybe; +}; + +/** Ordering options when selecting data from "address_events_summary". */ +export type Address_Events_Summary_Order_By = { + account_address?: InputMaybe; + block_metadata?: InputMaybe; + min_block_height?: InputMaybe; + num_distinct_versions?: InputMaybe; +}; + +/** select columns of table "address_events_summary" */ +export enum Address_Events_Summary_Select_Column { + /** column name */ + AccountAddress = 'account_address', + /** column name */ + MinBlockHeight = 'min_block_height', + /** column name */ + NumDistinctVersions = 'num_distinct_versions' +} + +/** Streaming cursor of the table "address_events_summary" */ +export type Address_Events_Summary_Stream_Cursor_Input = { + /** Stream column input with initial value */ + initial_value: Address_Events_Summary_Stream_Cursor_Value_Input; + /** cursor ordering */ + ordering?: InputMaybe; +}; + +/** Initial value of the column from where the streaming should start */ +export type Address_Events_Summary_Stream_Cursor_Value_Input = { + account_address?: InputMaybe; + min_block_height?: InputMaybe; + num_distinct_versions?: InputMaybe; +}; + /** columns and relationships of "address_version_from_events" */ export type Address_Version_From_Events = { __typename?: 'address_version_from_events'; account_address?: Maybe; coin_activities: Array; + coin_activities_aggregate: Coin_Activities_Aggregate; token_activities: Array; token_activities_aggregate: Token_Activities_Aggregate; transaction_version?: Maybe; @@ -96,6 +151,16 @@ export type Address_Version_From_EventsCoin_ActivitiesArgs = { }; +/** columns and relationships of "address_version_from_events" */ +export type Address_Version_From_EventsCoin_Activities_AggregateArgs = { + distinct_on?: InputMaybe>; + limit?: InputMaybe; + offset?: InputMaybe; + order_by?: InputMaybe>; + where?: InputMaybe; +}; + + /** columns and relationships of "address_version_from_events" */ export type Address_Version_From_EventsToken_ActivitiesArgs = { distinct_on?: InputMaybe>; @@ -115,6 +180,42 @@ export type Address_Version_From_EventsToken_Activities_AggregateArgs = { where?: InputMaybe; }; +/** aggregated selection of "address_version_from_events" */ +export type Address_Version_From_Events_Aggregate = { + __typename?: 'address_version_from_events_aggregate'; + aggregate?: Maybe; + nodes: Array; +}; + +/** aggregate fields of "address_version_from_events" */ +export type Address_Version_From_Events_Aggregate_Fields = { + __typename?: 'address_version_from_events_aggregate_fields'; + avg?: Maybe; + count: Scalars['Int']; + max?: Maybe; + min?: Maybe; + stddev?: Maybe; + stddev_pop?: Maybe; + stddev_samp?: Maybe; + sum?: Maybe; + var_pop?: Maybe; + var_samp?: Maybe; + variance?: Maybe; +}; + + +/** aggregate fields of "address_version_from_events" */ +export type Address_Version_From_Events_Aggregate_FieldsCountArgs = { + columns?: InputMaybe>; + distinct?: InputMaybe; +}; + +/** aggregate avg on columns */ +export type Address_Version_From_Events_Avg_Fields = { + __typename?: 'address_version_from_events_avg_fields'; + transaction_version?: Maybe; +}; + /** Boolean expression to filter rows from the table "address_version_from_events". All fields are combined with a logical 'AND'. */ export type Address_Version_From_Events_Bool_Exp = { _and?: InputMaybe>; @@ -124,6 +225,20 @@ export type Address_Version_From_Events_Bool_Exp = { transaction_version?: InputMaybe; }; +/** aggregate max on columns */ +export type Address_Version_From_Events_Max_Fields = { + __typename?: 'address_version_from_events_max_fields'; + account_address?: Maybe; + transaction_version?: Maybe; +}; + +/** aggregate min on columns */ +export type Address_Version_From_Events_Min_Fields = { + __typename?: 'address_version_from_events_min_fields'; + account_address?: Maybe; + transaction_version?: Maybe; +}; + /** Ordering options when selecting data from "address_version_from_events". */ export type Address_Version_From_Events_Order_By = { account_address?: InputMaybe; @@ -138,6 +253,24 @@ export enum Address_Version_From_Events_Select_Column { TransactionVersion = 'transaction_version' } +/** aggregate stddev on columns */ +export type Address_Version_From_Events_Stddev_Fields = { + __typename?: 'address_version_from_events_stddev_fields'; + transaction_version?: Maybe; +}; + +/** aggregate stddev_pop on columns */ +export type Address_Version_From_Events_Stddev_Pop_Fields = { + __typename?: 'address_version_from_events_stddev_pop_fields'; + transaction_version?: Maybe; +}; + +/** aggregate stddev_samp on columns */ +export type Address_Version_From_Events_Stddev_Samp_Fields = { + __typename?: 'address_version_from_events_stddev_samp_fields'; + transaction_version?: Maybe; +}; + /** Streaming cursor of the table "address_version_from_events" */ export type Address_Version_From_Events_Stream_Cursor_Input = { /** Stream column input with initial value */ @@ -152,6 +285,30 @@ export type Address_Version_From_Events_Stream_Cursor_Value_Input = { transaction_version?: InputMaybe; }; +/** aggregate sum on columns */ +export type Address_Version_From_Events_Sum_Fields = { + __typename?: 'address_version_from_events_sum_fields'; + transaction_version?: Maybe; +}; + +/** aggregate var_pop on columns */ +export type Address_Version_From_Events_Var_Pop_Fields = { + __typename?: 'address_version_from_events_var_pop_fields'; + transaction_version?: Maybe; +}; + +/** aggregate var_samp on columns */ +export type Address_Version_From_Events_Var_Samp_Fields = { + __typename?: 'address_version_from_events_var_samp_fields'; + transaction_version?: Maybe; +}; + +/** aggregate variance on columns */ +export type Address_Version_From_Events_Variance_Fields = { + __typename?: 'address_version_from_events_variance_fields'; + transaction_version?: Maybe; +}; + /** columns and relationships of "address_version_from_move_resources" */ export type Address_Version_From_Move_Resources = { __typename?: 'address_version_from_move_resources'; @@ -209,6 +366,104 @@ export type Bigint_Comparison_Exp = { _nin?: InputMaybe>; }; +/** columns and relationships of "block_metadata_transactions" */ +export type Block_Metadata_Transactions = { + __typename?: 'block_metadata_transactions'; + block_height: Scalars['bigint']; + epoch: Scalars['bigint']; + failed_proposer_indices: Scalars['jsonb']; + id: Scalars['String']; + previous_block_votes_bitvec: Scalars['jsonb']; + proposer: Scalars['String']; + round: Scalars['bigint']; + timestamp: Scalars['timestamp']; + version: Scalars['bigint']; +}; + + +/** columns and relationships of "block_metadata_transactions" */ +export type Block_Metadata_TransactionsFailed_Proposer_IndicesArgs = { + path?: InputMaybe; +}; + + +/** columns and relationships of "block_metadata_transactions" */ +export type Block_Metadata_TransactionsPrevious_Block_Votes_BitvecArgs = { + path?: InputMaybe; +}; + +/** Boolean expression to filter rows from the table "block_metadata_transactions". All fields are combined with a logical 'AND'. */ +export type Block_Metadata_Transactions_Bool_Exp = { + _and?: InputMaybe>; + _not?: InputMaybe; + _or?: InputMaybe>; + block_height?: InputMaybe; + epoch?: InputMaybe; + failed_proposer_indices?: InputMaybe; + id?: InputMaybe; + previous_block_votes_bitvec?: InputMaybe; + proposer?: InputMaybe; + round?: InputMaybe; + timestamp?: InputMaybe; + version?: InputMaybe; +}; + +/** Ordering options when selecting data from "block_metadata_transactions". */ +export type Block_Metadata_Transactions_Order_By = { + block_height?: InputMaybe; + epoch?: InputMaybe; + failed_proposer_indices?: InputMaybe; + id?: InputMaybe; + previous_block_votes_bitvec?: InputMaybe; + proposer?: InputMaybe; + round?: InputMaybe; + timestamp?: InputMaybe; + version?: InputMaybe; +}; + +/** select columns of table "block_metadata_transactions" */ +export enum Block_Metadata_Transactions_Select_Column { + /** column name */ + BlockHeight = 'block_height', + /** column name */ + Epoch = 'epoch', + /** column name */ + FailedProposerIndices = 'failed_proposer_indices', + /** column name */ + Id = 'id', + /** column name */ + PreviousBlockVotesBitvec = 'previous_block_votes_bitvec', + /** column name */ + Proposer = 'proposer', + /** column name */ + Round = 'round', + /** column name */ + Timestamp = 'timestamp', + /** column name */ + Version = 'version' +} + +/** Streaming cursor of the table "block_metadata_transactions" */ +export type Block_Metadata_Transactions_Stream_Cursor_Input = { + /** Stream column input with initial value */ + initial_value: Block_Metadata_Transactions_Stream_Cursor_Value_Input; + /** cursor ordering */ + ordering?: InputMaybe; +}; + +/** Initial value of the column from where the streaming should start */ +export type Block_Metadata_Transactions_Stream_Cursor_Value_Input = { + block_height?: InputMaybe; + epoch?: InputMaybe; + failed_proposer_indices?: InputMaybe; + id?: InputMaybe; + previous_block_votes_bitvec?: InputMaybe; + proposer?: InputMaybe; + round?: InputMaybe; + timestamp?: InputMaybe; + version?: InputMaybe; +}; + /** columns and relationships of "coin_activities" */ export type Coin_Activities = { __typename?: 'coin_activities'; @@ -242,6 +497,47 @@ export type Coin_ActivitiesAptos_NamesArgs = { where?: InputMaybe; }; +/** aggregated selection of "coin_activities" */ +export type Coin_Activities_Aggregate = { + __typename?: 'coin_activities_aggregate'; + aggregate?: Maybe; + nodes: Array; +}; + +/** aggregate fields of "coin_activities" */ +export type Coin_Activities_Aggregate_Fields = { + __typename?: 'coin_activities_aggregate_fields'; + avg?: Maybe; + count: Scalars['Int']; + max?: Maybe; + min?: Maybe; + stddev?: Maybe; + stddev_pop?: Maybe; + stddev_samp?: Maybe; + sum?: Maybe; + var_pop?: Maybe; + var_samp?: Maybe; + variance?: Maybe; +}; + + +/** aggregate fields of "coin_activities" */ +export type Coin_Activities_Aggregate_FieldsCountArgs = { + columns?: InputMaybe>; + distinct?: InputMaybe; +}; + +/** aggregate avg on columns */ +export type Coin_Activities_Avg_Fields = { + __typename?: 'coin_activities_avg_fields'; + amount?: Maybe; + block_height?: Maybe; + event_creation_number?: Maybe; + event_index?: Maybe; + event_sequence_number?: Maybe; + transaction_version?: Maybe; +}; + /** Boolean expression to filter rows from the table "coin_activities". All fields are combined with a logical 'AND'. */ export type Coin_Activities_Bool_Exp = { _and?: InputMaybe>; @@ -265,6 +561,40 @@ export type Coin_Activities_Bool_Exp = { transaction_version?: InputMaybe; }; +/** aggregate max on columns */ +export type Coin_Activities_Max_Fields = { + __typename?: 'coin_activities_max_fields'; + activity_type?: Maybe; + amount?: Maybe; + block_height?: Maybe; + coin_type?: Maybe; + entry_function_id_str?: Maybe; + event_account_address?: Maybe; + event_creation_number?: Maybe; + event_index?: Maybe; + event_sequence_number?: Maybe; + owner_address?: Maybe; + transaction_timestamp?: Maybe; + transaction_version?: Maybe; +}; + +/** aggregate min on columns */ +export type Coin_Activities_Min_Fields = { + __typename?: 'coin_activities_min_fields'; + activity_type?: Maybe; + amount?: Maybe; + block_height?: Maybe; + coin_type?: Maybe; + entry_function_id_str?: Maybe; + event_account_address?: Maybe; + event_creation_number?: Maybe; + event_index?: Maybe; + event_sequence_number?: Maybe; + owner_address?: Maybe; + transaction_timestamp?: Maybe; + transaction_version?: Maybe; +}; + /** Ordering options when selecting data from "coin_activities". */ export type Coin_Activities_Order_By = { activity_type?: InputMaybe; @@ -317,6 +647,39 @@ export enum Coin_Activities_Select_Column { TransactionVersion = 'transaction_version' } +/** aggregate stddev on columns */ +export type Coin_Activities_Stddev_Fields = { + __typename?: 'coin_activities_stddev_fields'; + amount?: Maybe; + block_height?: Maybe; + event_creation_number?: Maybe; + event_index?: Maybe; + event_sequence_number?: Maybe; + transaction_version?: Maybe; +}; + +/** aggregate stddev_pop on columns */ +export type Coin_Activities_Stddev_Pop_Fields = { + __typename?: 'coin_activities_stddev_pop_fields'; + amount?: Maybe; + block_height?: Maybe; + event_creation_number?: Maybe; + event_index?: Maybe; + event_sequence_number?: Maybe; + transaction_version?: Maybe; +}; + +/** aggregate stddev_samp on columns */ +export type Coin_Activities_Stddev_Samp_Fields = { + __typename?: 'coin_activities_stddev_samp_fields'; + amount?: Maybe; + block_height?: Maybe; + event_creation_number?: Maybe; + event_index?: Maybe; + event_sequence_number?: Maybe; + transaction_version?: Maybe; +}; + /** Streaming cursor of the table "coin_activities" */ export type Coin_Activities_Stream_Cursor_Input = { /** Stream column input with initial value */ @@ -343,6 +706,50 @@ export type Coin_Activities_Stream_Cursor_Value_Input = { transaction_version?: InputMaybe; }; +/** aggregate sum on columns */ +export type Coin_Activities_Sum_Fields = { + __typename?: 'coin_activities_sum_fields'; + amount?: Maybe; + block_height?: Maybe; + event_creation_number?: Maybe; + event_index?: Maybe; + event_sequence_number?: Maybe; + transaction_version?: Maybe; +}; + +/** aggregate var_pop on columns */ +export type Coin_Activities_Var_Pop_Fields = { + __typename?: 'coin_activities_var_pop_fields'; + amount?: Maybe; + block_height?: Maybe; + event_creation_number?: Maybe; + event_index?: Maybe; + event_sequence_number?: Maybe; + transaction_version?: Maybe; +}; + +/** aggregate var_samp on columns */ +export type Coin_Activities_Var_Samp_Fields = { + __typename?: 'coin_activities_var_samp_fields'; + amount?: Maybe; + block_height?: Maybe; + event_creation_number?: Maybe; + event_index?: Maybe; + event_sequence_number?: Maybe; + transaction_version?: Maybe; +}; + +/** aggregate variance on columns */ +export type Coin_Activities_Variance_Fields = { + __typename?: 'coin_activities_variance_fields'; + amount?: Maybe; + block_height?: Maybe; + event_creation_number?: Maybe; + event_index?: Maybe; + event_sequence_number?: Maybe; + transaction_version?: Maybe; +}; + /** columns and relationships of "coin_balances" */ export type Coin_Balances = { __typename?: 'coin_balances'; @@ -999,29 +1406,193 @@ export enum Current_Collection_Datas_Select_Column { UriMutable = 'uri_mutable' } -/** Streaming cursor of the table "current_collection_datas" */ -export type Current_Collection_Datas_Stream_Cursor_Input = { +/** Streaming cursor of the table "current_collection_datas" */ +export type Current_Collection_Datas_Stream_Cursor_Input = { + /** Stream column input with initial value */ + initial_value: Current_Collection_Datas_Stream_Cursor_Value_Input; + /** cursor ordering */ + ordering?: InputMaybe; +}; + +/** Initial value of the column from where the streaming should start */ +export type Current_Collection_Datas_Stream_Cursor_Value_Input = { + collection_data_id_hash?: InputMaybe; + collection_name?: InputMaybe; + creator_address?: InputMaybe; + description?: InputMaybe; + description_mutable?: InputMaybe; + last_transaction_timestamp?: InputMaybe; + last_transaction_version?: InputMaybe; + maximum?: InputMaybe; + maximum_mutable?: InputMaybe; + metadata_uri?: InputMaybe; + supply?: InputMaybe; + table_handle?: InputMaybe; + uri_mutable?: InputMaybe; +}; + +/** columns and relationships of "current_collection_ownership_v2_view" */ +export type Current_Collection_Ownership_V2_View = { + __typename?: 'current_collection_ownership_v2_view'; + collection_id?: Maybe; + /** An object relationship */ + current_collection?: Maybe; + distinct_tokens?: Maybe; + last_transaction_version?: Maybe; + owner_address?: Maybe; +}; + +/** aggregated selection of "current_collection_ownership_v2_view" */ +export type Current_Collection_Ownership_V2_View_Aggregate = { + __typename?: 'current_collection_ownership_v2_view_aggregate'; + aggregate?: Maybe; + nodes: Array; +}; + +/** aggregate fields of "current_collection_ownership_v2_view" */ +export type Current_Collection_Ownership_V2_View_Aggregate_Fields = { + __typename?: 'current_collection_ownership_v2_view_aggregate_fields'; + avg?: Maybe; + count: Scalars['Int']; + max?: Maybe; + min?: Maybe; + stddev?: Maybe; + stddev_pop?: Maybe; + stddev_samp?: Maybe; + sum?: Maybe; + var_pop?: Maybe; + var_samp?: Maybe; + variance?: Maybe; +}; + + +/** aggregate fields of "current_collection_ownership_v2_view" */ +export type Current_Collection_Ownership_V2_View_Aggregate_FieldsCountArgs = { + columns?: InputMaybe>; + distinct?: InputMaybe; +}; + +/** aggregate avg on columns */ +export type Current_Collection_Ownership_V2_View_Avg_Fields = { + __typename?: 'current_collection_ownership_v2_view_avg_fields'; + distinct_tokens?: Maybe; + last_transaction_version?: Maybe; +}; + +/** Boolean expression to filter rows from the table "current_collection_ownership_v2_view". All fields are combined with a logical 'AND'. */ +export type Current_Collection_Ownership_V2_View_Bool_Exp = { + _and?: InputMaybe>; + _not?: InputMaybe; + _or?: InputMaybe>; + collection_id?: InputMaybe; + current_collection?: InputMaybe; + distinct_tokens?: InputMaybe; + last_transaction_version?: InputMaybe; + owner_address?: InputMaybe; +}; + +/** aggregate max on columns */ +export type Current_Collection_Ownership_V2_View_Max_Fields = { + __typename?: 'current_collection_ownership_v2_view_max_fields'; + collection_id?: Maybe; + distinct_tokens?: Maybe; + last_transaction_version?: Maybe; + owner_address?: Maybe; +}; + +/** aggregate min on columns */ +export type Current_Collection_Ownership_V2_View_Min_Fields = { + __typename?: 'current_collection_ownership_v2_view_min_fields'; + collection_id?: Maybe; + distinct_tokens?: Maybe; + last_transaction_version?: Maybe; + owner_address?: Maybe; +}; + +/** Ordering options when selecting data from "current_collection_ownership_v2_view". */ +export type Current_Collection_Ownership_V2_View_Order_By = { + collection_id?: InputMaybe; + current_collection?: InputMaybe; + distinct_tokens?: InputMaybe; + last_transaction_version?: InputMaybe; + owner_address?: InputMaybe; +}; + +/** select columns of table "current_collection_ownership_v2_view" */ +export enum Current_Collection_Ownership_V2_View_Select_Column { + /** column name */ + CollectionId = 'collection_id', + /** column name */ + DistinctTokens = 'distinct_tokens', + /** column name */ + LastTransactionVersion = 'last_transaction_version', + /** column name */ + OwnerAddress = 'owner_address' +} + +/** aggregate stddev on columns */ +export type Current_Collection_Ownership_V2_View_Stddev_Fields = { + __typename?: 'current_collection_ownership_v2_view_stddev_fields'; + distinct_tokens?: Maybe; + last_transaction_version?: Maybe; +}; + +/** aggregate stddev_pop on columns */ +export type Current_Collection_Ownership_V2_View_Stddev_Pop_Fields = { + __typename?: 'current_collection_ownership_v2_view_stddev_pop_fields'; + distinct_tokens?: Maybe; + last_transaction_version?: Maybe; +}; + +/** aggregate stddev_samp on columns */ +export type Current_Collection_Ownership_V2_View_Stddev_Samp_Fields = { + __typename?: 'current_collection_ownership_v2_view_stddev_samp_fields'; + distinct_tokens?: Maybe; + last_transaction_version?: Maybe; +}; + +/** Streaming cursor of the table "current_collection_ownership_v2_view" */ +export type Current_Collection_Ownership_V2_View_Stream_Cursor_Input = { /** Stream column input with initial value */ - initial_value: Current_Collection_Datas_Stream_Cursor_Value_Input; + initial_value: Current_Collection_Ownership_V2_View_Stream_Cursor_Value_Input; /** cursor ordering */ ordering?: InputMaybe; }; /** Initial value of the column from where the streaming should start */ -export type Current_Collection_Datas_Stream_Cursor_Value_Input = { - collection_data_id_hash?: InputMaybe; - collection_name?: InputMaybe; - creator_address?: InputMaybe; - description?: InputMaybe; - description_mutable?: InputMaybe; - last_transaction_timestamp?: InputMaybe; +export type Current_Collection_Ownership_V2_View_Stream_Cursor_Value_Input = { + collection_id?: InputMaybe; + distinct_tokens?: InputMaybe; last_transaction_version?: InputMaybe; - maximum?: InputMaybe; - maximum_mutable?: InputMaybe; - metadata_uri?: InputMaybe; - supply?: InputMaybe; - table_handle?: InputMaybe; - uri_mutable?: InputMaybe; + owner_address?: InputMaybe; +}; + +/** aggregate sum on columns */ +export type Current_Collection_Ownership_V2_View_Sum_Fields = { + __typename?: 'current_collection_ownership_v2_view_sum_fields'; + distinct_tokens?: Maybe; + last_transaction_version?: Maybe; +}; + +/** aggregate var_pop on columns */ +export type Current_Collection_Ownership_V2_View_Var_Pop_Fields = { + __typename?: 'current_collection_ownership_v2_view_var_pop_fields'; + distinct_tokens?: Maybe; + last_transaction_version?: Maybe; +}; + +/** aggregate var_samp on columns */ +export type Current_Collection_Ownership_V2_View_Var_Samp_Fields = { + __typename?: 'current_collection_ownership_v2_view_var_samp_fields'; + distinct_tokens?: Maybe; + last_transaction_version?: Maybe; +}; + +/** aggregate variance on columns */ +export type Current_Collection_Ownership_V2_View_Variance_Fields = { + __typename?: 'current_collection_ownership_v2_view_variance_fields'; + distinct_tokens?: Maybe; + last_transaction_version?: Maybe; }; /** columns and relationships of "current_collection_ownership_view" */ @@ -1208,11 +1779,86 @@ export type Current_Collections_V2_Stream_Cursor_Value_Input = { uri?: InputMaybe; }; +/** columns and relationships of "current_delegated_staking_pool_balances" */ +export type Current_Delegated_Staking_Pool_Balances = { + __typename?: 'current_delegated_staking_pool_balances'; + active_table_handle: Scalars['String']; + inactive_table_handle: Scalars['String']; + last_transaction_version: Scalars['bigint']; + operator_commission_percentage: Scalars['numeric']; + staking_pool_address: Scalars['String']; + total_coins: Scalars['numeric']; + total_shares: Scalars['numeric']; +}; + +/** Boolean expression to filter rows from the table "current_delegated_staking_pool_balances". All fields are combined with a logical 'AND'. */ +export type Current_Delegated_Staking_Pool_Balances_Bool_Exp = { + _and?: InputMaybe>; + _not?: InputMaybe; + _or?: InputMaybe>; + active_table_handle?: InputMaybe; + inactive_table_handle?: InputMaybe; + last_transaction_version?: InputMaybe; + operator_commission_percentage?: InputMaybe; + staking_pool_address?: InputMaybe; + total_coins?: InputMaybe; + total_shares?: InputMaybe; +}; + +/** Ordering options when selecting data from "current_delegated_staking_pool_balances". */ +export type Current_Delegated_Staking_Pool_Balances_Order_By = { + active_table_handle?: InputMaybe; + inactive_table_handle?: InputMaybe; + last_transaction_version?: InputMaybe; + operator_commission_percentage?: InputMaybe; + staking_pool_address?: InputMaybe; + total_coins?: InputMaybe; + total_shares?: InputMaybe; +}; + +/** select columns of table "current_delegated_staking_pool_balances" */ +export enum Current_Delegated_Staking_Pool_Balances_Select_Column { + /** column name */ + ActiveTableHandle = 'active_table_handle', + /** column name */ + InactiveTableHandle = 'inactive_table_handle', + /** column name */ + LastTransactionVersion = 'last_transaction_version', + /** column name */ + OperatorCommissionPercentage = 'operator_commission_percentage', + /** column name */ + StakingPoolAddress = 'staking_pool_address', + /** column name */ + TotalCoins = 'total_coins', + /** column name */ + TotalShares = 'total_shares' +} + +/** Streaming cursor of the table "current_delegated_staking_pool_balances" */ +export type Current_Delegated_Staking_Pool_Balances_Stream_Cursor_Input = { + /** Stream column input with initial value */ + initial_value: Current_Delegated_Staking_Pool_Balances_Stream_Cursor_Value_Input; + /** cursor ordering */ + ordering?: InputMaybe; +}; + +/** Initial value of the column from where the streaming should start */ +export type Current_Delegated_Staking_Pool_Balances_Stream_Cursor_Value_Input = { + active_table_handle?: InputMaybe; + inactive_table_handle?: InputMaybe; + last_transaction_version?: InputMaybe; + operator_commission_percentage?: InputMaybe; + staking_pool_address?: InputMaybe; + total_coins?: InputMaybe; + total_shares?: InputMaybe; +}; + /** columns and relationships of "current_delegator_balances" */ export type Current_Delegator_Balances = { __typename?: 'current_delegator_balances'; delegator_address: Scalars['String']; last_transaction_version: Scalars['bigint']; + parent_table_handle: Scalars['String']; pool_address: Scalars['String']; pool_type: Scalars['String']; shares: Scalars['numeric']; @@ -1226,6 +1872,7 @@ export type Current_Delegator_Balances_Bool_Exp = { _or?: InputMaybe>; delegator_address?: InputMaybe; last_transaction_version?: InputMaybe; + parent_table_handle?: InputMaybe; pool_address?: InputMaybe; pool_type?: InputMaybe; shares?: InputMaybe; @@ -1236,6 +1883,7 @@ export type Current_Delegator_Balances_Bool_Exp = { export type Current_Delegator_Balances_Order_By = { delegator_address?: InputMaybe; last_transaction_version?: InputMaybe; + parent_table_handle?: InputMaybe; pool_address?: InputMaybe; pool_type?: InputMaybe; shares?: InputMaybe; @@ -1249,6 +1897,8 @@ export enum Current_Delegator_Balances_Select_Column { /** column name */ LastTransactionVersion = 'last_transaction_version', /** column name */ + ParentTableHandle = 'parent_table_handle', + /** column name */ PoolAddress = 'pool_address', /** column name */ PoolType = 'pool_type', @@ -1270,6 +1920,7 @@ export type Current_Delegator_Balances_Stream_Cursor_Input = { export type Current_Delegator_Balances_Stream_Cursor_Value_Input = { delegator_address?: InputMaybe; last_transaction_version?: InputMaybe; + parent_table_handle?: InputMaybe; pool_address?: InputMaybe; pool_type?: InputMaybe; shares?: InputMaybe; @@ -1281,10 +1932,22 @@ export type Current_Staking_Pool_Voter = { __typename?: 'current_staking_pool_voter'; last_transaction_version: Scalars['bigint']; operator_address: Scalars['String']; + /** An array relationship */ + operator_aptos_name: Array; staking_pool_address: Scalars['String']; voter_address: Scalars['String']; }; + +/** columns and relationships of "current_staking_pool_voter" */ +export type Current_Staking_Pool_VoterOperator_Aptos_NameArgs = { + distinct_on?: InputMaybe>; + limit?: InputMaybe; + offset?: InputMaybe; + order_by?: InputMaybe>; + where?: InputMaybe; +}; + /** Boolean expression to filter rows from the table "current_staking_pool_voter". All fields are combined with a logical 'AND'. */ export type Current_Staking_Pool_Voter_Bool_Exp = { _and?: InputMaybe>; @@ -1292,6 +1955,7 @@ export type Current_Staking_Pool_Voter_Bool_Exp = { _or?: InputMaybe>; last_transaction_version?: InputMaybe; operator_address?: InputMaybe; + operator_aptos_name?: InputMaybe; staking_pool_address?: InputMaybe; voter_address?: InputMaybe; }; @@ -1300,6 +1964,7 @@ export type Current_Staking_Pool_Voter_Bool_Exp = { export type Current_Staking_Pool_Voter_Order_By = { last_transaction_version?: InputMaybe; operator_address?: InputMaybe; + operator_aptos_name_aggregate?: InputMaybe; staking_pool_address?: InputMaybe; voter_address?: InputMaybe; }; @@ -2296,12 +2961,17 @@ export type Current_Token_Pending_Claims = { __typename?: 'current_token_pending_claims'; amount: Scalars['numeric']; collection_data_id_hash: Scalars['String']; + collection_id: Scalars['String']; collection_name: Scalars['String']; creator_address: Scalars['String']; /** An object relationship */ current_collection_data?: Maybe; /** An object relationship */ + current_collection_v2?: Maybe; + /** An object relationship */ current_token_data?: Maybe; + /** An object relationship */ + current_token_data_v2?: Maybe; from_address: Scalars['String']; last_transaction_timestamp: Scalars['timestamp']; last_transaction_version: Scalars['bigint']; @@ -2311,6 +2981,7 @@ export type Current_Token_Pending_Claims = { to_address: Scalars['String']; /** An object relationship */ token?: Maybe; + token_data_id: Scalars['String']; token_data_id_hash: Scalars['String']; }; @@ -2321,10 +2992,13 @@ export type Current_Token_Pending_Claims_Bool_Exp = { _or?: InputMaybe>; amount?: InputMaybe; collection_data_id_hash?: InputMaybe; + collection_id?: InputMaybe; collection_name?: InputMaybe; creator_address?: InputMaybe; current_collection_data?: InputMaybe; + current_collection_v2?: InputMaybe; current_token_data?: InputMaybe; + current_token_data_v2?: InputMaybe; from_address?: InputMaybe; last_transaction_timestamp?: InputMaybe; last_transaction_version?: InputMaybe; @@ -2333,6 +3007,7 @@ export type Current_Token_Pending_Claims_Bool_Exp = { table_handle?: InputMaybe; to_address?: InputMaybe; token?: InputMaybe; + token_data_id?: InputMaybe; token_data_id_hash?: InputMaybe; }; @@ -2340,10 +3015,13 @@ export type Current_Token_Pending_Claims_Bool_Exp = { export type Current_Token_Pending_Claims_Order_By = { amount?: InputMaybe; collection_data_id_hash?: InputMaybe; + collection_id?: InputMaybe; collection_name?: InputMaybe; creator_address?: InputMaybe; current_collection_data?: InputMaybe; + current_collection_v2?: InputMaybe; current_token_data?: InputMaybe; + current_token_data_v2?: InputMaybe; from_address?: InputMaybe; last_transaction_timestamp?: InputMaybe; last_transaction_version?: InputMaybe; @@ -2352,6 +3030,7 @@ export type Current_Token_Pending_Claims_Order_By = { table_handle?: InputMaybe; to_address?: InputMaybe; token?: InputMaybe; + token_data_id?: InputMaybe; token_data_id_hash?: InputMaybe; }; @@ -2362,6 +3041,8 @@ export enum Current_Token_Pending_Claims_Select_Column { /** column name */ CollectionDataIdHash = 'collection_data_id_hash', /** column name */ + CollectionId = 'collection_id', + /** column name */ CollectionName = 'collection_name', /** column name */ CreatorAddress = 'creator_address', @@ -2380,6 +3061,8 @@ export enum Current_Token_Pending_Claims_Select_Column { /** column name */ ToAddress = 'to_address', /** column name */ + TokenDataId = 'token_data_id', + /** column name */ TokenDataIdHash = 'token_data_id_hash' } @@ -2395,6 +3078,7 @@ export type Current_Token_Pending_Claims_Stream_Cursor_Input = { export type Current_Token_Pending_Claims_Stream_Cursor_Value_Input = { amount?: InputMaybe; collection_data_id_hash?: InputMaybe; + collection_id?: InputMaybe; collection_name?: InputMaybe; creator_address?: InputMaybe; from_address?: InputMaybe; @@ -2404,6 +3088,7 @@ export type Current_Token_Pending_Claims_Stream_Cursor_Value_Input = { property_version?: InputMaybe; table_handle?: InputMaybe; to_address?: InputMaybe; + token_data_id?: InputMaybe; token_data_id_hash?: InputMaybe; }; @@ -2531,6 +3216,58 @@ export type Delegated_Staking_Pools_Stream_Cursor_Value_Input = { staking_pool_address?: InputMaybe; }; +/** columns and relationships of "delegator_distinct_pool" */ +export type Delegator_Distinct_Pool = { + __typename?: 'delegator_distinct_pool'; + /** An object relationship */ + current_pool_balance?: Maybe; + delegator_address?: Maybe; + pool_address?: Maybe; + /** An object relationship */ + staking_pool_metadata?: Maybe; +}; + +/** Boolean expression to filter rows from the table "delegator_distinct_pool". All fields are combined with a logical 'AND'. */ +export type Delegator_Distinct_Pool_Bool_Exp = { + _and?: InputMaybe>; + _not?: InputMaybe; + _or?: InputMaybe>; + current_pool_balance?: InputMaybe; + delegator_address?: InputMaybe; + pool_address?: InputMaybe; + staking_pool_metadata?: InputMaybe; +}; + +/** Ordering options when selecting data from "delegator_distinct_pool". */ +export type Delegator_Distinct_Pool_Order_By = { + current_pool_balance?: InputMaybe; + delegator_address?: InputMaybe; + pool_address?: InputMaybe; + staking_pool_metadata?: InputMaybe; +}; + +/** select columns of table "delegator_distinct_pool" */ +export enum Delegator_Distinct_Pool_Select_Column { + /** column name */ + DelegatorAddress = 'delegator_address', + /** column name */ + PoolAddress = 'pool_address' +} + +/** Streaming cursor of the table "delegator_distinct_pool" */ +export type Delegator_Distinct_Pool_Stream_Cursor_Input = { + /** Stream column input with initial value */ + initial_value: Delegator_Distinct_Pool_Stream_Cursor_Value_Input; + /** cursor ordering */ + ordering?: InputMaybe; +}; + +/** Initial value of the column from where the streaming should start */ +export type Delegator_Distinct_Pool_Stream_Cursor_Value_Input = { + delegator_address?: InputMaybe; + pool_address?: InputMaybe; +}; + /** columns and relationships of "events" */ export type Events = { __typename?: 'events'; @@ -3172,11 +3909,20 @@ export type Proposal_Votes_Variance_Fields = { export type Query_Root = { __typename?: 'query_root'; + /** fetch data from the table: "address_events_summary" */ + address_events_summary: Array; /** fetch data from the table: "address_version_from_events" */ address_version_from_events: Array; + /** fetch aggregated fields from the table: "address_version_from_events" */ + address_version_from_events_aggregate: Address_Version_From_Events_Aggregate; /** fetch data from the table: "address_version_from_move_resources" */ address_version_from_move_resources: Array; + /** fetch data from the table: "block_metadata_transactions" */ + block_metadata_transactions: Array; + /** fetch data from the table: "block_metadata_transactions" using primary key columns */ + block_metadata_transactions_by_pk?: Maybe; coin_activities: Array; + coin_activities_aggregate: Coin_Activities_Aggregate; /** fetch data from the table: "coin_activities" using primary key columns */ coin_activities_by_pk?: Maybe; /** fetch data from the table: "coin_balances" */ @@ -3207,12 +3953,20 @@ export type Query_Root = { current_collection_datas: Array; /** fetch data from the table: "current_collection_datas" using primary key columns */ current_collection_datas_by_pk?: Maybe; + /** fetch data from the table: "current_collection_ownership_v2_view" */ + current_collection_ownership_v2_view: Array; + /** fetch aggregated fields from the table: "current_collection_ownership_v2_view" */ + current_collection_ownership_v2_view_aggregate: Current_Collection_Ownership_V2_View_Aggregate; /** fetch data from the table: "current_collection_ownership_view" */ current_collection_ownership_view: Array; /** fetch data from the table: "current_collections_v2" */ current_collections_v2: Array; /** fetch data from the table: "current_collections_v2" using primary key columns */ current_collections_v2_by_pk?: Maybe; + /** fetch data from the table: "current_delegated_staking_pool_balances" */ + current_delegated_staking_pool_balances: Array; + /** fetch data from the table: "current_delegated_staking_pool_balances" using primary key columns */ + current_delegated_staking_pool_balances_by_pk?: Maybe; /** fetch data from the table: "current_delegator_balances" */ current_delegator_balances: Array; /** fetch data from the table: "current_delegator_balances" using primary key columns */ @@ -3257,6 +4011,8 @@ export type Query_Root = { delegated_staking_pools: Array; /** fetch data from the table: "delegated_staking_pools" using primary key columns */ delegated_staking_pools_by_pk?: Maybe; + /** fetch data from the table: "delegator_distinct_pool" */ + delegator_distinct_pool: Array; /** fetch data from the table: "events" */ events: Array; /** fetch data from the table: "events" using primary key columns */ @@ -3316,6 +4072,15 @@ export type Query_Root = { }; +export type Query_RootAddress_Events_SummaryArgs = { + distinct_on?: InputMaybe>; + limit?: InputMaybe; + offset?: InputMaybe; + order_by?: InputMaybe>; + where?: InputMaybe; +}; + + export type Query_RootAddress_Version_From_EventsArgs = { distinct_on?: InputMaybe>; limit?: InputMaybe; @@ -3325,6 +4090,15 @@ export type Query_RootAddress_Version_From_EventsArgs = { }; +export type Query_RootAddress_Version_From_Events_AggregateArgs = { + distinct_on?: InputMaybe>; + limit?: InputMaybe; + offset?: InputMaybe; + order_by?: InputMaybe>; + where?: InputMaybe; +}; + + export type Query_RootAddress_Version_From_Move_ResourcesArgs = { distinct_on?: InputMaybe>; limit?: InputMaybe; @@ -3334,6 +4108,20 @@ export type Query_RootAddress_Version_From_Move_ResourcesArgs = { }; +export type Query_RootBlock_Metadata_TransactionsArgs = { + distinct_on?: InputMaybe>; + limit?: InputMaybe; + offset?: InputMaybe; + order_by?: InputMaybe>; + where?: InputMaybe; +}; + + +export type Query_RootBlock_Metadata_Transactions_By_PkArgs = { + version: Scalars['bigint']; +}; + + export type Query_RootCoin_ActivitiesArgs = { distinct_on?: InputMaybe>; limit?: InputMaybe; @@ -3343,6 +4131,15 @@ export type Query_RootCoin_ActivitiesArgs = { }; +export type Query_RootCoin_Activities_AggregateArgs = { + distinct_on?: InputMaybe>; + limit?: InputMaybe; + offset?: InputMaybe; + order_by?: InputMaybe>; + where?: InputMaybe; +}; + + export type Query_RootCoin_Activities_By_PkArgs = { event_account_address: Scalars['String']; event_creation_number: Scalars['bigint']; @@ -3455,6 +4252,24 @@ export type Query_RootCurrent_Collection_Datas_By_PkArgs = { }; +export type Query_RootCurrent_Collection_Ownership_V2_ViewArgs = { + distinct_on?: InputMaybe>; + limit?: InputMaybe; + offset?: InputMaybe; + order_by?: InputMaybe>; + where?: InputMaybe; +}; + + +export type Query_RootCurrent_Collection_Ownership_V2_View_AggregateArgs = { + distinct_on?: InputMaybe>; + limit?: InputMaybe; + offset?: InputMaybe; + order_by?: InputMaybe>; + where?: InputMaybe; +}; + + export type Query_RootCurrent_Collection_Ownership_ViewArgs = { distinct_on?: InputMaybe>; limit?: InputMaybe; @@ -3478,6 +4293,20 @@ export type Query_RootCurrent_Collections_V2_By_PkArgs = { }; +export type Query_RootCurrent_Delegated_Staking_Pool_BalancesArgs = { + distinct_on?: InputMaybe>; + limit?: InputMaybe; + offset?: InputMaybe; + order_by?: InputMaybe>; + where?: InputMaybe; +}; + + +export type Query_RootCurrent_Delegated_Staking_Pool_Balances_By_PkArgs = { + staking_pool_address: Scalars['String']; +}; + + export type Query_RootCurrent_Delegator_BalancesArgs = { distinct_on?: InputMaybe>; limit?: InputMaybe; @@ -3491,6 +4320,7 @@ export type Query_RootCurrent_Delegator_Balances_By_PkArgs = { delegator_address: Scalars['String']; pool_address: Scalars['String']; pool_type: Scalars['String']; + table_handle: Scalars['String']; }; @@ -3648,6 +4478,15 @@ export type Query_RootDelegated_Staking_Pools_By_PkArgs = { }; +export type Query_RootDelegator_Distinct_PoolArgs = { + distinct_on?: InputMaybe>; + limit?: InputMaybe; + offset?: InputMaybe; + order_by?: InputMaybe>; + where?: InputMaybe; +}; + + export type Query_RootEventsArgs = { distinct_on?: InputMaybe>; limit?: InputMaybe; @@ -3876,15 +4715,28 @@ export type Query_RootUser_Transactions_By_PkArgs = { export type Subscription_Root = { __typename?: 'subscription_root'; + /** fetch data from the table: "address_events_summary" */ + address_events_summary: Array; + /** fetch data from the table in a streaming manner : "address_events_summary" */ + address_events_summary_stream: Array; /** fetch data from the table: "address_version_from_events" */ address_version_from_events: Array; + /** fetch aggregated fields from the table: "address_version_from_events" */ + address_version_from_events_aggregate: Address_Version_From_Events_Aggregate; /** fetch data from the table in a streaming manner : "address_version_from_events" */ address_version_from_events_stream: Array; /** fetch data from the table: "address_version_from_move_resources" */ address_version_from_move_resources: Array; /** fetch data from the table in a streaming manner : "address_version_from_move_resources" */ address_version_from_move_resources_stream: Array; + /** fetch data from the table: "block_metadata_transactions" */ + block_metadata_transactions: Array; + /** fetch data from the table: "block_metadata_transactions" using primary key columns */ + block_metadata_transactions_by_pk?: Maybe; + /** fetch data from the table in a streaming manner : "block_metadata_transactions" */ + block_metadata_transactions_stream: Array; coin_activities: Array; + coin_activities_aggregate: Coin_Activities_Aggregate; /** fetch data from the table: "coin_activities" using primary key columns */ coin_activities_by_pk?: Maybe; /** fetch data from the table in a streaming manner : "coin_activities" */ @@ -3931,6 +4783,12 @@ export type Subscription_Root = { current_collection_datas_by_pk?: Maybe; /** fetch data from the table in a streaming manner : "current_collection_datas" */ current_collection_datas_stream: Array; + /** fetch data from the table: "current_collection_ownership_v2_view" */ + current_collection_ownership_v2_view: Array; + /** fetch aggregated fields from the table: "current_collection_ownership_v2_view" */ + current_collection_ownership_v2_view_aggregate: Current_Collection_Ownership_V2_View_Aggregate; + /** fetch data from the table in a streaming manner : "current_collection_ownership_v2_view" */ + current_collection_ownership_v2_view_stream: Array; /** fetch data from the table: "current_collection_ownership_view" */ current_collection_ownership_view: Array; /** fetch data from the table in a streaming manner : "current_collection_ownership_view" */ @@ -3941,6 +4799,12 @@ export type Subscription_Root = { current_collections_v2_by_pk?: Maybe; /** fetch data from the table in a streaming manner : "current_collections_v2" */ current_collections_v2_stream: Array; + /** fetch data from the table: "current_delegated_staking_pool_balances" */ + current_delegated_staking_pool_balances: Array; + /** fetch data from the table: "current_delegated_staking_pool_balances" using primary key columns */ + current_delegated_staking_pool_balances_by_pk?: Maybe; + /** fetch data from the table in a streaming manner : "current_delegated_staking_pool_balances" */ + current_delegated_staking_pool_balances_stream: Array; /** fetch data from the table: "current_delegator_balances" */ current_delegator_balances: Array; /** fetch data from the table: "current_delegator_balances" using primary key columns */ @@ -4005,6 +4869,10 @@ export type Subscription_Root = { delegated_staking_pools_by_pk?: Maybe; /** fetch data from the table in a streaming manner : "delegated_staking_pools" */ delegated_staking_pools_stream: Array; + /** fetch data from the table: "delegator_distinct_pool" */ + delegator_distinct_pool: Array; + /** fetch data from the table in a streaming manner : "delegator_distinct_pool" */ + delegator_distinct_pool_stream: Array; /** fetch data from the table: "events" */ events: Array; /** fetch data from the table: "events" using primary key columns */ @@ -4092,6 +4960,22 @@ export type Subscription_Root = { }; +export type Subscription_RootAddress_Events_SummaryArgs = { + distinct_on?: InputMaybe>; + limit?: InputMaybe; + offset?: InputMaybe; + order_by?: InputMaybe>; + where?: InputMaybe; +}; + + +export type Subscription_RootAddress_Events_Summary_StreamArgs = { + batch_size: Scalars['Int']; + cursor: Array>; + where?: InputMaybe; +}; + + export type Subscription_RootAddress_Version_From_EventsArgs = { distinct_on?: InputMaybe>; limit?: InputMaybe; @@ -4101,6 +4985,15 @@ export type Subscription_RootAddress_Version_From_EventsArgs = { }; +export type Subscription_RootAddress_Version_From_Events_AggregateArgs = { + distinct_on?: InputMaybe>; + limit?: InputMaybe; + offset?: InputMaybe; + order_by?: InputMaybe>; + where?: InputMaybe; +}; + + export type Subscription_RootAddress_Version_From_Events_StreamArgs = { batch_size: Scalars['Int']; cursor: Array>; @@ -4124,6 +5017,27 @@ export type Subscription_RootAddress_Version_From_Move_Resources_StreamArgs = { }; +export type Subscription_RootBlock_Metadata_TransactionsArgs = { + distinct_on?: InputMaybe>; + limit?: InputMaybe; + offset?: InputMaybe; + order_by?: InputMaybe>; + where?: InputMaybe; +}; + + +export type Subscription_RootBlock_Metadata_Transactions_By_PkArgs = { + version: Scalars['bigint']; +}; + + +export type Subscription_RootBlock_Metadata_Transactions_StreamArgs = { + batch_size: Scalars['Int']; + cursor: Array>; + where?: InputMaybe; +}; + + export type Subscription_RootCoin_ActivitiesArgs = { distinct_on?: InputMaybe>; limit?: InputMaybe; @@ -4133,6 +5047,15 @@ export type Subscription_RootCoin_ActivitiesArgs = { }; +export type Subscription_RootCoin_Activities_AggregateArgs = { + distinct_on?: InputMaybe>; + limit?: InputMaybe; + offset?: InputMaybe; + order_by?: InputMaybe>; + where?: InputMaybe; +}; + + export type Subscription_RootCoin_Activities_By_PkArgs = { event_account_address: Scalars['String']; event_creation_number: Scalars['bigint']; @@ -4301,6 +5224,31 @@ export type Subscription_RootCurrent_Collection_Datas_StreamArgs = { }; +export type Subscription_RootCurrent_Collection_Ownership_V2_ViewArgs = { + distinct_on?: InputMaybe>; + limit?: InputMaybe; + offset?: InputMaybe; + order_by?: InputMaybe>; + where?: InputMaybe; +}; + + +export type Subscription_RootCurrent_Collection_Ownership_V2_View_AggregateArgs = { + distinct_on?: InputMaybe>; + limit?: InputMaybe; + offset?: InputMaybe; + order_by?: InputMaybe>; + where?: InputMaybe; +}; + + +export type Subscription_RootCurrent_Collection_Ownership_V2_View_StreamArgs = { + batch_size: Scalars['Int']; + cursor: Array>; + where?: InputMaybe; +}; + + export type Subscription_RootCurrent_Collection_Ownership_ViewArgs = { distinct_on?: InputMaybe>; limit?: InputMaybe; @@ -4338,6 +5286,27 @@ export type Subscription_RootCurrent_Collections_V2_StreamArgs = { }; +export type Subscription_RootCurrent_Delegated_Staking_Pool_BalancesArgs = { + distinct_on?: InputMaybe>; + limit?: InputMaybe; + offset?: InputMaybe; + order_by?: InputMaybe>; + where?: InputMaybe; +}; + + +export type Subscription_RootCurrent_Delegated_Staking_Pool_Balances_By_PkArgs = { + staking_pool_address: Scalars['String']; +}; + + +export type Subscription_RootCurrent_Delegated_Staking_Pool_Balances_StreamArgs = { + batch_size: Scalars['Int']; + cursor: Array>; + where?: InputMaybe; +}; + + export type Subscription_RootCurrent_Delegator_BalancesArgs = { distinct_on?: InputMaybe>; limit?: InputMaybe; @@ -4351,6 +5320,7 @@ export type Subscription_RootCurrent_Delegator_Balances_By_PkArgs = { delegator_address: Scalars['String']; pool_address: Scalars['String']; pool_type: Scalars['String']; + table_handle: Scalars['String']; }; @@ -4578,6 +5548,22 @@ export type Subscription_RootDelegated_Staking_Pools_StreamArgs = { }; +export type Subscription_RootDelegator_Distinct_PoolArgs = { + distinct_on?: InputMaybe>; + limit?: InputMaybe; + offset?: InputMaybe; + order_by?: InputMaybe>; + where?: InputMaybe; +}; + + +export type Subscription_RootDelegator_Distinct_Pool_StreamArgs = { + batch_size: Scalars['Int']; + cursor: Array>; + where?: InputMaybe; +}; + + export type Subscription_RootEventsArgs = { distinct_on?: InputMaybe>; limit?: InputMaybe; diff --git a/ecosystem/typescript/sdk/src/indexer/queries/getCollectionsWithOwnedTokens.graphql b/ecosystem/typescript/sdk/src/indexer/queries/getCollectionsWithOwnedTokens.graphql new file mode 100644 index 0000000000000..e919780286597 --- /dev/null +++ b/ecosystem/typescript/sdk/src/indexer/queries/getCollectionsWithOwnedTokens.graphql @@ -0,0 +1,26 @@ +query getCollectionsWithOwnedTokens( + $where_condition: current_collection_ownership_v2_view_bool_exp! + $offset: Int + $limit: Int +) { + current_collection_ownership_v2_view( + where: $where_condition + order_by: { last_transaction_version: desc } + offset: $offset + limit: $limit + ) { + current_collection { + creator_address + collection_name + token_standard + collection_id + description + table_handle_v1 + uri + total_minted_v2 + max_supply + } + distinct_tokens + last_transaction_version + } +} diff --git a/ecosystem/typescript/sdk/src/indexer/queries/getOwnedTokens.graphql b/ecosystem/typescript/sdk/src/indexer/queries/getOwnedTokens.graphql index 1920e431db6bc..1ac45b0dfbed7 100644 --- a/ecosystem/typescript/sdk/src/indexer/queries/getOwnedTokens.graphql +++ b/ecosystem/typescript/sdk/src/indexer/queries/getOwnedTokens.graphql @@ -1,10 +1,6 @@ #import "./CurrentTokenOwnershipFieldsFragment"; -query getOwnedTokens($address: String!, $offset: Int, $limit: Int) { - current_token_ownerships_v2( - where: { owner_address: { _eq: $address }, amount: { _gt: 0 } } - offset: $offset - limit: $limit - ) { +query getOwnedTokens($where_condition: current_token_ownerships_v2_bool_exp!, $offset: Int, $limit: Int) { + current_token_ownerships_v2(where: $where_condition, offset: $offset, limit: $limit) { ...CurrentTokenOwnershipFields } } diff --git a/ecosystem/typescript/sdk/src/indexer/queries/getTokenOwnedFromCollection.graphql b/ecosystem/typescript/sdk/src/indexer/queries/getTokenOwnedFromCollection.graphql index 978fa420c16dd..fae4705a36e92 100644 --- a/ecosystem/typescript/sdk/src/indexer/queries/getTokenOwnedFromCollection.graphql +++ b/ecosystem/typescript/sdk/src/indexer/queries/getTokenOwnedFromCollection.graphql @@ -1,14 +1,6 @@ #import "./CurrentTokenOwnershipFieldsFragment"; -query getTokenOwnedFromCollection($collection_id: String!, $owner_address: String!, $offset: Int, $limit: Int) { - current_token_ownerships_v2( - where: { - owner_address: { _eq: $owner_address } - current_token_data: { collection_id: { _eq: $collection_id } } - amount: { _gt: 0 } - } - offset: $offset - limit: $limit - ) { +query getTokenOwnedFromCollection($where_condition: current_token_ownerships_v2_bool_exp!, $offset: Int, $limit: Int) { + current_token_ownerships_v2(where: $where_condition, offset: $offset, limit: $limit) { ...CurrentTokenOwnershipFields } } diff --git a/ecosystem/typescript/sdk/src/providers/indexer.ts b/ecosystem/typescript/sdk/src/providers/indexer.ts index 7186dc1fa66f2..834ca38a2b573 100644 --- a/ecosystem/typescript/sdk/src/providers/indexer.ts +++ b/ecosystem/typescript/sdk/src/providers/indexer.ts @@ -20,6 +20,7 @@ import { GetOwnedTokensQuery, GetTokenOwnedFromCollectionQuery, GetCollectionDataQuery, + GetCollectionsWithOwnedTokensQuery, } from "../indexer/generated/operations"; import { GetAccountTokensCount, @@ -39,6 +40,7 @@ import { GetOwnedTokens, GetTokenOwnedFromCollection, GetCollectionData, + GetCollectionsWithOwnedTokens, } from "../indexer/generated/queries"; /** @@ -324,21 +326,42 @@ export class IndexerClient { /** * Queries account's current owned tokens. * This query returns all tokens (v1 and v2 standards) an account owns, including NFTs, fungible, soulbound, etc. - * + * If you want to get only the token from a specific standrd, you can pass an optional tokenStandard param + * @example An example of how to pass a specific token standard + * ``` + * { + * tokenStandard:"v2" + * } + * ``` * @param ownerAddress The token owner address we want to get the tokens for * @returns GetOwnedTokensQuery response type */ async getOwnedTokens( ownerAddress: MaybeHexString, extraArgs?: { + tokenStandard?: TokenStandard; options?: PaginationArgs; }, ): Promise { const address = HexString.ensure(ownerAddress).hex(); IndexerClient.validateAddress(address); + + const whereCondition: any = { + owner_address: { _eq: address }, + amount: { _gt: 0 }, + }; + + if (extraArgs?.tokenStandard) { + whereCondition.token_standard = { _eq: extraArgs?.tokenStandard }; + } + const graphqlQuery = { query: GetOwnedTokens, - variables: { address, offset: extraArgs?.options?.offset, limit: extraArgs?.options?.limit }, + variables: { + where_condition: whereCondition, + offset: extraArgs?.options?.offset, + limit: extraArgs?.options?.limit, + }, }; return this.queryIndexer(graphqlQuery); } @@ -364,11 +387,20 @@ export class IndexerClient { const collectionHexAddress = HexString.ensure(collectionAddress).hex(); IndexerClient.validateAddress(collectionHexAddress); + const whereCondition: any = { + owner_address: { _eq: ownerHexAddress }, + current_token_data: { collection_id: { _eq: collectionHexAddress } }, + amount: { _gt: 0 }, + }; + + if (extraArgs?.tokenStandard) { + whereCondition.token_standard = { _eq: extraArgs?.tokenStandard }; + } + const graphqlQuery = { query: GetTokenOwnedFromCollection, variables: { - collection_id: collectionHexAddress, - owner_address: ownerHexAddress, + where_condition: whereCondition, offset: extraArgs?.options?.offset, limit: extraArgs?.options?.limit, }, @@ -457,4 +489,39 @@ export class IndexerClient { return (await this.getCollectionData(creatorAddress, collectionName, extraArgs)).current_collections_v2[0] .collection_id; } + + /** + * Queries for all collections that an account has tokens for. + * + * @param ownerAddress the account address that owns the tokens + * @returns GetCollectionsWithOwnedTokensQuery response type + */ + async getCollectionsWithOwnedTokens( + ownerAddress: MaybeHexString, + extraArgs?: { + tokenStandard?: TokenStandard; + options?: PaginationArgs; + }, + ): Promise { + const ownerHexAddress = HexString.ensure(ownerAddress).hex(); + IndexerClient.validateAddress(ownerHexAddress); + + const whereCondition: any = { + owner_address: { _eq: ownerHexAddress }, + }; + + if (extraArgs?.tokenStandard) { + whereCondition.current_collection = { token_standard: { _eq: extraArgs?.tokenStandard } }; + } + + const graphqlQuery = { + query: GetCollectionsWithOwnedTokens, + variables: { + where_condition: whereCondition, + offset: extraArgs?.options?.offset, + limit: extraArgs?.options?.limit, + }, + }; + return this.queryIndexer(graphqlQuery); + } } diff --git a/ecosystem/typescript/sdk/src/tests/e2e/indexer.test.ts b/ecosystem/typescript/sdk/src/tests/e2e/indexer.test.ts index fdb6fa75e6479..64d6399951363 100644 --- a/ecosystem/typescript/sdk/src/tests/e2e/indexer.test.ts +++ b/ecosystem/typescript/sdk/src/tests/e2e/indexer.test.ts @@ -235,6 +235,11 @@ describe("Indexer", () => { expect(tokens.current_token_ownerships_v2).toHaveLength(2); }); + it("gets account current tokens from a specified token standard", async () => { + const tokens = await indexerClient.getOwnedTokens(alice.address().hex(), { tokenStandard: "v2" }); + expect(tokens.current_token_ownerships_v2).toHaveLength(1); + }); + it("gets the collection data", async () => { const collectionData = await indexerClient.getCollectionData(alice.address().hex(), collectionName); expect(collectionData.current_collections_v2).toHaveLength(1); @@ -284,5 +289,25 @@ describe("Indexer", () => { }, longTestTimeout, ); + + it( + "queries for all collections that an account has tokens for", + async () => { + const collections = await indexerClient.getCollectionsWithOwnedTokens(alice.address().hex()); + expect(collections.current_collection_ownership_v2_view.length).toEqual(2); + }, + longTestTimeout, + ); + + it( + "queries for all v2 collections that an account has tokens for", + async () => { + const collections = await indexerClient.getCollectionsWithOwnedTokens(alice.address().hex(), { + tokenStandard: "v2", + }); + expect(collections.current_collection_ownership_v2_view.length).toEqual(1); + }, + longTestTimeout, + ); }); }); From c613c43577b42fa657321f6faab2855c3ace3052 Mon Sep 17 00:00:00 2001 From: Kevin <105028215+movekevin@users.noreply.github.com> Date: Tue, 6 Jun 2023 15:21:39 -0500 Subject: [PATCH 079/200] Add functions to extract all keys and values from simple_map and (token v1's property_map) (#8501) --- .../framework/aptos-stdlib/doc/simple_map.md | 92 ++++++++++++ .../aptos-stdlib/sources/simple_map.move | 36 +++++ .../aptos-stdlib/sources/simple_map.spec.move | 8 + .../framework/aptos-token/doc/property_map.md | 137 +++++++++++++++++- .../aptos-token/sources/property_map.move | 66 +++++++-- .../sources/property_map.spec.move | 12 ++ 6 files changed, 340 insertions(+), 11 deletions(-) diff --git a/aptos-move/framework/aptos-stdlib/doc/simple_map.md b/aptos-move/framework/aptos-stdlib/doc/simple_map.md index fdbd00ab5e0d6..66092156f555b 100644 --- a/aptos-move/framework/aptos-stdlib/doc/simple_map.md +++ b/aptos-move/framework/aptos-stdlib/doc/simple_map.md @@ -22,6 +22,8 @@ This module provides a solution for sorted maps, that is it has the properties t - [Function `destroy_empty`](#0x1_simple_map_destroy_empty) - [Function `add`](#0x1_simple_map_add) - [Function `upsert`](#0x1_simple_map_upsert) +- [Function `keys`](#0x1_simple_map_keys) +- [Function `values`](#0x1_simple_map_values) - [Function `to_vec_pair`](#0x1_simple_map_to_vec_pair) - [Function `destroy`](#0x1_simple_map_destroy) - [Function `remove`](#0x1_simple_map_remove) @@ -36,6 +38,8 @@ This module provides a solution for sorted maps, that is it has the properties t - [Function `destroy_empty`](#@Specification_1_destroy_empty) - [Function `add`](#@Specification_1_add) - [Function `upsert`](#@Specification_1_upsert) + - [Function `keys`](#@Specification_1_keys) + - [Function `values`](#@Specification_1_values) - [Function `to_vec_pair`](#@Specification_1_to_vec_pair) - [Function `remove`](#@Specification_1_remove) - [Function `find`](#@Specification_1_find) @@ -368,6 +372,62 @@ Insert key/value pair or update an existing key to a new value + + + + +## Function `keys` + +Return all keys in the map. This requires keys to be copyable. + + +
public fun keys<Key: copy, Value>(map: &simple_map::SimpleMap<Key, Value>): vector<Key>
+
+ + + +
+Implementation + + +
public fun keys<Key: copy, Value>(map: &SimpleMap<Key, Value>): vector<Key> {
+    vector::map_ref(&map.data, |e| {
+        let e: &Element<Key, Value> = e;
+        e.key
+    })
+}
+
+ + + +
+ + + +## Function `values` + +Return all values in the map. This requires values to be copyable. + + +
public fun values<Key, Value: copy>(map: &simple_map::SimpleMap<Key, Value>): vector<Value>
+
+ + + +
+Implementation + + +
public fun values<Key, Value: copy>(map: &SimpleMap<Key, Value>): vector<Value> {
+    vector::map_ref(&map.data, |e| {
+        let e: &Element<Key, Value> = e;
+        e.value
+    })
+}
+
+ + +
@@ -724,6 +784,38 @@ using lambdas to destroy the individual keys and values. + + +### Function `keys` + + +
public fun keys<Key: copy, Value>(map: &simple_map::SimpleMap<Key, Value>): vector<Key>
+
+ + + + +
pragma verify=false;
+
+ + + + + +### Function `values` + + +
public fun values<Key, Value: copy>(map: &simple_map::SimpleMap<Key, Value>): vector<Value>
+
+ + + + +
pragma verify=false;
+
+ + + ### Function `to_vec_pair` diff --git a/aptos-move/framework/aptos-stdlib/sources/simple_map.move b/aptos-move/framework/aptos-stdlib/sources/simple_map.move index 70a6cd07931e4..84a117786cc29 100644 --- a/aptos-move/framework/aptos-stdlib/sources/simple_map.move +++ b/aptos-move/framework/aptos-stdlib/sources/simple_map.move @@ -100,6 +100,22 @@ module aptos_std::simple_map { (std::option::none(), std::option::none()) } + /// Return all keys in the map. This requires keys to be copyable. + public fun keys(map: &SimpleMap): vector { + vector::map_ref(&map.data, |e| { + let e: &Element = e; + e.key + }) + } + + /// Return all values in the map. This requires values to be copyable. + public fun values(map: &SimpleMap): vector { + vector::map_ref(&map.data, |e| { + let e: &Element = e; + e.value + }) + } + /// Transform the map into two vectors with the keys and values respectively /// Primarily used to destroy a map public fun to_vec_pair( @@ -183,6 +199,26 @@ module aptos_std::simple_map { destroy_empty(map); } + #[test] + public fun test_keys() { + let map = create(); + assert!(keys(&map) == vector[], 0); + add(&mut map, 2, 1); + add(&mut map, 3, 1); + + assert!(keys(&map) == vector[2, 3], 0); + } + + #[test] + public fun test_values() { + let map = create(); + assert!(values(&map) == vector[], 0); + add(&mut map, 2, 1); + add(&mut map, 3, 2); + + assert!(values(&map) == vector[1, 2], 0); + } + #[test] #[expected_failure] public fun add_twice() { diff --git a/aptos-move/framework/aptos-stdlib/sources/simple_map.spec.move b/aptos-move/framework/aptos-stdlib/sources/simple_map.spec.move index b9a40e720c93d..2c8ea20bd5749 100644 --- a/aptos-move/framework/aptos-stdlib/sources/simple_map.spec.move +++ b/aptos-move/framework/aptos-stdlib/sources/simple_map.spec.move @@ -56,6 +56,14 @@ spec aptos_std::simple_map { pragma verify=false; } + spec keys { + pragma verify=false; + } + + spec values { + pragma verify=false; + } + spec to_vec_pair(map: SimpleMap): (vector, vector) { pragma intrinsic; pragma opaque; diff --git a/aptos-move/framework/aptos-token/doc/property_map.md b/aptos-move/framework/aptos-token/doc/property_map.md index 5cd717ee647bf..cddfd84c49170 100644 --- a/aptos-move/framework/aptos-token/doc/property_map.md +++ b/aptos-move/framework/aptos-token/doc/property_map.md @@ -19,6 +19,9 @@ It also supports deserializing property value to it original type. - [Function `add`](#0x3_property_map_add) - [Function `length`](#0x3_property_map_length) - [Function `borrow`](#0x3_property_map_borrow) +- [Function `keys`](#0x3_property_map_keys) +- [Function `types`](#0x3_property_map_types) +- [Function `values`](#0x3_property_map_values) - [Function `read_string`](#0x3_property_map_read_string) - [Function `read_u8`](#0x3_property_map_read_u8) - [Function `read_u64`](#0x3_property_map_read_u64) @@ -40,6 +43,9 @@ It also supports deserializing property value to it original type. - [Function `add`](#@Specification_1_add) - [Function `length`](#@Specification_1_length) - [Function `borrow`](#@Specification_1_borrow) + - [Function `keys`](#@Specification_1_keys) + - [Function `types`](#@Specification_1_types) + - [Function `values`](#@Specification_1_values) - [Function `read_string`](#@Specification_1_read_string) - [Function `read_u8`](#@Specification_1_read_u8) - [Function `read_u64`](#@Specification_1_read_u64) @@ -374,7 +380,7 @@ Create property map directly from key and property value 
public fun add(map: &mut PropertyMap, key: String, value: PropertyValue) {
     assert!(string::length(&key) <= MAX_PROPERTY_NAME_LENGTH, error::invalid_argument(EPROPERTY_MAP_NAME_TOO_LONG));
-    assert!(simple_map::length<String, PropertyValue>(&map.map) < MAX_PROPERTY_MAP_SIZE, error::invalid_state(EPROPERTY_NUMBER_EXCEED_LIMIT));
+    assert!(simple_map::length(&map.map) < MAX_PROPERTY_MAP_SIZE, error::invalid_state(EPROPERTY_NUMBER_EXCEED_LIMIT));
     simple_map::add(&mut map.map, key, value);
 }
@@ -431,6 +437,87 @@ Create property map directly from key and property value + + + + +## Function `keys` + +Return all the keys in the property map in the order they are added. + + +
public fun keys(map: &property_map::PropertyMap): vector<string::String>
+
+ + + +
+Implementation + + +
public fun keys(map: &PropertyMap): vector<String> {
+    simple_map::keys(&map.map)
+}
+
+ + + +
+ + + +## Function `types` + +Return the types of all properties in the property map in the order they are added. + + +
public fun types(map: &property_map::PropertyMap): vector<string::String>
+
+ + + +
+Implementation + + +
public fun types(map: &PropertyMap): vector<String> {
+    vector::map_ref(&simple_map::values(&map.map), |v| {
+        let v: &PropertyValue = v;
+        v.type
+    })
+}
+
+ + + +
+ + + +## Function `values` + +Return the values of all properties in the property map in the order they are added. + + +
public fun values(map: &property_map::PropertyMap): vector<vector<u8>>
+
+ + + +
+Implementation + + +
public fun values(map: &PropertyMap): vector<vector<u8>> {
+    vector::map_ref(&simple_map::values(&map.map), |v| {
+        let v: &PropertyValue = v;
+        v.value
+    })
+}
+
+ + +
@@ -947,6 +1034,54 @@ create a property value from generic type data + + +### Function `keys` + + +
public fun keys(map: &property_map::PropertyMap): vector<string::String>
+
+ + + + +
pragma verify = false;
+
+ + + + + +### Function `types` + + +
public fun types(map: &property_map::PropertyMap): vector<string::String>
+
+ + + + +
pragma verify = false;
+
+ + + + + +### Function `values` + + +
public fun values(map: &property_map::PropertyMap): vector<vector<u8>>
+
+ + + + +
pragma verify = false;
+
+ + + ### Function `read_string` diff --git a/aptos-move/framework/aptos-token/sources/property_map.move b/aptos-move/framework/aptos-token/sources/property_map.move index 321266cf59cd7..45546cc402644 100644 --- a/aptos-move/framework/aptos-token/sources/property_map.move +++ b/aptos-move/framework/aptos-token/sources/property_map.move @@ -117,7 +117,7 @@ module aptos_token::property_map { public fun add(map: &mut PropertyMap, key: String, value: PropertyValue) { assert!(string::length(&key) <= MAX_PROPERTY_NAME_LENGTH, error::invalid_argument(EPROPERTY_MAP_NAME_TOO_LONG)); - assert!(simple_map::length(&map.map) < MAX_PROPERTY_MAP_SIZE, error::invalid_state(EPROPERTY_NUMBER_EXCEED_LIMIT)); + assert!(simple_map::length(&map.map) < MAX_PROPERTY_MAP_SIZE, error::invalid_state(EPROPERTY_NUMBER_EXCEED_LIMIT)); simple_map::add(&mut map.map, key, value); } @@ -131,6 +131,27 @@ module aptos_token::property_map { simple_map::borrow(&map.map, key) } + /// Return all the keys in the property map in the order they are added. + public fun keys(map: &PropertyMap): vector { + simple_map::keys(&map.map) + } + + /// Return the types of all properties in the property map in the order they are added. + public fun types(map: &PropertyMap): vector { + vector::map_ref(&simple_map::values(&map.map), |v| { + let v: &PropertyValue = v; + v.type + }) + } + + /// Return the values of all properties in the property map in the order they are added. + public fun values(map: &PropertyMap): vector> { + vector::map_ref(&simple_map::values(&map.map), |v| { + let v: &PropertyValue = v; + v.value + }) + } + public fun read_string(map: &PropertyMap, key: &String): String { let prop = borrow(map, key); assert!(prop.type == string::utf8(b"0x1::string::String"), error::invalid_state(ETYPE_NOT_MATCH)); @@ -250,18 +271,31 @@ module aptos_token::property_map { } } + #[test_only] + use std::string::utf8; + + #[test_only] + fun test_keys(): vector { + vector[ utf8(b"attack"), utf8(b"durability"), utf8(b"type") ] + } + + #[test_only] + fun test_values(): vector> { + vector[ b"10", b"5", b"weapon" ] + } + + #[test_only] + fun test_types(): vector { + vector[ utf8(b"integer"), utf8(b"integer"), utf8(b"String") ] + } + #[test_only] fun create_property_list(): PropertyMap { - use std::string::utf8; - let keys = vector[ utf8(b"attack"), utf8(b"durability"), utf8(b"type")]; - let values = vector>[ b"10", b"5", b"weapon" ]; - let types = vector[ utf8(b"integer"), utf8(b"integer"), utf8(b"String") ]; - new(keys, values, types) + new(test_keys(), test_values(), test_types()) } #[test] fun test_add_property(): PropertyMap { - use std::string::utf8; let properties = create_property_list(); add( &mut properties, utf8(b"level"), @@ -275,9 +309,23 @@ module aptos_token::property_map { properties } + #[test] + fun test_get_property_keys() { + assert!(keys(&create_property_list()) == test_keys(), 0); + } + + #[test] + fun test_get_property_types() { + assert!(types(&create_property_list()) == test_types(), 0); + } + + #[test] + fun test_get_property_values() { + assert!(values(&create_property_list()) == test_values(), 0); + } + #[test] fun test_update_property(): PropertyMap { - use std::string::utf8; let properties = create_property_list(); update_property_value(&mut properties, &utf8(b"attack"), PropertyValue { value: b"7", type: utf8(b"integer") }); assert!( @@ -289,7 +337,6 @@ module aptos_token::property_map { #[test] fun test_remove_property(): PropertyMap { - use std::string::utf8; let properties = create_property_list(); assert!(length(&mut properties) == 3, 1); let (_, _) = remove(&mut properties, &utf8(b"attack")); @@ -307,7 +354,6 @@ module aptos_token::property_map { #[test] fun test_read_value_with_type() { - use std::string::utf8; let keys = vector[ utf8(b"attack"), utf8(b"mutable")]; let values = vector>[ bcs::to_bytes(&10), bcs::to_bytes(&false) ]; let types = vector[ utf8(b"u8"), utf8(b"bool")]; diff --git a/aptos-move/framework/aptos-token/sources/property_map.spec.move b/aptos-move/framework/aptos-token/sources/property_map.spec.move index 30a1bd242705f..b97e90b2c1bae 100644 --- a/aptos-move/framework/aptos-token/sources/property_map.spec.move +++ b/aptos-move/framework/aptos-token/sources/property_map.spec.move @@ -52,6 +52,18 @@ spec aptos_token::property_map { aborts_if false; } + spec keys(map: &PropertyMap): vector { + pragma verify = false; + } + + spec types(map: &PropertyMap): vector { + pragma verify = false; + } + + spec values(map: &PropertyMap): vector> { + pragma verify = false; + } + spec borrow(map: &PropertyMap, key: &String): &PropertyValue { use aptos_framework::simple_map; aborts_if !simple_map::spec_contains_key(map.map, key); From af991b81cd81607eef9e61e6db90b06f2bc87789 Mon Sep 17 00:00:00 2001 From: alnoki <43892045+alnoki@users.noreply.github.com> Date: Tue, 6 Jun 2023 13:22:05 -0700 Subject: [PATCH 080/200] [Aptos Framework] Add multisig v2 owner helpers, abstractions (#8525) --- .../aptos-framework/doc/multisig_account.md | 338 ++++++++++++++---- .../sources/multisig_account.move | 274 ++++++++++---- .../src/aptos_framework_sdk_builder.rs | 198 +++++++++- 3 files changed, 649 insertions(+), 161 deletions(-) diff --git a/aptos-move/framework/aptos-framework/doc/multisig_account.md b/aptos-move/framework/aptos-framework/doc/multisig_account.md index f39fa4f1293fb..fdfc38d0d22c5 100644 --- a/aptos-move/framework/aptos-framework/doc/multisig_account.md +++ b/aptos-move/framework/aptos-framework/doc/multisig_account.md @@ -71,13 +71,16 @@ and implement the governance voting logic on top. - [Function `create_with_existing_account`](#0x1_multisig_account_create_with_existing_account) - [Function `create`](#0x1_multisig_account_create) - [Function `create_with_owners`](#0x1_multisig_account_create_with_owners) +- [Function `create_with_owners_then_remove_bootstrapper`](#0x1_multisig_account_create_with_owners_then_remove_bootstrapper) - [Function `create_with_owners_internal`](#0x1_multisig_account_create_with_owners_internal) - [Function `add_owner`](#0x1_multisig_account_add_owner) - [Function `add_owners`](#0x1_multisig_account_add_owners) - [Function `add_owners_and_update_signatures_required`](#0x1_multisig_account_add_owners_and_update_signatures_required) - [Function `remove_owner`](#0x1_multisig_account_remove_owner) - [Function `remove_owners`](#0x1_multisig_account_remove_owners) -- [Function `remove_owners_and_update_signatures_required`](#0x1_multisig_account_remove_owners_and_update_signatures_required) +- [Function `swap_owner`](#0x1_multisig_account_swap_owner) +- [Function `swap_owners`](#0x1_multisig_account_swap_owners) +- [Function `swap_owners_and_update_signatures_required`](#0x1_multisig_account_swap_owners_and_update_signatures_required) - [Function `update_signatures_required`](#0x1_multisig_account_update_signatures_required) - [Function `update_metadata`](#0x1_multisig_account_update_metadata) - [Function `update_metadata_internal`](#0x1_multisig_account_update_metadata_internal) @@ -98,6 +101,7 @@ and implement the governance voting logic on top. - [Function `assert_is_owner`](#0x1_multisig_account_assert_is_owner) - [Function `num_approvals_and_rejections`](#0x1_multisig_account_num_approvals_and_rejections) - [Function `assert_multisig_account_exists`](#0x1_multisig_account_assert_multisig_account_exists) +- [Function `update_owner_schema`](#0x1_multisig_account_update_owner_schema) 
use 0x1::account;
@@ -865,6 +869,16 @@ The number of metadata keys and values don't match.
 
 
 
+
+
+Provided owners to remove and new owners overlap.
+
+
+
const EOWNERS_TO_REMOVE_NEW_OWNERS_OVERLAP: u64 = 18;
+

+
+
+
 
 
 The multisig account itself cannot be an owner.
@@ -1401,6 +1415,53 @@ at most the total number of owners.
 
 
 
+
+
+
+
+## Function `create_with_owners_then_remove_bootstrapper`
+
+Like create_with_owners, but removes the calling account after creation.
+
+This is for creating a vanity multisig account from a bootstrapping account that should not
+be an owner after the vanity multisig address has been secured.
+
+
+
public entry fun create_with_owners_then_remove_bootstrapper(bootstrapper: &signer, owners: vector<address>, num_signatures_required: u64, metadata_keys: vector<string::String>, metadata_values: vector<vector<u8>>)
+

+
+
+
+

+Implementation
+
+
+
public entry fun create_with_owners_then_remove_bootstrapper(
+    bootstrapper: &signer,
+    owners: vector<address>,
+    num_signatures_required: u64,
+    metadata_keys: vector<String>,
+    metadata_values: vector<vector<u8>>,
+) acquires MultisigAccount {
+    let bootstrapper_address = address_of(bootstrapper);
+    create_with_owners(
+        bootstrapper,
+        owners,
+        num_signatures_required,
+        metadata_keys,
+        metadata_values
+    );
+    update_owner_schema(
+        get_next_multisig_account_address(bootstrapper_address),
+        vector[],
+        vector[bootstrapper_address],
+        option::none()
+    );
+}
+

+
+
+
 

 
 
@@ -1510,22 +1571,12 @@ maliciously alter the owners list.
 
 
entry fun add_owners(
     multisig_account: &signer, new_owners: vector<address>) acquires MultisigAccount {
-    // Short circuit if new owners list is empty.
-    // This avoids emitting an event if no changes happen, which is confusing to off-chain components.
-    if (vector::length(&new_owners) == 0) {
-        return
-    };
-
-    let multisig_address = address_of(multisig_account);
-    assert_multisig_account_exists(multisig_address);
-    let multisig_account_resource = borrow_global_mut<MultisigAccount>(multisig_address);
-
-    vector::append(&mut multisig_account_resource.owners, new_owners);
-    // This will fail if an existing owner is added again.
-    validate_owners(&multisig_account_resource.owners, multisig_address);
-    emit_event(&mut multisig_account_resource.add_owners_events, AddOwnersEvent {
-        owners_added: new_owners,
-    });
+    update_owner_schema(
+        address_of(multisig_account),
+        new_owners,
+        vector[],
+        option::none()
+    );
 }
 

 
@@ -1554,8 +1605,12 @@ Add owners then update number of signatures required, in a single operation.
     new_owners: vector<address>,
     new_num_signatures_required: u64
 ) acquires MultisigAccount {
-    add_owners(multisig_account, new_owners);
-    update_signatures_required(multisig_account, new_num_signatures_required);
+    update_owner_schema(
+        address_of(multisig_account),
+        new_owners,
+        vector[],
+        option::some(new_num_signatures_required)
+    );
 }
@@ -1613,37 +1668,46 @@ maliciously alter the owners list. 
entry fun remove_owners(
     multisig_account: &signer, owners_to_remove: vector<address>) acquires MultisigAccount {
-    // Short circuit if the list of owners to remove is empty.
-    // This avoids emitting an event if no changes happen, which is confusing to off-chain components.
-    if (vector::length(&owners_to_remove) == 0) {
-        return
-    };
+    update_owner_schema(
+        address_of(multisig_account),
+        vector[],
+        owners_to_remove,
+        option::none()
+    );
+}
+
- let multisig_address = address_of(multisig_account); - assert_multisig_account_exists(multisig_address); - let multisig_account_resource = borrow_global_mut<MultisigAccount>(multisig_address); - let owners = &mut multisig_account_resource.owners; - let owners_removed = vector::empty<address>(); - vector::for_each_ref(&owners_to_remove, |owner_to_remove| { - let owner_to_remove = *owner_to_remove; - let (found, index) = vector::index_of(owners, &owner_to_remove); - // Only remove an owner if they're present in the owners list. - if (found) { - vector::push_back(&mut owners_removed, owner_to_remove); - vector::swap_remove(owners, index); - }; - }); - // Make sure there's still at least as many owners as the number of signatures required. - // This also ensures that there's at least one owner left as signature threshold must be > 0. - assert!( - vector::length(owners) >= multisig_account_resource.num_signatures_required, - error::invalid_state(ENOT_ENOUGH_OWNERS), + + + + +## Function `swap_owner` + +Swap an owner in for an old one, without changing required signatures. + + +
entry fun swap_owner(multisig_account: &signer, to_swap_in: address, to_swap_out: address)
+
+ + + +
+Implementation + + +
entry fun swap_owner(
+    multisig_account: &signer,
+    to_swap_in: address,
+    to_swap_out: address
+) acquires MultisigAccount {
+    update_owner_schema(
+        address_of(multisig_account),
+        vector[to_swap_in],
+        vector[to_swap_out],
+        option::none()
     );
-    if (vector::length(&owners_removed) > 0) {
-        emit_event(&mut multisig_account_resource.remove_owners_events, RemoveOwnersEvent { owners_removed });
-    }
 }
@@ -1651,14 +1715,14 @@ maliciously alter the owners list.
- + -## Function `remove_owners_and_update_signatures_required` +## Function `swap_owners` -Update the number of signatures required then remove owners, in a single operation. +Swap owners in and out, without changing required signatures. -
entry fun remove_owners_and_update_signatures_required(multisig_account: &signer, owners_to_remove: vector<address>, new_num_signatures_required: u64)
+
entry fun swap_owners(multisig_account: &signer, to_swap_in: vector<address>, to_swap_out: vector<address>)
 

 
 
@@ -1667,13 +1731,52 @@ Update the number of signatures required then remove owners, in a single operati
 Implementation
 
 
-
entry fun remove_owners_and_update_signatures_required(
+
entry fun swap_owners(
     multisig_account: &signer,
+    to_swap_in: vector<address>,
+    to_swap_out: vector<address>
+) acquires MultisigAccount {
+    update_owner_schema(
+        address_of(multisig_account),
+        to_swap_in,
+        to_swap_out,
+        option::none()
+    );
+}
+

+
+
+
+
+
+
+
+## Function `swap_owners_and_update_signatures_required`
+
+Swap owners in and out, updating number of required signatures.
+
+
+
entry fun swap_owners_and_update_signatures_required(multisig_account: &signer, new_owners: vector<address>, owners_to_remove: vector<address>, new_num_signatures_required: u64)
+

+
+
+
+

+Implementation
+
+
+
entry fun swap_owners_and_update_signatures_required(
+    multisig_account: &signer,
+    new_owners: vector<address>,
     owners_to_remove: vector<address>,
     new_num_signatures_required: u64
 ) acquires MultisigAccount {
-    update_signatures_required(multisig_account, new_num_signatures_required);
-    remove_owners(multisig_account, owners_to_remove);
+    update_owner_schema(
+        address_of(multisig_account),
+        new_owners,
+        owners_to_remove,
+        option::some(new_num_signatures_required)
+    );
 }
 

 
@@ -1704,28 +1807,11 @@ maliciously alter the number of signatures required.
 
 
entry fun update_signatures_required(
     multisig_account: &signer, new_num_signatures_required: u64) acquires MultisigAccount {
-    let multisig_address = address_of(multisig_account);
-    assert_multisig_account_exists(multisig_address);
-    let multisig_account_resource = borrow_global_mut<MultisigAccount>(multisig_address);
-    // Short-circuit if the new number of signatures required is the same as before.
-    // This avoids emitting an event.
-    if (multisig_account_resource.num_signatures_required == new_num_signatures_required) {
-        return
-    };
-    let num_owners = vector::length(&multisig_account_resource.owners);
-    assert!(
-        new_num_signatures_required > 0 && new_num_signatures_required <= num_owners,
-        error::invalid_argument(EINVALID_SIGNATURES_REQUIRED),
-    );
-
-    let old_num_signatures_required = multisig_account_resource.num_signatures_required;
-    multisig_account_resource.num_signatures_required = new_num_signatures_required;
-    emit_event(
-        &mut multisig_account_resource.update_signature_required_events,
-        UpdateSignaturesRequiredEvent {
-            old_num_signatures_required,
-            new_num_signatures_required,
-        }
+    update_owner_schema(
+        address_of(multisig_account),
+        vector[],
+        vector[],
+        option::some(new_num_signatures_required)
     );
 }
 

@@ -2443,6 +2529,108 @@ This function is private so no other code can call this beside the VM itself as
 
 
 
+

+
+
+
+## Function `update_owner_schema`
+
+Add new owners, remove owners to remove, update signatures required.
+
+
+
fun update_owner_schema(multisig_address: address, new_owners: vector<address>, owners_to_remove: vector<address>, optional_new_num_signatures_required: option::Option<u64>)
+

+
+
+
+

+Implementation
+
+
+
fun update_owner_schema(
+    multisig_address: address,
+    new_owners: vector<address>,
+    owners_to_remove: vector<address>,
+    optional_new_num_signatures_required: Option<u64>,
+) acquires MultisigAccount {
+    assert_multisig_account_exists(multisig_address);
+    let multisig_account_ref_mut =
+        borrow_global_mut<MultisigAccount>(multisig_address);
+    // Verify no overlap between new owners and owners to remove.
+    vector::for_each_ref(&new_owners, |new_owner_ref| {
+        assert!(
+            !vector::contains(&owners_to_remove, new_owner_ref),
+            error::invalid_argument(EOWNERS_TO_REMOVE_NEW_OWNERS_OVERLAP)
+        )
+    });
+    // If new owners provided, try to add them and emit an event.
+    if (vector::length(&new_owners) > 0) {
+        vector::append(&mut multisig_account_ref_mut.owners, new_owners);
+        validate_owners(
+            &multisig_account_ref_mut.owners,
+            multisig_address
+        );
+        emit_event(
+            &mut multisig_account_ref_mut.add_owners_events,
+            AddOwnersEvent { owners_added: new_owners }
+        );
+    };
+    // If owners to remove provided, try to remove them.
+    if (vector::length(&owners_to_remove) > 0) {
+        let owners_ref_mut = &mut multisig_account_ref_mut.owners;
+        let owners_removed = vector[];
+        vector::for_each_ref(&owners_to_remove, |owner_to_remove_ref| {
+            let (found, index) =
+                vector::index_of(owners_ref_mut, owner_to_remove_ref);
+            if (found) {
+                vector::push_back(
+                    &mut owners_removed,
+                    vector::swap_remove(owners_ref_mut, index)
+                );
+            }
+        });
+        // Only emit event if owner(s) actually removed.
+        if (vector::length(&owners_removed) > 0) {
+            emit_event(
+                &mut multisig_account_ref_mut.remove_owners_events,
+                RemoveOwnersEvent { owners_removed }
+            );
+        }
+    };
+    // If new signature count provided, try to update count.
+    if (option::is_some(&optional_new_num_signatures_required)) {
+        let new_num_signatures_required =
+            option::extract(&mut optional_new_num_signatures_required);
+        assert!(
+            new_num_signatures_required > 0,
+            error::invalid_argument(EINVALID_SIGNATURES_REQUIRED)
+        );
+        let old_num_signatures_required =
+            multisig_account_ref_mut.num_signatures_required;
+        // Only apply update and emit event if a change indicated.
+        if (new_num_signatures_required != old_num_signatures_required) {
+            multisig_account_ref_mut.num_signatures_required =
+                new_num_signatures_required;
+            emit_event(
+                &mut multisig_account_ref_mut.update_signature_required_events,
+                UpdateSignaturesRequiredEvent {
+                    old_num_signatures_required,
+                    new_num_signatures_required,
+                }
+            );
+        }
+    };
+    // Verify number of owners.
+    let num_owners = vector::length(&multisig_account_ref_mut.owners);
+    assert!(
+        num_owners >= multisig_account_ref_mut.num_signatures_required,
+        error::invalid_state(ENOT_ENOUGH_OWNERS)
+    );
+}
+

+
+
+
 

 
 
diff --git a/aptos-move/framework/aptos-framework/sources/multisig_account.move b/aptos-move/framework/aptos-framework/sources/multisig_account.move
index eec31bb2de51f..4ed285a232b95 100644
--- a/aptos-move/framework/aptos-framework/sources/multisig_account.move
+++ b/aptos-move/framework/aptos-framework/sources/multisig_account.move
@@ -91,6 +91,8 @@ module aptos_framework::multisig_account {
     const EDUPLICATE_METADATA_KEY: u64 = 16;
     /// The sequence number provided is invalid. It must be between [1, next pending transaction - 1].
     const EINVALID_SEQUENCE_NUMBER: u64 = 17;
+    /// Provided owners to remove and new owners overlap.
+    const EOWNERS_TO_REMOVE_NEW_OWNERS_OVERLAP: u64 = 18;
 
     /// Represents a multisig account's configurations and transactions.
     /// This will be stored in the multisig account (created as a resource account separate from any owner accounts).
@@ -448,6 +450,33 @@ module aptos_framework::multisig_account {
         );
     }
 
+    /// Like `create_with_owners`, but removes the calling account after creation.
+    ///
+    /// This is for creating a vanity multisig account from a bootstrapping account that should not
+    /// be an owner after the vanity multisig address has been secured.
+    public entry fun create_with_owners_then_remove_bootstrapper(
+        bootstrapper: &signer,
+        owners: vector
,
+        num_signatures_required: u64,
+        metadata_keys: vector,
+        metadata_values: vector>,
+    ) acquires MultisigAccount {
+        let bootstrapper_address = address_of(bootstrapper);
+        create_with_owners(
+            bootstrapper,
+            owners,
+            num_signatures_required,
+            metadata_keys,
+            metadata_values
+        );
+        update_owner_schema(
+            get_next_multisig_account_address(bootstrapper_address),
+            vector[],
+            vector[bootstrapper_address],
+            option::none()
+        );
+    }
+
     fun create_with_owners_internal(
         multisig_account: &signer,
         owners: vector
,
@@ -502,22 +531,12 @@ module aptos_framework::multisig_account {
     /// maliciously alter the owners list.
     entry fun add_owners(
         multisig_account: &signer, new_owners: vector
) acquires MultisigAccount {
-        // Short circuit if new owners list is empty.
-        // This avoids emitting an event if no changes happen, which is confusing to off-chain components.
-        if (vector::length(&new_owners) == 0) {
-            return
-        };
-
-        let multisig_address = address_of(multisig_account);
-        assert_multisig_account_exists(multisig_address);
-        let multisig_account_resource = borrow_global_mut(multisig_address);
-
-        vector::append(&mut multisig_account_resource.owners, new_owners);
-        // This will fail if an existing owner is added again.
-        validate_owners(&multisig_account_resource.owners, multisig_address);
-        emit_event(&mut multisig_account_resource.add_owners_events, AddOwnersEvent {
-            owners_added: new_owners,
-        });
+        update_owner_schema(
+            address_of(multisig_account),
+            new_owners,
+            vector[],
+            option::none()
+        );
     }
 
     /// Add owners then update number of signatures required, in a single operation.
@@ -526,8 +545,12 @@ module aptos_framework::multisig_account {
         new_owners: vector
,
         new_num_signatures_required: u64
     ) acquires MultisigAccount {
-        add_owners(multisig_account, new_owners);
-        update_signatures_required(multisig_account, new_num_signatures_required);
+        update_owner_schema(
+            address_of(multisig_account),
+            new_owners,
+            vector[],
+            option::some(new_num_signatures_required)
+        );
     }
 
     /// Similar to remove_owners, but only allow removing one owner.
@@ -545,47 +568,55 @@ module aptos_framework::multisig_account {
     /// maliciously alter the owners list.
     entry fun remove_owners(
         multisig_account: &signer, owners_to_remove: vector
) acquires MultisigAccount {
-        // Short circuit if the list of owners to remove is empty.
-        // This avoids emitting an event if no changes happen, which is confusing to off-chain components.
-        if (vector::length(&owners_to_remove) == 0) {
-            return
-        };
-
-        let multisig_address = address_of(multisig_account);
-        assert_multisig_account_exists(multisig_address);
-        let multisig_account_resource = borrow_global_mut(multisig_address);
+        update_owner_schema(
+            address_of(multisig_account),
+            vector[],
+            owners_to_remove,
+            option::none()
+        );
+    }
 
-        let owners = &mut multisig_account_resource.owners;
-        let owners_removed = vector::empty
();
-        vector::for_each_ref(&owners_to_remove, |owner_to_remove| {
-            let owner_to_remove = *owner_to_remove;
-            let (found, index) = vector::index_of(owners, &owner_to_remove);
-            // Only remove an owner if they're present in the owners list.
-            if (found) {
-                vector::push_back(&mut owners_removed, owner_to_remove);
-                vector::swap_remove(owners, index);
-            };
-        });
+    /// Swap an owner in for an old one, without changing required signatures.
+    entry fun swap_owner(
+        multisig_account: &signer,
+        to_swap_in: address,
+        to_swap_out: address
+    ) acquires MultisigAccount {
+        update_owner_schema(
+            address_of(multisig_account),
+            vector[to_swap_in],
+            vector[to_swap_out],
+            option::none()
+        );
+    }
 
-        // Make sure there's still at least as many owners as the number of signatures required.
-        // This also ensures that there's at least one owner left as signature threshold must be > 0.
-        assert!(
-            vector::length(owners) >= multisig_account_resource.num_signatures_required,
-            error::invalid_state(ENOT_ENOUGH_OWNERS),
+    /// Swap owners in and out, without changing required signatures.
+    entry fun swap_owners(
+        multisig_account: &signer,
+        to_swap_in: vector
,
+        to_swap_out: vector

+    ) acquires MultisigAccount {
+        update_owner_schema(
+            address_of(multisig_account),
+            to_swap_in,
+            to_swap_out,
+            option::none()
         );
-        if (vector::length(&owners_removed) > 0) {
-            emit_event(&mut multisig_account_resource.remove_owners_events, RemoveOwnersEvent { owners_removed });
-        }
     }
 
-    /// Update the number of signatures required then remove owners, in a single operation.
-    entry fun remove_owners_and_update_signatures_required(
+    /// Swap owners in and out, updating number of required signatures.
+    entry fun swap_owners_and_update_signatures_required(
         multisig_account: &signer,
+        new_owners: vector
,
         owners_to_remove: vector
,
         new_num_signatures_required: u64
     ) acquires MultisigAccount {
-        update_signatures_required(multisig_account, new_num_signatures_required);
-        remove_owners(multisig_account, owners_to_remove);
+        update_owner_schema(
+            address_of(multisig_account),
+            new_owners,
+            owners_to_remove,
+            option::some(new_num_signatures_required)
+        );
     }
 
     /// Update the number of signatures required to execute transaction in the specified multisig account.
@@ -596,28 +627,11 @@ module aptos_framework::multisig_account {
     /// maliciously alter the number of signatures required.
     entry fun update_signatures_required(
         multisig_account: &signer, new_num_signatures_required: u64) acquires MultisigAccount {
-        let multisig_address = address_of(multisig_account);
-        assert_multisig_account_exists(multisig_address);
-        let multisig_account_resource = borrow_global_mut(multisig_address);
-        // Short-circuit if the new number of signatures required is the same as before.
-        // This avoids emitting an event.
-        if (multisig_account_resource.num_signatures_required == new_num_signatures_required) {
-            return
-        };
-        let num_owners = vector::length(&multisig_account_resource.owners);
-        assert!(
-            new_num_signatures_required > 0 && new_num_signatures_required <= num_owners,
-            error::invalid_argument(EINVALID_SIGNATURES_REQUIRED),
-        );
-
-        let old_num_signatures_required = multisig_account_resource.num_signatures_required;
-        multisig_account_resource.num_signatures_required = new_num_signatures_required;
-        emit_event(
-            &mut multisig_account_resource.update_signature_required_events,
-            UpdateSignaturesRequiredEvent {
-                old_num_signatures_required,
-                new_num_signatures_required,
-            }
+        update_owner_schema(
+            address_of(multisig_account),
+            vector[],
+            vector[],
+            option::some(new_num_signatures_required)
         );
     }
 
@@ -959,6 +973,88 @@ module aptos_framework::multisig_account {
         assert!(exists(multisig_account), error::invalid_state(EACCOUNT_NOT_MULTISIG));
     }
 
+    /// Add new owners, remove owners to remove, update signatures required.
+    fun update_owner_schema(
+        multisig_address: address,
+        new_owners: vector
,
+        owners_to_remove: vector
,
+        optional_new_num_signatures_required: Option,
+    ) acquires MultisigAccount {
+        assert_multisig_account_exists(multisig_address);
+        let multisig_account_ref_mut =
+            borrow_global_mut(multisig_address);
+        // Verify no overlap between new owners and owners to remove.
+        vector::for_each_ref(&new_owners, |new_owner_ref| {
+            assert!(
+                !vector::contains(&owners_to_remove, new_owner_ref),
+                error::invalid_argument(EOWNERS_TO_REMOVE_NEW_OWNERS_OVERLAP)
+            )
+        });
+        // If new owners provided, try to add them and emit an event.
+        if (vector::length(&new_owners) > 0) {
+            vector::append(&mut multisig_account_ref_mut.owners, new_owners);
+            validate_owners(
+                &multisig_account_ref_mut.owners,
+                multisig_address
+            );
+            emit_event(
+                &mut multisig_account_ref_mut.add_owners_events,
+                AddOwnersEvent { owners_added: new_owners }
+            );
+        };
+        // If owners to remove provided, try to remove them.
+        if (vector::length(&owners_to_remove) > 0) {
+            let owners_ref_mut = &mut multisig_account_ref_mut.owners;
+            let owners_removed = vector[];
+            vector::for_each_ref(&owners_to_remove, |owner_to_remove_ref| {
+                let (found, index) =
+                    vector::index_of(owners_ref_mut, owner_to_remove_ref);
+                if (found) {
+                    vector::push_back(
+                        &mut owners_removed,
+                        vector::swap_remove(owners_ref_mut, index)
+                    );
+                }
+            });
+            // Only emit event if owner(s) actually removed.
+            if (vector::length(&owners_removed) > 0) {
+                emit_event(
+                    &mut multisig_account_ref_mut.remove_owners_events,
+                    RemoveOwnersEvent { owners_removed }
+                );
+            }
+        };
+        // If new signature count provided, try to update count.
+        if (option::is_some(&optional_new_num_signatures_required)) {
+            let new_num_signatures_required =
+                option::extract(&mut optional_new_num_signatures_required);
+            assert!(
+                new_num_signatures_required > 0,
+                error::invalid_argument(EINVALID_SIGNATURES_REQUIRED)
+            );
+            let old_num_signatures_required =
+                multisig_account_ref_mut.num_signatures_required;
+            // Only apply update and emit event if a change indicated.
+            if (new_num_signatures_required != old_num_signatures_required) {
+                multisig_account_ref_mut.num_signatures_required =
+                    new_num_signatures_required;
+                emit_event(
+                    &mut multisig_account_ref_mut.update_signature_required_events,
+                    UpdateSignaturesRequiredEvent {
+                        old_num_signatures_required,
+                        new_num_signatures_required,
+                    }
+                );
+            }
+        };
+        // Verify number of owners.
+        let num_owners = vector::length(&multisig_account_ref_mut.owners);
+        assert!(
+            num_owners >= multisig_account_ref_mut.num_signatures_required,
+            error::invalid_state(ENOT_ENOUGH_OWNERS)
+        );
+    }
+
     ////////////////////////// Tests ///////////////////////////////
 
     #[test_only]
@@ -1214,7 +1310,7 @@ module aptos_framework::multisig_account {
     }
 
     #[test(owner = @0x123)]
-    #[expected_failure(abort_code = 0x1000B, location = Self)]
+    #[expected_failure(abort_code = 0x30005, location = Self)]
     public entry fun test_update_with_too_many_signatures_required_should_fail(
         owner: &signer) acquires MultisigAccount {
         setup();
@@ -1630,4 +1726,36 @@ module aptos_framework::multisig_account {
         reject_transaction(owner_2, multisig_account, 1);
         execute_rejected_transaction(owner_3, multisig_account);
     }
+
+    #[test(
+        owner_1 = @0x123,
+        owner_2 = @0x124,
+        owner_3 = @0x125
+    )]
+    #[expected_failure(abort_code = 0x10012, location = Self)]
+    fun test_update_owner_schema_overlap_should_fail(
+        owner_1: &signer,
+        owner_2: &signer,
+        owner_3: &signer
+    ) acquires MultisigAccount {
+        setup();
+        let owner_1_addr = address_of(owner_1);
+        let owner_2_addr = address_of(owner_2);
+        let owner_3_addr = address_of(owner_3);
+        create_account(owner_1_addr);
+        let multisig_address = get_next_multisig_account_address(owner_1_addr);
+        create_with_owners(
+            owner_1,
+            vector[owner_2_addr, owner_3_addr],
+            2,
+            vector[],
+            vector[]
+        );
+        update_owner_schema(
+            multisig_address,
+            vector[owner_1_addr],
+            vector[owner_1_addr],
+            option::none()
+        );
+    }
 }
diff --git a/aptos-move/framework/cached-packages/src/aptos_framework_sdk_builder.rs b/aptos-move/framework/cached-packages/src/aptos_framework_sdk_builder.rs
index 8cade781a1858..815f0efdc626d 100644
--- a/aptos-move/framework/cached-packages/src/aptos_framework_sdk_builder.rs
+++ b/aptos-move/framework/cached-packages/src/aptos_framework_sdk_builder.rs
@@ -399,6 +399,17 @@ pub enum EntryFunctionCall {
         metadata_values: Vec>,
     },
 
+    /// Like `create_with_owners`, but removes the calling account after creation.
+    ///
+    /// This is for creating a vanity multisig account from a bootstrapping account that should not
+    /// be an owner after the vanity multisig address has been secured.
+    MultisigAccountCreateWithOwnersThenRemoveBootstrapper {
+        owners: Vec,
+        num_signatures_required: u64,
+        metadata_keys: Vec>,
+        metadata_values: Vec>,
+    },
+
     /// Remove the next transaction if it has sufficient owner rejections.
     MultisigAccountExecuteRejectedTransaction {
         multisig_account: AccountAddress,
@@ -426,8 +437,21 @@ pub enum EntryFunctionCall {
         owners_to_remove: Vec,
     },
 
-    /// Update the number of signatures required then remove owners, in a single operation.
-    MultisigAccountRemoveOwnersAndUpdateSignaturesRequired {
+    /// Swap an owner in for an old one, without changing required signatures.
+    MultisigAccountSwapOwner {
+        to_swap_in: AccountAddress,
+        to_swap_out: AccountAddress,
+    },
+
+    /// Swap owners in and out, without changing required signatures.
+    MultisigAccountSwapOwners {
+        to_swap_in: Vec,
+        to_swap_out: Vec,
+    },
+
+    /// Swap owners in and out, updating number of required signatures.
+    MultisigAccountSwapOwnersAndUpdateSignaturesRequired {
+        new_owners: Vec,
         owners_to_remove: Vec,
         new_num_signatures_required: u64,
     },
@@ -1005,6 +1029,17 @@ impl EntryFunctionCall {
                 metadata_keys,
                 metadata_values,
             ),
+            MultisigAccountCreateWithOwnersThenRemoveBootstrapper {
+                owners,
+                num_signatures_required,
+                metadata_keys,
+                metadata_values,
+            } => multisig_account_create_with_owners_then_remove_bootstrapper(
+                owners,
+                num_signatures_required,
+                metadata_keys,
+                metadata_values,
+            ),
             MultisigAccountExecuteRejectedTransaction { multisig_account } => {
                 multisig_account_execute_rejected_transaction(multisig_account)
             },
@@ -1018,10 +1053,20 @@ impl EntryFunctionCall {
             MultisigAccountRemoveOwners { owners_to_remove } => {
                 multisig_account_remove_owners(owners_to_remove)
             },
-            MultisigAccountRemoveOwnersAndUpdateSignaturesRequired {
+            MultisigAccountSwapOwner {
+                to_swap_in,
+                to_swap_out,
+            } => multisig_account_swap_owner(to_swap_in, to_swap_out),
+            MultisigAccountSwapOwners {
+                to_swap_in,
+                to_swap_out,
+            } => multisig_account_swap_owners(to_swap_in, to_swap_out),
+            MultisigAccountSwapOwnersAndUpdateSignaturesRequired {
+                new_owners,
                 owners_to_remove,
                 new_num_signatures_required,
-            } => multisig_account_remove_owners_and_update_signatures_required(
+            } => multisig_account_swap_owners_and_update_signatures_required(
+                new_owners,
                 owners_to_remove,
                 new_num_signatures_required,
             ),
@@ -2254,6 +2299,35 @@ pub fn multisig_account_create_with_owners(
     ))
 }
 
+/// Like `create_with_owners`, but removes the calling account after creation.
+///
+/// This is for creating a vanity multisig account from a bootstrapping account that should not
+/// be an owner after the vanity multisig address has been secured.
+pub fn multisig_account_create_with_owners_then_remove_bootstrapper(
+    owners: Vec,
+    num_signatures_required: u64,
+    metadata_keys: Vec>,
+    metadata_values: Vec>,
+) -> TransactionPayload {
+    TransactionPayload::EntryFunction(EntryFunction::new(
+        ModuleId::new(
+            AccountAddress::new([
+                0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+                0, 0, 0, 1,
+            ]),
+            ident_str!("multisig_account").to_owned(),
+        ),
+        ident_str!("create_with_owners_then_remove_bootstrapper").to_owned(),
+        vec![],
+        vec![
+            bcs::to_bytes(&owners).unwrap(),
+            bcs::to_bytes(&num_signatures_required).unwrap(),
+            bcs::to_bytes(&metadata_keys).unwrap(),
+            bcs::to_bytes(&metadata_values).unwrap(),
+        ],
+    ))
+}
+
 /// Remove the next transaction if it has sufficient owner rejections.
 pub fn multisig_account_execute_rejected_transaction(
     multisig_account: AccountAddress,
@@ -2332,8 +2406,53 @@ pub fn multisig_account_remove_owners(owners_to_remove: Vec) ->
     ))
 }
 
-/// Update the number of signatures required then remove owners, in a single operation.
-pub fn multisig_account_remove_owners_and_update_signatures_required(
+/// Swap an owner in for an old one, without changing required signatures.
+pub fn multisig_account_swap_owner(
+    to_swap_in: AccountAddress,
+    to_swap_out: AccountAddress,
+) -> TransactionPayload {
+    TransactionPayload::EntryFunction(EntryFunction::new(
+        ModuleId::new(
+            AccountAddress::new([
+                0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+                0, 0, 0, 1,
+            ]),
+            ident_str!("multisig_account").to_owned(),
+        ),
+        ident_str!("swap_owner").to_owned(),
+        vec![],
+        vec![
+            bcs::to_bytes(&to_swap_in).unwrap(),
+            bcs::to_bytes(&to_swap_out).unwrap(),
+        ],
+    ))
+}
+
+/// Swap owners in and out, without changing required signatures.
+pub fn multisig_account_swap_owners(
+    to_swap_in: Vec,
+    to_swap_out: Vec,
+) -> TransactionPayload {
+    TransactionPayload::EntryFunction(EntryFunction::new(
+        ModuleId::new(
+            AccountAddress::new([
+                0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+                0, 0, 0, 1,
+            ]),
+            ident_str!("multisig_account").to_owned(),
+        ),
+        ident_str!("swap_owners").to_owned(),
+        vec![],
+        vec![
+            bcs::to_bytes(&to_swap_in).unwrap(),
+            bcs::to_bytes(&to_swap_out).unwrap(),
+        ],
+    ))
+}
+
+/// Swap owners in and out, updating number of required signatures.
+pub fn multisig_account_swap_owners_and_update_signatures_required(
+    new_owners: Vec,
     owners_to_remove: Vec,
     new_num_signatures_required: u64,
 ) -> TransactionPayload {
@@ -2345,9 +2464,10 @@ pub fn multisig_account_remove_owners_and_update_signatures_required(
             ]),
             ident_str!("multisig_account").to_owned(),
         ),
-        ident_str!("remove_owners_and_update_signatures_required").to_owned(),
+        ident_str!("swap_owners_and_update_signatures_required").to_owned(),
         vec![],
         vec![
+            bcs::to_bytes(&new_owners).unwrap(),
             bcs::to_bytes(&owners_to_remove).unwrap(),
             bcs::to_bytes(&new_num_signatures_required).unwrap(),
         ],
@@ -4049,6 +4169,23 @@ mod decoder {
         }
     }
 
+    pub fn multisig_account_create_with_owners_then_remove_bootstrapper(
+        payload: &TransactionPayload,
+    ) -> Option {
+        if let TransactionPayload::EntryFunction(script) = payload {
+            Some(
+                EntryFunctionCall::MultisigAccountCreateWithOwnersThenRemoveBootstrapper {
+                    owners: bcs::from_bytes(script.args().get(0)?).ok()?,
+                    num_signatures_required: bcs::from_bytes(script.args().get(1)?).ok()?,
+                    metadata_keys: bcs::from_bytes(script.args().get(2)?).ok()?,
+                    metadata_values: bcs::from_bytes(script.args().get(3)?).ok()?,
+                },
+            )
+        } else {
+            None
+        }
+    }
+
     pub fn multisig_account_execute_rejected_transaction(
         payload: &TransactionPayload,
     ) -> Option {
@@ -4100,14 +4237,37 @@ mod decoder {
         }
     }
 
-    pub fn multisig_account_remove_owners_and_update_signatures_required(
+    pub fn multisig_account_swap_owner(payload: &TransactionPayload) -> Option {
+        if let TransactionPayload::EntryFunction(script) = payload {
+            Some(EntryFunctionCall::MultisigAccountSwapOwner {
+                to_swap_in: bcs::from_bytes(script.args().get(0)?).ok()?,
+                to_swap_out: bcs::from_bytes(script.args().get(1)?).ok()?,
+            })
+        } else {
+            None
+        }
+    }
+
+    pub fn multisig_account_swap_owners(payload: &TransactionPayload) -> Option {
+        if let TransactionPayload::EntryFunction(script) = payload {
+            Some(EntryFunctionCall::MultisigAccountSwapOwners {
+                to_swap_in: bcs::from_bytes(script.args().get(0)?).ok()?,
+                to_swap_out: bcs::from_bytes(script.args().get(1)?).ok()?,
+            })
+        } else {
+            None
+        }
+    }
+
+    pub fn multisig_account_swap_owners_and_update_signatures_required(
         payload: &TransactionPayload,
     ) -> Option {
         if let TransactionPayload::EntryFunction(script) = payload {
             Some(
-                EntryFunctionCall::MultisigAccountRemoveOwnersAndUpdateSignaturesRequired {
-                    owners_to_remove: bcs::from_bytes(script.args().get(0)?).ok()?,
-                    new_num_signatures_required: bcs::from_bytes(script.args().get(1)?).ok()?,
+                EntryFunctionCall::MultisigAccountSwapOwnersAndUpdateSignaturesRequired {
+                    new_owners: bcs::from_bytes(script.args().get(0)?).ok()?,
+                    owners_to_remove: bcs::from_bytes(script.args().get(1)?).ok()?,
+                    new_num_signatures_required: bcs::from_bytes(script.args().get(2)?).ok()?,
                 },
             )
         } else {
@@ -4969,6 +5129,10 @@ static SCRIPT_FUNCTION_DECODER_MAP: once_cell::sync::Lazy
Date: Tue, 6 Jun 2023 17:48:24 -0400
Subject: [PATCH 081/200] [TF] Disable the monitoring Helm chart by default
 (#8546)

---
 terraform/aptos-node-testnet/aws/variables.tf | 6 +++---
 terraform/aptos-node-testnet/gcp/variables.tf | 4 ++--
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/terraform/aptos-node-testnet/aws/variables.tf b/terraform/aptos-node-testnet/aws/variables.tf
index c9d58a14ae6cd..d1257333dca9a 100644
--- a/terraform/aptos-node-testnet/aws/variables.tf
+++ b/terraform/aptos-node-testnet/aws/variables.tf
@@ -113,7 +113,7 @@ variable "logger_helm_values" {
 
 variable "enable_monitoring" {
   description = "Enable monitoring helm chart"
-  default     = true
+  default     = false
 }
 
 variable "monitoring_helm_values" {
@@ -124,12 +124,12 @@ variable "monitoring_helm_values" {
 
 variable "enable_prometheus_node_exporter" {
   description = "Enable prometheus-node-exporter within monitoring helm chart"
-  default     = true
+  default     = false
 }
 
 variable "enable_kube_state_metrics" {
   description = "Enable kube-state-metrics within monitoring helm chart"
-  default     = true
+  default     = false
 }
 
 variable "testnet_addons_helm_values" {
diff --git a/terraform/aptos-node-testnet/gcp/variables.tf b/terraform/aptos-node-testnet/gcp/variables.tf
index 1daff33e24e02..4ab008b1328dc 100644
--- a/terraform/aptos-node-testnet/gcp/variables.tf
+++ b/terraform/aptos-node-testnet/gcp/variables.tf
@@ -154,7 +154,7 @@ variable "enable_forge" {
 
 variable "enable_monitoring" {
   description = "Enable monitoring helm chart"
-  default     = true
+  default     = false
 }
 
 variable "monitoring_helm_values" {
@@ -165,7 +165,7 @@ variable "monitoring_helm_values" {
 
 variable "enable_prometheus_node_exporter" {
   description = "Enable prometheus-node-exporter within monitoring helm chart"
-  default     = true
+  default     = false
 }
 
 ### Autoscaling

From 005aca2ae22a1200871c4679b606c84210fdfb94 Mon Sep 17 00:00:00 2001
From: Sital Kedia 
Date: Tue, 6 Jun 2023 17:08:11 -0700
Subject: [PATCH 082/200] [Sharding] [Execution] Add support for Analyzed txn
 and sharded graph partitioning (#8323)

---
 Cargo.lock                                    |  20 +
 Cargo.toml                                    |   2 +
 aptos-move/aptos-vm/Cargo.toml                |   2 +
 .../src/sharded_block_executor/mod.rs         |   7 +-
 execution/block-partitioner/Cargo.toml        |  31 +
 .../block-partitioner/src/lib.rs              |   5 +
 execution/block-partitioner/src/main.rs       |  61 ++
 .../conflict_detector.rs                      | 190 +++++
 .../dependency_analysis.rs                    |  88 +++
 .../src/sharded_block_partitioner/messages.rs |  84 +++
 .../src/sharded_block_partitioner/mod.rs      | 657 ++++++++++++++++++
 .../partitioning_shard.rs                     | 242 +++++++
 execution/block-partitioner/src/test_utils.rs |  81 +++
 execution/block-partitioner/src/types.rs      | 109 +++
 execution/executor-benchmark/src/main.rs      |  11 +-
 .../executor/src/components/chunk_output.rs   |   6 +-
 types/src/transaction/analyzed_transaction.rs | 224 ++++++
 types/src/transaction/mod.rs                  |   1 +
 18 files changed, 1810 insertions(+), 11 deletions(-)
 create mode 100644 execution/block-partitioner/Cargo.toml
 rename aptos-move/aptos-vm/src/sharded_block_executor/block_partitioner.rs => execution/block-partitioner/src/lib.rs (93%)
 create mode 100644 execution/block-partitioner/src/main.rs
 create mode 100644 execution/block-partitioner/src/sharded_block_partitioner/conflict_detector.rs
 create mode 100644 execution/block-partitioner/src/sharded_block_partitioner/dependency_analysis.rs
 create mode 100644 execution/block-partitioner/src/sharded_block_partitioner/messages.rs
 create mode 100644 execution/block-partitioner/src/sharded_block_partitioner/mod.rs
 create mode 100644 execution/block-partitioner/src/sharded_block_partitioner/partitioning_shard.rs
 create mode 100644 execution/block-partitioner/src/test_utils.rs
 create mode 100644 execution/block-partitioner/src/types.rs
 create mode 100644 types/src/transaction/analyzed_transaction.rs

diff --git a/Cargo.lock b/Cargo.lock
index dd3cb7a035006..d3f77026e59b0 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -481,6 +481,24 @@ dependencies = [
  "rayon",
 ]
 
+[[package]]
+name = "aptos-block-partitioner"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "aptos-crypto",
+ "aptos-logger",
+ "aptos-metrics-core",
+ "aptos-types",
+ "bcs 0.1.4",
+ "clap 3.2.23",
+ "dashmap",
+ "itertools",
+ "move-core-types",
+ "rand 0.7.3",
+ "rayon",
+]
+
 [[package]]
 name = "aptos-bounded-executor"
 version = "0.1.0"
@@ -3341,6 +3359,7 @@ dependencies = [
  "anyhow",
  "aptos-aggregator",
  "aptos-block-executor",
+ "aptos-block-partitioner",
  "aptos-crypto",
  "aptos-crypto-derive",
  "aptos-framework",
@@ -3372,6 +3391,7 @@ dependencies = [
  "once_cell",
  "ouroboros 0.15.6",
  "proptest",
+ "rand 0.7.3",
  "rayon",
  "serde 1.0.149",
  "serde_json",
diff --git a/Cargo.toml b/Cargo.toml
index 7f7b71f328159..d603a65c4a5cb 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -100,6 +100,7 @@ members = [
     "ecosystem/indexer-grpc/indexer-grpc-utils",
     "ecosystem/node-checker",
     "ecosystem/node-checker/fn-check-client",
+    "execution/block-partitioner",
     "execution/db-bootstrapper",
     "execution/executor",
     "execution/executor-benchmark",
@@ -272,6 +273,7 @@ aptos-debugger = { path = "aptos-move/aptos-debugger" }
 aptos-event-notifications = { path = "state-sync/inter-component/event-notifications" }
 aptos-executable-store = { path = "storage/executable-store" }
 aptos-executor = { path = "execution/executor" }
+aptos-block-partitioner = { path = "execution/block-partitioner" }
 aptos-executor-test-helpers = { path = "execution/executor-test-helpers" }
 aptos-executor-types = { path = "execution/executor-types" }
 aptos-faucet-cli = { path = "crates/aptos-faucet/cli" }
diff --git a/aptos-move/aptos-vm/Cargo.toml b/aptos-move/aptos-vm/Cargo.toml
index cf2238385084d..b1c2423e953d6 100644
--- a/aptos-move/aptos-vm/Cargo.toml
+++ b/aptos-move/aptos-vm/Cargo.toml
@@ -16,6 +16,7 @@ rust-version = { workspace = true }
 anyhow = { workspace = true }
 aptos-aggregator = { workspace = true }
 aptos-block-executor = { workspace = true }
+aptos-block-partitioner = { workspace = true }
 aptos-crypto = { workspace = true }
 aptos-crypto-derive = { workspace = true }
 aptos-framework =  { workspace = true }
@@ -45,6 +46,7 @@ move-vm-types = { workspace = true }
 num_cpus = { workspace = true }
 once_cell = { workspace = true }
 ouroboros = { workspace = true }
+rand = { workspace = true }
 rayon = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
diff --git a/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs b/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs
index 3537e08dbba5e..5bd0b0fb4b986 100644
--- a/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs
+++ b/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs
@@ -2,10 +2,8 @@
 // Parts of the project are originally copyright © Meta Platforms, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-use crate::sharded_block_executor::{
-    block_partitioner::{BlockPartitioner, UniformPartitioner},
-    executor_shard::ExecutorShard,
-};
+use crate::sharded_block_executor::executor_shard::ExecutorShard;
+use aptos_block_partitioner::{BlockPartitioner, UniformPartitioner};
 use aptos_logger::{error, info, trace};
 use aptos_state_view::StateView;
 use aptos_types::transaction::{Transaction, TransactionOutput};
@@ -19,7 +17,6 @@ use std::{
     thread,
 };
 
-mod block_partitioner;
 mod executor_shard;
 
 /// A wrapper around sharded block executors that manages multiple shards and aggregates the results.
diff --git a/execution/block-partitioner/Cargo.toml b/execution/block-partitioner/Cargo.toml
new file mode 100644
index 0000000000000..9a800231d3f8c
--- /dev/null
+++ b/execution/block-partitioner/Cargo.toml
@@ -0,0 +1,31 @@
+[package]
+name = "aptos-block-partitioner"
+description = "A tool to partition a block store into smaller chunks based on graph partitioning."
+
+version = "0.1.0"
+
+# Workspace inherited keys
+authors = { workspace = true }
+edition = { workspace = true }
+homepage = { workspace = true }
+license = { workspace = true }
+publish = { workspace = true }
+repository = { workspace = true }
+rust-version = { workspace = true }
+
+[dependencies]
+anyhow = { workspace = true }
+aptos-crypto = { workspace = true }
+aptos-logger = { workspace = true }
+aptos-metrics-core = { workspace = true }
+aptos-types = { workspace = true }
+bcs = { workspace = true }
+clap = { workspace = true }
+dashmap = { workspace = true }
+itertools = { workspace = true }
+move-core-types = { workspace = true }
+rand = { workspace = true }
+rayon = { workspace = true }
+
+[features]
+default = []
diff --git a/aptos-move/aptos-vm/src/sharded_block_executor/block_partitioner.rs b/execution/block-partitioner/src/lib.rs
similarity index 93%
rename from aptos-move/aptos-vm/src/sharded_block_executor/block_partitioner.rs
rename to execution/block-partitioner/src/lib.rs
index b05dd053ac463..da04fc2c2be7b 100644
--- a/aptos-move/aptos-vm/src/sharded_block_executor/block_partitioner.rs
+++ b/execution/block-partitioner/src/lib.rs
@@ -1,6 +1,11 @@
 // Copyright © Aptos Foundation
 // Parts of the project are originally copyright © Meta Platforms, Inc.
 // SPDX-License-Identifier: Apache-2.0
+
+pub mod sharded_block_partitioner;
+pub mod test_utils;
+pub mod types;
+
 use aptos_types::transaction::Transaction;
 
 pub trait BlockPartitioner: Send + Sync {
diff --git a/execution/block-partitioner/src/main.rs b/execution/block-partitioner/src/main.rs
new file mode 100644
index 0000000000000..f7be700334916
--- /dev/null
+++ b/execution/block-partitioner/src/main.rs
@@ -0,0 +1,61 @@
+// Copyright © Aptos Foundation
+
+use aptos_block_partitioner::{
+    sharded_block_partitioner::ShardedBlockPartitioner,
+    test_utils::{create_signed_p2p_transaction, generate_test_account, TestAccount},
+};
+use aptos_types::transaction::analyzed_transaction::AnalyzedTransaction;
+use clap::Parser;
+use rand::rngs::OsRng;
+use rayon::iter::{IntoParallelIterator, ParallelIterator};
+use std::{sync::Mutex, time::Instant};
+
+#[derive(Debug, Parser)]
+struct Args {
+    #[clap(long, default_value = "2000000")]
+    pub num_accounts: usize,
+
+    #[clap(long, default_value = "100000")]
+    pub block_size: usize,
+
+    #[clap(long, default_value = "10")]
+    pub num_blocks: usize,
+
+    #[clap(long, default_value = "12")]
+    pub num_shards: usize,
+}
+
+fn main() {
+    println!("Starting the block partitioning benchmark");
+    let args = Args::parse();
+    let num_accounts = args.num_accounts;
+    println!("Creating {} accounts", num_accounts);
+    let accounts: Vec> = (0..num_accounts)
+        .into_par_iter()
+        .map(|_i| Mutex::new(generate_test_account()))
+        .collect();
+    println!("Created {} accounts", num_accounts);
+    println!("Creating {} transactions", args.block_size);
+    let transactions: Vec = (0..args.block_size)
+        .into_iter()
+        .map(|_| {
+            // randomly select a sender and receiver from accounts
+            let mut rng = OsRng;
+
+            let indices = rand::seq::index::sample(&mut rng, num_accounts, 2);
+            let receiver = accounts[indices.index(1)].lock().unwrap();
+            let mut sender = accounts[indices.index(0)].lock().unwrap();
+            create_signed_p2p_transaction(&mut sender, vec![&receiver]).remove(0)
+        })
+        .collect();
+
+    let partitioner = ShardedBlockPartitioner::new(args.num_shards);
+    for _ in 0..args.num_blocks {
+        let transactions = transactions.clone();
+        println!("Starting to partition");
+        let now = Instant::now();
+        partitioner.partition(transactions, 1);
+        let elapsed = now.elapsed();
+        println!("Time taken to partition: {:?}", elapsed);
+    }
+}
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/conflict_detector.rs b/execution/block-partitioner/src/sharded_block_partitioner/conflict_detector.rs
new file mode 100644
index 0000000000000..577e7d3a11685
--- /dev/null
+++ b/execution/block-partitioner/src/sharded_block_partitioner/conflict_detector.rs
@@ -0,0 +1,190 @@
+// Copyright © Aptos Foundation
+
+use crate::{
+    sharded_block_partitioner::dependency_analysis::{RWSet, WriteSetWithTxnIndex},
+    types::{CrossShardDependencies, ShardId, SubBlock, TransactionWithDependencies, TxnIndex},
+};
+use aptos_types::transaction::analyzed_transaction::{AnalyzedTransaction, StorageLocation};
+use std::{
+    collections::hash_map::DefaultHasher,
+    hash::{Hash, Hasher},
+    sync::Arc,
+};
+
+pub struct CrossShardConflictDetector {
+    shard_id: ShardId,
+    num_shards: usize,
+}
+
+impl CrossShardConflictDetector {
+    pub fn new(shard_id: ShardId, num_shards: usize) -> Self {
+        Self {
+            shard_id,
+            num_shards,
+        }
+    }
+
+    pub fn discard_txns_with_cross_shard_deps(
+        &mut self,
+        txns: Vec,
+        cross_shard_rw_set: &[RWSet],
+        prev_rounds_rw_set_with_index: Arc>,
+    ) -> (
+        Vec,
+        Vec,
+        Vec,
+    ) {
+        // Iterate through all the transactions and if any shard has taken read/write lock on the storage location
+        // and has a higher priority than this shard id, then this transaction needs to be moved to the end of the block.
+        let mut accepted_txns = Vec::new();
+        let mut accepted_txn_dependencies = Vec::new();
+        let mut rejected_txns = Vec::new();
+        for (_, txn) in txns.into_iter().enumerate() {
+            if self.check_for_cross_shard_conflict(self.shard_id, &txn, cross_shard_rw_set) {
+                rejected_txns.push(txn);
+            } else {
+                accepted_txn_dependencies.push(self.get_dependencies_for_frozen_txn(
+                    &txn,
+                    Arc::new(vec![]),
+                    prev_rounds_rw_set_with_index.clone(),
+                ));
+                accepted_txns.push(txn);
+            }
+        }
+        (accepted_txns, accepted_txn_dependencies, rejected_txns)
+    }
+
+    /// Adds a cross shard dependency for a transaction. This can be done by finding the maximum transaction index
+    /// that has taken a read/write lock on the storage location the current transaction is trying to read/write.
+    /// We traverse the current round read/write set in reverse order starting from shard id -1 and look for the first
+    /// txn index that has taken a read/write lock on the storage location. If we can't find any such txn index, we
+    /// traverse the previous rounds read/write set in reverse order and look for the first txn index that has taken
+    /// a read/write lock on the storage location.
+    fn get_dependencies_for_frozen_txn(
+        &self,
+        frozen_txn: &AnalyzedTransaction,
+        current_round_rw_set_with_index: Arc>,
+        prev_rounds_rw_set_with_index: Arc>,
+    ) -> CrossShardDependencies {
+        if current_round_rw_set_with_index.is_empty() && prev_rounds_rw_set_with_index.is_empty() {
+            return CrossShardDependencies::default();
+        }
+        // Iterate through the frozen dependencies and add the max transaction index for each storage location
+        let mut cross_shard_dependencies = CrossShardDependencies::default();
+        for storage_location in frozen_txn
+            .read_hints()
+            .iter()
+            .chain(frozen_txn.write_hints().iter())
+        {
+            // For current round, iterate through all shards less than current shards in the reverse order and for previous rounds iterate through all shards in the reverse order
+            // and find the first shard id that has taken a write lock on the storage location. This ensures that we find the highest txn index that is conflicting
+            // with the current transaction. Please note that since we use a multi-version database, there is no conflict if any previous txn index has taken
+            // a read lock on the storage location.
+            for rw_set_with_index in current_round_rw_set_with_index
+                .iter()
+                .take(self.shard_id)
+                .rev()
+                .chain(prev_rounds_rw_set_with_index.iter().rev())
+            {
+                if rw_set_with_index.has_write_lock(storage_location) {
+                    cross_shard_dependencies.add_depends_on_txn(
+                        rw_set_with_index.get_write_lock_txn_index(storage_location),
+                    );
+                    break;
+                }
+            }
+        }
+
+        cross_shard_dependencies
+    }
+
+    pub fn get_frozen_sub_block(
+        &self,
+        txns: Vec,
+        current_round_rw_set_with_index: Arc>,
+        prev_round_rw_set_with_index: Arc>,
+        index_offset: TxnIndex,
+    ) -> SubBlock {
+        let mut frozen_txns = Vec::new();
+        for txn in txns.into_iter() {
+            let dependency = self.get_dependencies_for_frozen_txn(
+                &txn,
+                current_round_rw_set_with_index.clone(),
+                prev_round_rw_set_with_index.clone(),
+            );
+            frozen_txns.push(TransactionWithDependencies::new(txn, dependency));
+        }
+        SubBlock::new(index_offset, frozen_txns)
+    }
+
+    fn check_for_cross_shard_conflict(
+        &self,
+        current_shard_id: ShardId,
+        txn: &AnalyzedTransaction,
+        cross_shard_rw_set: &[RWSet],
+    ) -> bool {
+        if self.check_for_read_conflict(current_shard_id, txn, cross_shard_rw_set) {
+            return true;
+        }
+        if self.check_for_write_conflict(current_shard_id, txn, cross_shard_rw_set) {
+            return true;
+        }
+        false
+    }
+
+    fn get_anchor_shard_id(&self, storage_location: &StorageLocation) -> ShardId {
+        let mut hasher = DefaultHasher::new();
+        storage_location.hash(&mut hasher);
+        (hasher.finish() % self.num_shards as u64) as usize
+    }
+
+    fn check_for_read_conflict(
+        &self,
+        current_shard_id: ShardId,
+        txn: &AnalyzedTransaction,
+        cross_shard_rw_set: &[RWSet],
+    ) -> bool {
+        for read_location in txn.read_hints().iter() {
+            // Each storage location is allocated an anchor shard id, which is used to conflict resolution deterministically across shards.
+            // During conflict resolution, shards starts scanning from the anchor shard id and
+            // first shard id that has taken a read/write lock on this storage location is the owner of this storage location.
+            // Please note another alternative is scan from first shard id, but this will result in non-uniform load across shards in case of conflicts.
+            let anchor_shard_id = self.get_anchor_shard_id(read_location);
+            for offset in 0..self.num_shards {
+                let shard_id = (anchor_shard_id + offset) % self.num_shards;
+                // Ignore if this is from the same shard
+                if shard_id == current_shard_id {
+                    // We only need to check if any shard id < current shard id has taken a write lock on the storage location
+                    break;
+                }
+                if cross_shard_rw_set[shard_id].has_write_lock(read_location) {
+                    return true;
+                }
+            }
+        }
+        false
+    }
+
+    fn check_for_write_conflict(
+        &self,
+        current_shard_id: usize,
+        txn: &AnalyzedTransaction,
+        cross_shard_rw_set: &[RWSet],
+    ) -> bool {
+        for write_location in txn.write_hints().iter() {
+            let anchor_shard_id = self.get_anchor_shard_id(write_location);
+            for offset in 0..self.num_shards {
+                let shard_id = (anchor_shard_id + offset) % self.num_shards;
+                // Ignore if this is from the same shard
+                if shard_id == current_shard_id {
+                    // We only need to check if any shard id < current shard id has taken a write lock on the storage location
+                    break;
+                }
+                if cross_shard_rw_set[shard_id].has_read_or_write_lock(write_location) {
+                    return true;
+                }
+            }
+        }
+        false
+    }
+}
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/dependency_analysis.rs b/execution/block-partitioner/src/sharded_block_partitioner/dependency_analysis.rs
new file mode 100644
index 0000000000000..7da289c06611e
--- /dev/null
+++ b/execution/block-partitioner/src/sharded_block_partitioner/dependency_analysis.rs
@@ -0,0 +1,88 @@
+// Copyright © Aptos Foundation
+
+use crate::types::TxnIndex;
+use aptos_types::transaction::analyzed_transaction::{AnalyzedTransaction, StorageLocation};
+use std::{
+    collections::{HashMap, HashSet},
+    sync::Arc,
+};
+
+#[derive(Default, Clone, Debug)]
+pub struct RWSet {
+    // Represents a set of storage locations that are read by the transactions in this shard.
+    read_set: Arc>,
+    // Represents a set of storage locations that are written by the transactions in this shard.
+    write_set: Arc>,
+}
+
+impl RWSet {
+    pub fn new(txns: &[AnalyzedTransaction]) -> Self {
+        let mut read_set = HashSet::new();
+        let mut write_set = HashSet::new();
+        for analyzed_txn in txns {
+            for write_location in analyzed_txn.write_hints().iter() {
+                write_set.insert(write_location.clone());
+            }
+            for read_location in analyzed_txn.read_hints().iter() {
+                read_set.insert(read_location.clone());
+            }
+        }
+
+        Self {
+            read_set: Arc::new(read_set),
+            write_set: Arc::new(write_set),
+        }
+    }
+
+    pub fn has_write_lock(&self, location: &StorageLocation) -> bool {
+        self.write_set.contains(location)
+    }
+
+    pub fn has_read_lock(&self, location: &StorageLocation) -> bool {
+        self.read_set.contains(location)
+    }
+
+    pub fn has_read_or_write_lock(&self, location: &StorageLocation) -> bool {
+        self.has_read_lock(location) || self.has_write_lock(location)
+    }
+}
+
+#[derive(Default, Clone, Debug)]
+/// Contains a list of storage location along with the maximum transaction index in this shard
+/// that has taken a read/write lock on this storage location.  For example, if the chunk contains 3
+/// transactions with read/write set as follows:
+/// Txn 0: Write set: [A, B, C]
+/// Txn 1: Write set: [A, B]
+/// Txn 2: Write set: [A]
+/// Then the WriteSetWithTxnIndex will be:
+/// Write set: {A: 2, B: 1, C: 0}
+/// Please note that the index is the global index which includes the offset of the shard.
+pub struct WriteSetWithTxnIndex {
+    write_set: Arc>,
+}
+
+impl WriteSetWithTxnIndex {
+    // Creates a new dependency analysis object from a list of transactions. In this case, since the
+    // transactions are frozen, we can set the maximum transaction index to the index of the last
+    // transaction in the list.
+    pub fn new(txns: &[AnalyzedTransaction], txn_index_offset: TxnIndex) -> Self {
+        let mut write_set = HashMap::new();
+        for (index, txn) in txns.iter().enumerate() {
+            for write_location in txn.write_hints().iter() {
+                write_set.insert(write_location.clone(), txn_index_offset + index);
+            }
+        }
+
+        Self {
+            write_set: Arc::new(write_set),
+        }
+    }
+
+    pub fn has_write_lock(&self, location: &StorageLocation) -> bool {
+        self.write_set.contains_key(location)
+    }
+
+    pub fn get_write_lock_txn_index(&self, location: &StorageLocation) -> TxnIndex {
+        *self.write_set.get(location).unwrap()
+    }
+}
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/messages.rs b/execution/block-partitioner/src/sharded_block_partitioner/messages.rs
new file mode 100644
index 0000000000000..6b16abbc66240
--- /dev/null
+++ b/execution/block-partitioner/src/sharded_block_partitioner/messages.rs
@@ -0,0 +1,84 @@
+// Copyright © Aptos Foundation
+
+use crate::{
+    sharded_block_partitioner::dependency_analysis::{RWSet, WriteSetWithTxnIndex},
+    types::{SubBlock, TxnIndex},
+};
+use aptos_types::transaction::analyzed_transaction::AnalyzedTransaction;
+use std::sync::Arc;
+
+pub enum ControlMsg {
+    DiscardCrossShardDepReq(DiscardTxnsWithCrossShardDep),
+    AddCrossShardDepReq(AddTxnsWithCrossShardDep),
+    Stop,
+}
+
+#[derive(Clone, Debug)]
+pub enum CrossShardMsg {
+    WriteSetWithTxnIndexMsg(WriteSetWithTxnIndex),
+    RWSetMsg(RWSet),
+    // Number of accepted transactions in the shard for the current round.
+    AcceptedTxnsMsg(usize),
+}
+
+pub struct DiscardTxnsWithCrossShardDep {
+    pub transactions: Vec,
+    // The frozen dependencies in previous chunks.
+    pub prev_rounds_write_set_with_index: Arc>,
+    pub prev_rounds_frozen_sub_blocks: Arc>,
+}
+
+impl DiscardTxnsWithCrossShardDep {
+    pub fn new(
+        transactions: Vec,
+        prev_rounds_write_set_with_index: Arc>,
+        prev_rounds_frozen_sub_blocks: Arc>,
+    ) -> Self {
+        Self {
+            transactions,
+            prev_rounds_write_set_with_index,
+            prev_rounds_frozen_sub_blocks,
+        }
+    }
+}
+
+pub struct AddTxnsWithCrossShardDep {
+    pub transactions: Vec,
+    pub index_offset: TxnIndex,
+    // The frozen dependencies in previous chunks.
+    pub prev_rounds_write_set_with_index: Arc>,
+}
+
+impl AddTxnsWithCrossShardDep {
+    pub fn new(
+        transactions: Vec,
+        index_offset: TxnIndex,
+        prev_rounds_write_set_with_index: Arc>,
+    ) -> Self {
+        Self {
+            transactions,
+            index_offset,
+            prev_rounds_write_set_with_index,
+        }
+    }
+}
+
+pub struct PartitioningBlockResponse {
+    pub frozen_sub_block: SubBlock,
+    pub write_set_with_index: WriteSetWithTxnIndex,
+    pub discarded_txns: Vec,
+}
+
+impl PartitioningBlockResponse {
+    pub fn new(
+        frozen_sub_block: SubBlock,
+        write_set_with_index: WriteSetWithTxnIndex,
+        discarded_txns: Vec,
+    ) -> Self {
+        Self {
+            frozen_sub_block,
+            write_set_with_index,
+            discarded_txns,
+        }
+    }
+}
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/mod.rs b/execution/block-partitioner/src/sharded_block_partitioner/mod.rs
new file mode 100644
index 0000000000000..bc80102fb3c14
--- /dev/null
+++ b/execution/block-partitioner/src/sharded_block_partitioner/mod.rs
@@ -0,0 +1,657 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::{
+    sharded_block_partitioner::{
+        dependency_analysis::WriteSetWithTxnIndex,
+        messages::{
+            AddTxnsWithCrossShardDep, ControlMsg,
+            ControlMsg::{AddCrossShardDepReq, DiscardCrossShardDepReq},
+            CrossShardMsg, DiscardTxnsWithCrossShardDep, PartitioningBlockResponse,
+        },
+        partitioning_shard::PartitioningShard,
+    },
+    types::{ShardId, SubBlock},
+};
+use aptos_logger::{error, info};
+use aptos_types::transaction::analyzed_transaction::AnalyzedTransaction;
+use std::{
+    collections::HashMap,
+    sync::{
+        mpsc::{Receiver, Sender},
+        Arc,
+    },
+    thread,
+};
+
+mod conflict_detector;
+mod dependency_analysis;
+mod messages;
+mod partitioning_shard;
+
+/// A sharded block partitioner that partitions a block into multiple transaction chunks.
+/// On a high level, the partitioning process is as follows:
+/// ```plaintext
+/// 1. A block is partitioned into equally sized transaction chunks and sent to each shard.
+///
+///    Block:
+///
+///    T1 {write set: A, B}
+///    T2 {write set: B, C}
+///    T3 {write set: C, D}
+///    T4 {write set: D, E}
+///    T5 {write set: E, F}
+///    T6 {write set: F, G}
+///    T7 {write set: G, H}
+///    T8 {write set: H, I}
+///    T9 {write set: I, J}
+///
+/// 2. Discard a bunch of transactions from the chunks and create new chunks so that
+///    there is no cross-shard dependency between transactions in a chunk.
+///   2.1 Following information is passed to each shard:
+///      - candidate transaction chunks to be partitioned
+///      - previously frozen transaction chunks (if any)
+///      - read-write set index mapping from previous iteration (if any) - this contains the maximum absolute index
+///        of the transaction that read/wrote to a storage location indexed by the storage location.
+///   2.2 Each shard creates a read-write set for all transactions in the chunk and broadcasts it to all other shards.
+///              Shard 0                          Shard 1                           Shard 2
+///    +----------------------------+  +-------------------------------+  +-------------------------------+
+///    |        Read-Write Set      |  |         Read-Write Set         |  |         Read-Write Set         |
+///    |                            |  |                               |  |                               |
+///    |   T1 {A, B}                |  |   T4 {D, E}                   |  |   T7 {G, H}                   |
+///    |   T2 {B, C}                |  |   T5 {E, F}                   |  |   T8 {H, I}                   |
+///    |   T3 {C, D}                |  |   T6 {F, G}                   |  |   T9 {I, J}                   |
+///    +----------------------------+  +-------------------------------+  +-------------------------------+
+///   2.3 Each shard collects read-write sets from all other shards and discards transactions that have cross-shard dependencies.
+///              Shard 0                          Shard 1                           Shard 2
+///    +----------------------------+  +-------------------------------+  +-------------------------------+
+///    |        Discarded Txns      |  |         Discarded Txns         |  |         Discarded Txns         |
+///    |                            |  |                               |  |                               |
+///    |   - T3 (cross-shard dependency with T4) |  |   - T6 (cross-shard dependency with T7) |  | No discard |
+///    +----------------------------+  +-------------------------------+  +-------------------------------+
+///   2.4 Each shard broadcasts the number of transactions that it plans to put in the current chunk.
+///              Shard 0                          Shard 1                           Shard 2
+///    +----------------------------+  +-------------------------------+  +-------------------------------+
+///    |          Chunk Count       |  |          Chunk Count          |  |          Chunk Count          |
+///    |                            |  |                               |  |                               |
+///    |   2                        |  |   2                           |  |      3                        |
+///    +----------------------------+  +-------------------------------+  +-------------------------------+
+///   2.5 Each shard collects the number of transactions that all other shards plan to put in the current chunk and based
+///      on that, it finalizes the absolute index offset of the current chunk. It uses this information to create a read-write set
+///      index, which is a mapping of all the storage location to the maximum absolute index of the transaction that read/wrote to that location.
+///             Shard 0                          Shard 1                           Shard 2
+///    +----------------------------+  +-------------------------------+  +-------------------------------+
+///    |          Index Offset      |  |          Index Offset         |  |          Index Offset         |
+///    |                            |  |                               |  |                               |
+///    |   0                        |  |   2                           |  |   4                           |
+///    +----------------------------+  +-------------------------------+  +-------------------------------+
+///   2.6 It also uses the read-write set index mapping passed in previous iteration to add cross-shard dependencies to the transactions. This is
+///     done by looking up the read-write set index for each storage location that a transaction reads/writes to and adding a cross-shard dependency
+///   2.7 Returns two lists of transactions: one list of transactions that are discarded and another list of transactions that are kept.
+/// 3. Use the discarded transactions to create new chunks and repeat the step 2 until N iterations.
+/// 4. For remaining transaction chunks, add cross-shard dependencies to the transactions. This is done as follows:
+///   4.1 Create a read-write set with index mapping for all the transactions in the remaining chunks.
+///   4.2 Broadcast and collect read-write set with index mapping from all shards.
+///   4.3 Add cross-shard dependencies to the transactions in the remaining chunks by looking up the read-write set index
+///       for each storage location that a transaction reads/writes to. The idea is to find the maximum transaction index
+///       that reads/writes to the same location and add that as a dependency. This can be done as follows: First look up the read-write set index
+///       mapping received from other shards in current iteration in descending order of shard id. If the read-write set index is not found,
+///       look up the read-write set index mapping received from other shards in previous iteration(s) in descending order of shard id.
+/// ```
+///
+pub struct ShardedBlockPartitioner {
+    num_shards: usize,
+    control_txs: Vec>,
+    result_rxs: Vec>,
+    shard_threads: Vec>,
+}
+
+impl ShardedBlockPartitioner {
+    pub fn new(num_shards: usize) -> Self {
+        info!(
+            "Creating a new sharded block partitioner with {} shards",
+            num_shards
+        );
+        assert!(num_shards > 0, "num_partitioning_shards must be > 0");
+        // create channels for cross shard messages across all shards. This is a full mesh connection.
+        // Each shard has a vector of channels for sending messages to other shards and
+        // a vector of channels for receiving messages from other shards.
+        let mut messages_txs = vec![];
+        let mut messages_rxs = vec![];
+        for _ in 0..num_shards {
+            messages_txs.push(vec![]);
+            messages_rxs.push(vec![]);
+            for _ in 0..num_shards {
+                let (messages_tx, messages_rx) = std::sync::mpsc::channel();
+                messages_txs.last_mut().unwrap().push(messages_tx);
+                messages_rxs.last_mut().unwrap().push(messages_rx);
+            }
+        }
+        let mut control_txs = vec![];
+        let mut result_rxs = vec![];
+        let mut shard_join_handles = vec![];
+        for (i, message_rxs) in messages_rxs.into_iter().enumerate() {
+            let (control_tx, control_rx) = std::sync::mpsc::channel();
+            let (result_tx, result_rx) = std::sync::mpsc::channel();
+            control_txs.push(control_tx);
+            result_rxs.push(result_rx);
+            shard_join_handles.push(spawn_partitioning_shard(
+                i,
+                control_rx,
+                result_tx,
+                message_rxs,
+                messages_txs.iter().map(|txs| txs[i].clone()).collect(),
+            ));
+        }
+        Self {
+            num_shards,
+            control_txs,
+            result_rxs,
+            shard_threads: shard_join_handles,
+        }
+    }
+
+    // reorders the transactions so that transactions from the same sender always go to the same shard.
+    // This places transactions from the same sender next to each other, which is not optimal for parallelism.
+    // TODO(skedia): Improve this logic to shuffle senders
+    fn partition_by_senders(
+        &self,
+        txns: Vec,
+    ) -> Vec> {
+        let approx_txns_per_shard = (txns.len() as f64 / self.num_shards as f64).ceil() as usize;
+        let mut sender_to_txns = HashMap::new();
+        let mut sender_order = Vec::new(); // Track sender ordering
+
+        for txn in txns {
+            let sender = txn.sender().unwrap();
+            let entry = sender_to_txns.entry(sender).or_insert_with(Vec::new);
+            entry.push(txn);
+            if entry.len() == 1 {
+                sender_order.push(sender); // Add sender to the order vector
+            }
+        }
+
+        let mut result = Vec::new();
+        result.push(Vec::new());
+
+        for sender in sender_order {
+            let txns = sender_to_txns.remove(&sender).unwrap();
+            let txns_in_shard = result.last().unwrap().len();
+
+            if txns_in_shard < approx_txns_per_shard {
+                result.last_mut().unwrap().extend(txns);
+            } else {
+                result.push(txns);
+            }
+        }
+
+        // pad the rest of the shard with empty txns
+        for _ in result.len()..self.num_shards {
+            result.push(Vec::new());
+        }
+
+        result
+    }
+
+    fn send_partition_msgs(&self, partition_msg: Vec) {
+        for (i, msg) in partition_msg.into_iter().enumerate() {
+            self.control_txs[i].send(msg).unwrap();
+        }
+    }
+
+    fn collect_partition_block_response(
+        &self,
+    ) -> (
+        Vec,
+        Vec,
+        Vec>,
+    ) {
+        let mut frozen_chunks = Vec::new();
+        let mut frozen_write_set_with_index = Vec::new();
+        let mut rejected_txns_vec = Vec::new();
+        for rx in &self.result_rxs {
+            let PartitioningBlockResponse {
+                frozen_sub_block: frozen_chunk,
+                write_set_with_index,
+                discarded_txns: rejected_txns,
+            } = rx.recv().unwrap();
+            frozen_chunks.push(frozen_chunk);
+            frozen_write_set_with_index.push(write_set_with_index);
+            rejected_txns_vec.push(rejected_txns);
+        }
+        (
+            frozen_chunks,
+            frozen_write_set_with_index,
+            rejected_txns_vec,
+        )
+    }
+
+    fn discard_txns_with_cross_shard_dependencies(
+        &self,
+        txns_to_partition: Vec>,
+        frozen_sub_blocks: Arc>,
+        frozen_write_set_with_index: Arc>,
+    ) -> (
+        Vec,
+        Vec,
+        Vec>,
+    ) {
+        let partition_block_msgs = txns_to_partition
+            .into_iter()
+            .map(|txns| {
+                DiscardCrossShardDepReq(DiscardTxnsWithCrossShardDep::new(
+                    txns,
+                    frozen_write_set_with_index.clone(),
+                    frozen_sub_blocks.clone(),
+                ))
+            })
+            .collect();
+        self.send_partition_msgs(partition_block_msgs);
+        self.collect_partition_block_response()
+    }
+
+    fn add_cross_shard_dependencies(
+        &self,
+        index_offset: usize,
+        remaining_txns_vec: Vec>,
+        frozen_write_set_with_index: Arc>,
+    ) -> (
+        Vec,
+        Vec,
+        Vec>,
+    ) {
+        let mut index_offset = index_offset;
+        let partition_block_msgs = remaining_txns_vec
+            .into_iter()
+            .map(|remaining_txns| {
+                let remaining_txns_len = remaining_txns.len();
+                let partitioning_msg = AddCrossShardDepReq(AddTxnsWithCrossShardDep::new(
+                    remaining_txns,
+                    index_offset,
+                    frozen_write_set_with_index.clone(),
+                ));
+                index_offset += remaining_txns_len;
+                partitioning_msg
+            })
+            .collect::>();
+        self.send_partition_msgs(partition_block_msgs);
+        self.collect_partition_block_response()
+    }
+
+    /// We repeatedly partition chunks, discarding a bunch of transactions with cross-shard dependencies. The set of discarded
+    /// transactions are used as candidate chunks in the next round. This process is repeated until num_partitioning_rounds.
+    /// The remaining transactions are then added to the chunks with cross-shard dependencies.
+    pub fn partition(
+        &self,
+        transactions: Vec,
+        num_partitioning_round: usize,
+    ) -> Vec {
+        let total_txns = transactions.len();
+        if total_txns == 0 {
+            return vec![];
+        }
+
+        // First round, we filter all transactions with cross-shard dependencies
+        let mut txns_to_partition = self.partition_by_senders(transactions);
+        let mut frozen_write_set_with_index = Arc::new(Vec::new());
+        let mut frozen_sub_blocks = Arc::new(Vec::new());
+
+        for _ in 0..num_partitioning_round {
+            let (
+                current_frozen_sub_blocks_vec,
+                current_frozen_rw_set_with_index_vec,
+                discarded_txns_to_partition,
+            ) = self.discard_txns_with_cross_shard_dependencies(
+                txns_to_partition,
+                frozen_sub_blocks.clone(),
+                frozen_write_set_with_index.clone(),
+            );
+            let mut prev_frozen_sub_blocks = Arc::try_unwrap(frozen_sub_blocks).unwrap();
+            let mut prev_frozen_write_set_with_index =
+                Arc::try_unwrap(frozen_write_set_with_index).unwrap();
+            prev_frozen_sub_blocks.extend(current_frozen_sub_blocks_vec);
+            prev_frozen_write_set_with_index.extend(current_frozen_rw_set_with_index_vec);
+            frozen_sub_blocks = Arc::new(prev_frozen_sub_blocks);
+            frozen_write_set_with_index = Arc::new(prev_frozen_write_set_with_index);
+            txns_to_partition = discarded_txns_to_partition;
+            if txns_to_partition
+                .iter()
+                .map(|txns| txns.len())
+                .sum::()
+                == 0
+            {
+                return Arc::try_unwrap(frozen_sub_blocks).unwrap();
+            }
+        }
+
+        // We just add cross shard dependencies for remaining transactions.
+        let index_offset = frozen_sub_blocks
+            .iter()
+            .map(|chunk| chunk.len())
+            .sum::();
+        let (remaining_frozen_chunks, _, _) = self.add_cross_shard_dependencies(
+            index_offset,
+            txns_to_partition,
+            frozen_write_set_with_index,
+        );
+
+        Arc::try_unwrap(frozen_sub_blocks)
+            .unwrap()
+            .into_iter()
+            .chain(remaining_frozen_chunks.into_iter())
+            .collect::>()
+    }
+}
+
+impl Drop for ShardedBlockPartitioner {
+    /// Best effort stops all the executor shards and waits for the thread to finish.
+    fn drop(&mut self) {
+        // send stop command to all executor shards
+        for control_tx in self.control_txs.iter() {
+            if let Err(e) = control_tx.send(ControlMsg::Stop) {
+                error!("Failed to send stop command to executor shard: {:?}", e);
+            }
+        }
+
+        // wait for all executor shards to stop
+        for shard_thread in self.shard_threads.drain(..) {
+            shard_thread.join().unwrap_or_else(|e| {
+                error!("Failed to join executor shard thread: {:?}", e);
+            });
+        }
+    }
+}
+
+fn spawn_partitioning_shard(
+    shard_id: ShardId,
+    control_rx: Receiver,
+    result_tx: Sender,
+    message_rxs: Vec>,
+    messages_txs: Vec>,
+) -> thread::JoinHandle<()> {
+    // create and start a new executor shard in a separate thread
+    thread::Builder::new()
+        .name(format!("partitioning-shard-{}", shard_id))
+        .spawn(move || {
+            let partitioning_shard =
+                PartitioningShard::new(shard_id, control_rx, result_tx, message_rxs, messages_txs);
+            partitioning_shard.start();
+        })
+        .unwrap()
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::{
+        sharded_block_partitioner::ShardedBlockPartitioner,
+        test_utils::{
+            create_non_conflicting_p2p_transaction, create_signed_p2p_transaction,
+            generate_test_account, generate_test_account_for_address, TestAccount,
+        },
+        types::SubBlock,
+    };
+    use aptos_types::transaction::analyzed_transaction::AnalyzedTransaction;
+    use move_core_types::account_address::AccountAddress;
+    use rand::{rngs::OsRng, Rng};
+    use std::collections::HashMap;
+
+    fn verify_no_cross_shard_dependency(partitioned_txns: Vec) {
+        for chunk in partitioned_txns {
+            for txn in chunk.transactions {
+                assert_eq!(txn.cross_shard_dependencies().len(), 0);
+            }
+        }
+    }
+
+    #[test]
+    // Test that the partitioner works correctly for a single sender and multiple receivers.
+    // In this case the expectation is that only the first shard will contain transactions and all
+    // other shards will be empty.
+    fn test_single_sender_txns() {
+        let mut sender = generate_test_account();
+        let mut receivers = Vec::new();
+        let num_txns = 10;
+        for _ in 0..num_txns {
+            receivers.push(generate_test_account());
+        }
+        let transactions = create_signed_p2p_transaction(
+            &mut sender,
+            receivers.iter().collect::>(),
+        );
+        let partitioner = ShardedBlockPartitioner::new(4);
+        let partitioned_txns = partitioner.partition(transactions.clone(), 1);
+        assert_eq!(partitioned_txns.len(), 4);
+        // The first shard should contain all the transactions
+        assert_eq!(partitioned_txns[0].len(), num_txns);
+        // The rest of the shards should be empty
+        for txns in partitioned_txns.iter().take(4).skip(1) {
+            assert_eq!(txns.len(), 0);
+        }
+        // Verify that the transactions are in the same order as the original transactions and cross shard
+        // dependencies are empty.
+        for (i, txn) in partitioned_txns[0].transactions.iter().enumerate() {
+            assert_eq!(txn.txn(), &transactions[i]);
+            assert_eq!(txn.cross_shard_dependencies().len(), 0);
+        }
+    }
+
+    #[test]
+    // Test that the partitioner works correctly for no conflict transactions. In this case, the
+    // expectation is that no transaction is reordered.
+    fn test_non_conflicting_txns() {
+        let num_txns = 4;
+        let num_shards = 2;
+        let mut transactions = Vec::new();
+        for _ in 0..num_txns {
+            transactions.push(create_non_conflicting_p2p_transaction())
+        }
+        let partitioner = ShardedBlockPartitioner::new(num_shards);
+        let partitioned_txns = partitioner.partition(transactions.clone(), 1);
+        assert_eq!(partitioned_txns.len(), num_shards);
+        // Verify that the transactions are in the same order as the original transactions and cross shard
+        // dependencies are empty.
+        let mut current_index = 0;
+        for analyzed_txns in partitioned_txns.into_iter() {
+            assert_eq!(analyzed_txns.len(), num_txns / num_shards);
+            for txn in analyzed_txns.transactions.iter() {
+                assert_eq!(txn.txn(), &transactions[current_index]);
+                assert_eq!(txn.cross_shard_dependencies().len(), 0);
+                current_index += 1;
+            }
+        }
+    }
+
+    #[test]
+    fn test_same_sender_in_one_shard() {
+        let num_shards = 3;
+        let mut sender = generate_test_account();
+        let mut txns_from_sender = Vec::new();
+        for _ in 0..5 {
+            txns_from_sender.push(
+                create_signed_p2p_transaction(&mut sender, vec![&generate_test_account()])
+                    .remove(0),
+            );
+        }
+        let mut non_conflicting_transactions = Vec::new();
+        for _ in 0..5 {
+            non_conflicting_transactions.push(create_non_conflicting_p2p_transaction());
+        }
+
+        let mut transactions = Vec::new();
+        let mut txn_from_sender_index = 0;
+        let mut non_conflicting_txn_index = 0;
+        transactions.push(non_conflicting_transactions[non_conflicting_txn_index].clone());
+        non_conflicting_txn_index += 1;
+        transactions.push(txns_from_sender[txn_from_sender_index].clone());
+        txn_from_sender_index += 1;
+        transactions.push(txns_from_sender[txn_from_sender_index].clone());
+        txn_from_sender_index += 1;
+        transactions.push(non_conflicting_transactions[non_conflicting_txn_index].clone());
+        non_conflicting_txn_index += 1;
+        transactions.push(txns_from_sender[txn_from_sender_index].clone());
+        txn_from_sender_index += 1;
+        transactions.push(txns_from_sender[txn_from_sender_index].clone());
+        txn_from_sender_index += 1;
+        transactions.push(non_conflicting_transactions[non_conflicting_txn_index].clone());
+        transactions.push(txns_from_sender[txn_from_sender_index].clone());
+
+        let partitioner = ShardedBlockPartitioner::new(num_shards);
+        let partitioned_txns = partitioner.partition(transactions.clone(), 1);
+        assert_eq!(partitioned_txns.len(), num_shards);
+        assert_eq!(partitioned_txns[0].len(), 6);
+        assert_eq!(partitioned_txns[1].len(), 2);
+        assert_eq!(partitioned_txns[2].len(), 0);
+
+        // verify that all transactions from the sender end up in shard 0
+        for (index, txn) in txns_from_sender.iter().enumerate() {
+            assert_eq!(partitioned_txns[0].transactions[index + 1].txn(), txn);
+        }
+        verify_no_cross_shard_dependency(partitioned_txns);
+    }
+
+    #[test]
+    fn test_cross_shard_dependencies() {
+        let num_shards = 3;
+        let mut account1 = generate_test_account_for_address(AccountAddress::new([0; 32]));
+        let mut account2 = generate_test_account_for_address(AccountAddress::new([1; 32]));
+        let account3 = generate_test_account_for_address(AccountAddress::new([2; 32]));
+        let mut account4 = generate_test_account_for_address(AccountAddress::new([4; 32]));
+        let account5 = generate_test_account_for_address(AccountAddress::new([5; 32]));
+        let account6 = generate_test_account_for_address(AccountAddress::new([6; 32]));
+        let mut account7 = generate_test_account_for_address(AccountAddress::new([7; 32]));
+        let account8 = generate_test_account_for_address(AccountAddress::new([8; 32]));
+        let account9 = generate_test_account_for_address(AccountAddress::new([9; 32]));
+
+        let txn0 = create_signed_p2p_transaction(&mut account1, vec![&account2]).remove(0); // txn 0
+        let txn1 = create_signed_p2p_transaction(&mut account1, vec![&account3]).remove(0); // txn 1
+        let txn2 = create_signed_p2p_transaction(&mut account2, vec![&account3]).remove(0); // txn 2
+                                                                                            // Should go in shard 1
+        let txn3 = create_signed_p2p_transaction(&mut account4, vec![&account5]).remove(0); // txn 3
+        let txn4 = create_signed_p2p_transaction(&mut account4, vec![&account6]).remove(0); // txn 4
+        let txn5 = create_signed_p2p_transaction(&mut account4, vec![&account6]).remove(0); // txn 5
+                                                                                            // Should go in shard 2
+        let txn6 = create_signed_p2p_transaction(&mut account7, vec![&account8]).remove(0); // txn 6
+        let txn7 = create_signed_p2p_transaction(&mut account7, vec![&account9]).remove(0); // txn 7
+        let txn8 = create_signed_p2p_transaction(&mut account4, vec![&account7]).remove(0); // txn 8
+
+        let transactions = vec![
+            txn0.clone(),
+            txn1.clone(),
+            txn2.clone(),
+            txn3.clone(),
+            txn4.clone(),
+            txn5.clone(),
+            txn6.clone(),
+            txn7.clone(),
+            txn8.clone(),
+        ];
+
+        let partitioner = ShardedBlockPartitioner::new(num_shards);
+        let partitioned_chunks = partitioner.partition(transactions, 1);
+        assert_eq!(partitioned_chunks.len(), 2 * num_shards);
+
+        // In first round of the partitioning, we should have txn0, txn1 and txn2 in shard 0 and
+        // txn3, txn4, txn5 and txn8 in shard 1 and 0 in shard 2. Please note that txn8 is moved to
+        // shard 1 because of sender based reordering.
+        assert_eq!(partitioned_chunks[0].len(), 3);
+        assert_eq!(partitioned_chunks[1].len(), 4);
+        assert_eq!(partitioned_chunks[2].len(), 0);
+
+        assert_eq!(
+            partitioned_chunks[0]
+                .transactions_with_deps()
+                .iter()
+                .map(|x| x.txn.clone())
+                .collect::>(),
+            vec![txn0, txn1, txn2]
+        );
+        assert_eq!(
+            partitioned_chunks[1]
+                .transactions_with_deps()
+                .iter()
+                .map(|x| x.txn.clone())
+                .collect::>(),
+            vec![txn3, txn4, txn5, txn8]
+        );
+
+        // Rest of the transactions will be added in round 2 along with their dependencies
+        assert_eq!(partitioned_chunks[3].len(), 0);
+        assert_eq!(partitioned_chunks[4].len(), 0);
+        assert_eq!(partitioned_chunks[5].len(), 2);
+
+        assert_eq!(
+            partitioned_chunks[5]
+                .transactions_with_deps()
+                .iter()
+                .map(|x| x.txn.clone())
+                .collect::>(),
+            vec![txn6, txn7]
+        );
+
+        // Verify transaction dependencies
+        verify_no_cross_shard_dependency(vec![
+            partitioned_chunks[0].clone(),
+            partitioned_chunks[1].clone(),
+            partitioned_chunks[2].clone(),
+        ]);
+        // txn6 and txn7 depends on txn8 (index 6)
+        assert!(partitioned_chunks[5].transactions_with_deps()[0]
+            .cross_shard_dependencies
+            .is_depends_on(6));
+        assert!(partitioned_chunks[5].transactions_with_deps()[1]
+            .cross_shard_dependencies
+            .is_depends_on(6));
+    }
+
+    #[test]
+    // Generates a bunch of random transactions and ensures that after the partitioning, there is
+    // no conflict across shards.
+    fn test_no_conflict_across_shards_in_first_round() {
+        let mut rng = OsRng;
+        let max_accounts = 500;
+        let max_txns = 2000;
+        let max_num_shards = 64;
+        let num_accounts = rng.gen_range(1, max_accounts);
+        let mut accounts = Vec::new();
+        for _ in 0..num_accounts {
+            accounts.push(generate_test_account());
+        }
+        let num_txns = rng.gen_range(1, max_txns);
+        let mut transactions = Vec::new();
+        let num_shards = rng.gen_range(1, max_num_shards);
+
+        for _ in 0..num_txns {
+            // randomly select a sender and receiver from accounts
+            let sender_index = rng.gen_range(0, accounts.len());
+            let mut sender = accounts.swap_remove(sender_index);
+            let receiver_index = rng.gen_range(0, accounts.len());
+            let receiver = accounts.get(receiver_index).unwrap();
+            transactions.push(create_signed_p2p_transaction(&mut sender, vec![receiver]).remove(0));
+            accounts.push(sender)
+        }
+        let partitioner = ShardedBlockPartitioner::new(num_shards);
+        let partitioned_txns = partitioner.partition(transactions, 1);
+        // Build a map of storage location to corresponding shards in first round
+        // and ensure that no storage location is present in more than one shard.
+        let mut storage_location_to_shard_map = HashMap::new();
+        for (shard_id, txns) in partitioned_txns.iter().enumerate().take(num_shards) {
+            for txn in txns.transactions_with_deps().iter() {
+                let storage_locations = txn
+                    .txn()
+                    .read_hints()
+                    .iter()
+                    .chain(txn.txn().write_hints().iter());
+                for storage_location in storage_locations {
+                    if storage_location_to_shard_map.contains_key(storage_location) {
+                        assert_eq!(
+                            storage_location_to_shard_map.get(storage_location).unwrap(),
+                            &shard_id
+                        );
+                    } else {
+                        storage_location_to_shard_map.insert(storage_location, shard_id);
+                    }
+                }
+            }
+        }
+    }
+}
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/partitioning_shard.rs b/execution/block-partitioner/src/sharded_block_partitioner/partitioning_shard.rs
new file mode 100644
index 0000000000000..ccaf34d502606
--- /dev/null
+++ b/execution/block-partitioner/src/sharded_block_partitioner/partitioning_shard.rs
@@ -0,0 +1,242 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+use crate::{
+    sharded_block_partitioner::{
+        conflict_detector::CrossShardConflictDetector,
+        dependency_analysis::{RWSet, WriteSetWithTxnIndex},
+        messages::{
+            AddTxnsWithCrossShardDep, ControlMsg, CrossShardMsg, DiscardTxnsWithCrossShardDep,
+            PartitioningBlockResponse,
+        },
+    },
+    types::{ShardId, SubBlock, TransactionWithDependencies},
+};
+use aptos_logger::trace;
+use std::sync::{
+    mpsc::{Receiver, Sender},
+    Arc,
+};
+
+pub struct PartitioningShard {
+    shard_id: ShardId,
+    control_rx: Receiver,
+    result_tx: Sender,
+    message_rxs: Vec>,
+    message_txs: Vec>,
+}
+
+impl PartitioningShard {
+    pub fn new(
+        shard_id: ShardId,
+        control_rx: Receiver,
+        result_tx: Sender,
+        message_rxs: Vec>,
+        messages_txs: Vec>,
+    ) -> Self {
+        Self {
+            shard_id,
+            control_rx,
+            result_tx,
+            message_rxs,
+            message_txs: messages_txs,
+        }
+    }
+
+    fn broadcast_rw_set(&self, rw_set: RWSet) {
+        let num_shards = self.message_txs.len();
+        for i in 0..num_shards {
+            if i != self.shard_id {
+                self.message_txs[i]
+                    .send(CrossShardMsg::RWSetMsg(rw_set.clone()))
+                    .unwrap();
+            }
+        }
+    }
+
+    fn collect_rw_set(&self) -> Vec {
+        let mut rw_set_vec = vec![RWSet::default(); self.message_txs.len()];
+        for (i, msg_rx) in self.message_rxs.iter().enumerate() {
+            if i == self.shard_id {
+                continue;
+            }
+
+            let msg = msg_rx.recv().unwrap();
+            match msg {
+                CrossShardMsg::RWSetMsg(rw_set) => {
+                    rw_set_vec[i] = rw_set;
+                },
+                _ => panic!("Unexpected message"),
+            }
+        }
+        rw_set_vec
+    }
+
+    fn broadcast_write_set_with_index(&self, rw_set_with_index: WriteSetWithTxnIndex) {
+        let num_shards = self.message_txs.len();
+        for i in 0..num_shards {
+            if i != self.shard_id {
+                self.message_txs[i]
+                    .send(CrossShardMsg::WriteSetWithTxnIndexMsg(
+                        rw_set_with_index.clone(),
+                    ))
+                    .unwrap();
+            }
+        }
+    }
+
+    fn collect_write_set_with_index(&self) -> Vec {
+        let mut rw_set_with_index_vec =
+            vec![WriteSetWithTxnIndex::default(); self.message_txs.len()];
+        for (i, msg_rx) in self.message_rxs.iter().enumerate() {
+            if i == self.shard_id {
+                continue;
+            }
+            let msg = msg_rx.recv().unwrap();
+            match msg {
+                CrossShardMsg::WriteSetWithTxnIndexMsg(rw_set_with_index) => {
+                    rw_set_with_index_vec[i] = rw_set_with_index;
+                },
+                _ => panic!("Unexpected message"),
+            }
+        }
+        rw_set_with_index_vec
+    }
+
+    fn broadcast_num_accepted_txns(&self, num_accepted_txns: usize) {
+        let num_shards = self.message_txs.len();
+        for i in 0..num_shards {
+            if i != self.shard_id {
+                self.message_txs[i]
+                    .send(CrossShardMsg::AcceptedTxnsMsg(num_accepted_txns))
+                    .unwrap();
+            }
+        }
+    }
+
+    fn collect_num_accepted_txns(&self) -> Vec {
+        let mut accepted_txns_vec = vec![0; self.message_txs.len()];
+        for (i, msg_rx) in self.message_rxs.iter().enumerate() {
+            if i == self.shard_id {
+                continue;
+            }
+            let msg = msg_rx.recv().unwrap();
+            match msg {
+                CrossShardMsg::AcceptedTxnsMsg(num_accepted_txns) => {
+                    accepted_txns_vec[i] = num_accepted_txns;
+                },
+                _ => panic!("Unexpected message"),
+            }
+        }
+        accepted_txns_vec
+    }
+
+    fn discard_txns_with_cross_shard_deps(&self, partition_msg: DiscardTxnsWithCrossShardDep) {
+        let DiscardTxnsWithCrossShardDep {
+            transactions,
+            prev_rounds_write_set_with_index,
+            prev_rounds_frozen_sub_blocks,
+        } = partition_msg;
+        let num_shards = self.message_txs.len();
+        let mut conflict_detector = CrossShardConflictDetector::new(self.shard_id, num_shards);
+        // If transaction filtering is allowed, we need to prepare the dependency analysis and broadcast it to other shards
+        // Based on the dependency analysis received from other shards, we will reject transactions that are conflicting with
+        // transactions in other shards
+        let read_write_set = RWSet::new(&transactions);
+        self.broadcast_rw_set(read_write_set);
+        let cross_shard_rw_set = self.collect_rw_set();
+        let (accepted_txns, accepted_cross_shard_dependencies, rejected_txns) = conflict_detector
+            .discard_txns_with_cross_shard_deps(
+                transactions,
+                &cross_shard_rw_set,
+                prev_rounds_write_set_with_index,
+            );
+        // Broadcast and collect the stats around number of accepted and rejected transactions from other shards
+        // this will be used to determine the absolute index of accepted transactions in this shard.
+        self.broadcast_num_accepted_txns(accepted_txns.len());
+        let accepted_txns_vec = self.collect_num_accepted_txns();
+        // Calculate the absolute index of accepted transactions in this shard, which is the sum of all accepted transactions
+        // from other shards whose shard id is smaller than the current shard id and the number of accepted transactions in the
+        // previous rounds
+        // TODO(skedia): Evaluate if we can avoid this calculation by tracking it with a number across rounds.
+        let mut index_offset = prev_rounds_frozen_sub_blocks
+            .iter()
+            .map(|chunk| chunk.len())
+            .sum::();
+        // Drop the previous rounds frozen sub blocks so that the reference count for this drops and
+        // the coordinator can unwrap the Arc after receiving the response
+        drop(prev_rounds_frozen_sub_blocks);
+        let num_accepted_txns = accepted_txns_vec.iter().take(self.shard_id).sum::();
+        index_offset += num_accepted_txns;
+
+        // Calculate the RWSetWithTxnIndex for the accepted transactions
+        let current_rw_set_with_index = WriteSetWithTxnIndex::new(&accepted_txns, index_offset);
+
+        let accepted_txns_with_dependencies = accepted_txns
+            .into_iter()
+            .zip(accepted_cross_shard_dependencies.into_iter())
+            .map(|(txn, dependencies)| TransactionWithDependencies::new(txn, dependencies))
+            .collect::>();
+
+        let frozen_sub_block = SubBlock::new(index_offset, accepted_txns_with_dependencies);
+        // send the result back to the controller
+        self.result_tx
+            .send(PartitioningBlockResponse::new(
+                frozen_sub_block,
+                current_rw_set_with_index,
+                rejected_txns,
+            ))
+            .unwrap();
+    }
+
+    fn add_txns_with_cross_shard_deps(&self, partition_msg: AddTxnsWithCrossShardDep) {
+        let AddTxnsWithCrossShardDep {
+            transactions,
+            index_offset,
+            // The frozen dependencies in previous chunks.
+            prev_rounds_write_set_with_index,
+        } = partition_msg;
+        let num_shards = self.message_txs.len();
+        let conflict_detector = CrossShardConflictDetector::new(self.shard_id, num_shards);
+
+        // Since txn filtering is not allowed, we can create the RW set with maximum txn
+        // index with the index offset passed.
+        let write_set_with_index_for_shard = WriteSetWithTxnIndex::new(&transactions, index_offset);
+
+        self.broadcast_write_set_with_index(write_set_with_index_for_shard.clone());
+        let current_round_rw_set_with_index = self.collect_write_set_with_index();
+        let frozen_sub_block = conflict_detector.get_frozen_sub_block(
+            transactions,
+            Arc::new(current_round_rw_set_with_index),
+            prev_rounds_write_set_with_index,
+            index_offset,
+        );
+
+        self.result_tx
+            .send(PartitioningBlockResponse::new(
+                frozen_sub_block,
+                write_set_with_index_for_shard,
+                vec![],
+            ))
+            .unwrap();
+    }
+
+    pub fn start(&self) {
+        loop {
+            let command = self.control_rx.recv().unwrap();
+            match command {
+                ControlMsg::DiscardCrossShardDepReq(msg) => {
+                    self.discard_txns_with_cross_shard_deps(msg);
+                },
+                ControlMsg::AddCrossShardDepReq(msg) => {
+                    self.add_txns_with_cross_shard_deps(msg);
+                },
+                ControlMsg::Stop => {
+                    break;
+                },
+            }
+        }
+        trace!("Shard {} is shutting down", self.shard_id);
+    }
+}
diff --git a/execution/block-partitioner/src/test_utils.rs b/execution/block-partitioner/src/test_utils.rs
new file mode 100644
index 0000000000000..b1766e7f73566
--- /dev/null
+++ b/execution/block-partitioner/src/test_utils.rs
@@ -0,0 +1,81 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use aptos_crypto::{ed25519::ed25519_keys::Ed25519PrivateKey, PrivateKey, SigningKey, Uniform};
+use aptos_types::{
+    chain_id::ChainId,
+    transaction::{
+        analyzed_transaction::AnalyzedTransaction, EntryFunction, RawTransaction,
+        SignedTransaction, Transaction, TransactionPayload,
+    },
+    utility_coin::APTOS_COIN_TYPE,
+};
+use move_core_types::{
+    account_address::AccountAddress, identifier::Identifier, language_storage::ModuleId,
+};
+
+#[derive(Debug)]
+pub struct TestAccount {
+    pub account_address: AccountAddress,
+    pub private_key: Ed25519PrivateKey,
+    pub sequence_number: u64,
+}
+
+pub fn generate_test_account() -> TestAccount {
+    TestAccount {
+        account_address: AccountAddress::random(),
+        private_key: Ed25519PrivateKey::generate_for_testing(),
+        sequence_number: 0,
+    }
+}
+
+pub fn generate_test_account_for_address(account_address: AccountAddress) -> TestAccount {
+    TestAccount {
+        account_address,
+        private_key: Ed25519PrivateKey::generate_for_testing(),
+        sequence_number: 0,
+    }
+}
+
+pub fn create_non_conflicting_p2p_transaction() -> AnalyzedTransaction {
+    // create unique sender and receiver accounts so that there is no conflict
+    let mut sender = generate_test_account();
+    let receiver = generate_test_account();
+    create_signed_p2p_transaction(&mut sender, vec![&receiver]).remove(0)
+}
+
+pub fn create_signed_p2p_transaction(
+    sender: &mut TestAccount,
+    receivers: Vec<&TestAccount>,
+) -> Vec {
+    let mut transactions = Vec::new();
+    for (_, receiver) in receivers.iter().enumerate() {
+        let transaction_payload = TransactionPayload::EntryFunction(EntryFunction::new(
+            ModuleId::new(AccountAddress::ONE, Identifier::new("coin").unwrap()),
+            Identifier::new("transfer").unwrap(),
+            vec![APTOS_COIN_TYPE.clone()],
+            vec![
+                bcs::to_bytes(&receiver.account_address).unwrap(),
+                bcs::to_bytes(&1u64).unwrap(),
+            ],
+        ));
+
+        let raw_transaction = RawTransaction::new(
+            sender.account_address,
+            sender.sequence_number,
+            transaction_payload,
+            0,
+            0,
+            0,
+            ChainId::new(10),
+        );
+        sender.sequence_number += 1;
+        let txn = Transaction::UserTransaction(SignedTransaction::new(
+            raw_transaction.clone(),
+            sender.private_key.public_key().clone(),
+            sender.private_key.sign(&raw_transaction).unwrap(),
+        ));
+        transactions.push(txn.into())
+    }
+    transactions
+}
diff --git a/execution/block-partitioner/src/types.rs b/execution/block-partitioner/src/types.rs
new file mode 100644
index 0000000000000..56b6a40c31899
--- /dev/null
+++ b/execution/block-partitioner/src/types.rs
@@ -0,0 +1,109 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use aptos_types::transaction::analyzed_transaction::AnalyzedTransaction;
+use std::collections::HashSet;
+
+pub type ShardId = usize;
+pub type TxnIndex = usize;
+
+#[derive(Default, Debug, Clone)]
+/// Represents the dependencies of a transaction on other transactions across shards. Two types
+/// of dependencies are supported:
+/// 1. `depends_on`: The transaction depends on the execution of the transactions in the set. In this
+/// case, the transaction can only be executed after the transactions in the set have been executed.
+/// 2. `dependents`: The transactions in the set depend on the execution of the transaction. In this
+/// case, the transactions in the set can only be executed after the transaction has been executed.
+pub struct CrossShardDependencies {
+    depends_on: HashSet,
+    // TODO (skedia) add support for this.
+    _dependents: HashSet,
+}
+
+impl CrossShardDependencies {
+    pub fn len(&self) -> usize {
+        self.depends_on.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.depends_on.is_empty()
+    }
+
+    pub fn is_depends_on(&self, txn_index: TxnIndex) -> bool {
+        self.depends_on.contains(&txn_index)
+    }
+
+    pub fn add_depends_on_txn(&mut self, txn_index: TxnIndex) {
+        self.depends_on.insert(txn_index);
+    }
+}
+
+#[derive(Debug, Clone)]
+/// A contiguous chunk of transactions (along with their dependencies) in a block.
+///
+/// Each `SubBlock` represents a sequential section of transactions within a block.
+/// The chunk includes the index of the first transaction relative to the block and a vector
+/// of `TransactionWithDependencies` representing the transactions included in the chunk.
+///
+/// Illustration:
+/// ```plaintext
+///  Block (Split into 3 transactions chunks):
+///  +----------------+------------------+------------------+
+///  | Chunk 1        | Chunk 2          | Chunk 3          |
+///  +----------------+------------------+------------------+
+///  | Transaction 1  | Transaction 4    | Transaction 7    |
+///  | Transaction 2  | Transaction 5    | Transaction 8    |
+///  | Transaction 3  | Transaction 6    | Transaction 9    |
+///  +----------------+------------------+------------------+
+/// ```
+pub struct SubBlock {
+    // This is the index of first transaction relative to the block.
+    pub start_index: TxnIndex,
+    pub transactions: Vec,
+}
+
+impl SubBlock {
+    pub fn new(start_index: TxnIndex, transactions: Vec) -> Self {
+        Self {
+            start_index,
+            transactions,
+        }
+    }
+
+    pub fn len(&self) -> usize {
+        self.transactions.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.transactions.is_empty()
+    }
+
+    pub fn transactions_with_deps(&self) -> &Vec {
+        &self.transactions
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct TransactionWithDependencies {
+    pub txn: AnalyzedTransaction,
+    pub cross_shard_dependencies: CrossShardDependencies,
+}
+
+impl TransactionWithDependencies {
+    pub fn new(txn: AnalyzedTransaction, cross_shard_dependencies: CrossShardDependencies) -> Self {
+        Self {
+            txn,
+            cross_shard_dependencies,
+        }
+    }
+
+    #[cfg(test)]
+    pub fn txn(&self) -> &AnalyzedTransaction {
+        &self.txn
+    }
+
+    #[cfg(test)]
+    pub fn cross_shard_dependencies(&self) -> &CrossShardDependencies {
+        &self.cross_shard_dependencies
+    }
+}
diff --git a/execution/executor-benchmark/src/main.rs b/execution/executor-benchmark/src/main.rs
index 489f47ada9c32..44494f3e48562 100644
--- a/execution/executor-benchmark/src/main.rs
+++ b/execution/executor-benchmark/src/main.rs
@@ -117,6 +117,9 @@ struct Opt {
     #[clap(long)]
     concurrency_level: Option,
 
+    #[clap(long, default_value = "1")]
+    num_executor_shards: usize,
+
     #[clap(flatten)]
     pruner_opt: PrunerOpt,
 
@@ -144,10 +147,11 @@ impl Opt {
     fn concurrency_level(&self) -> usize {
         match self.concurrency_level {
             None => {
-                let level = num_cpus::get();
+                let level =
+                    (num_cpus::get() as f64 / self.num_executor_shards as f64).ceil() as usize;
                 println!(
-                    "\nVM concurrency level defaults to num of cpus: {}\n",
-                    level
+                    "\nVM concurrency level defaults to {} for number of shards {} \n",
+                    level, self.num_executor_shards
                 );
                 level
             },
@@ -293,6 +297,7 @@ fn main() {
         .build_global()
         .expect("Failed to build rayon global thread pool.");
     AptosVM::set_concurrency_level_once(opt.concurrency_level());
+    AptosVM::set_num_shards_once(opt.num_executor_shards);
     NativeExecutor::set_concurrency_level_once(opt.concurrency_level());
 
     if opt.use_native_executor {
diff --git a/execution/executor/src/components/chunk_output.rs b/execution/executor/src/components/chunk_output.rs
index 6561082edf249..698317e50f4c0 100644
--- a/execution/executor/src/components/chunk_output.rs
+++ b/execution/executor/src/components/chunk_output.rs
@@ -76,15 +76,15 @@ impl ChunkOutput {
             maybe_block_gas_limit,
         )?;
 
-        update_counters_for_processed_chunk(&transactions, &transaction_outputs, "executed");
+        // TODO(skedia) add logic to emit counters per shard instead of doing it globally.
 
+        // Unwrapping here is safe because the execution has finished and it is guaranteed that
+        // the state view is not used anymore.
         let state_view = Arc::try_unwrap(state_view_arc).unwrap();
 
         Ok(Self {
             transactions,
             transaction_outputs,
-            // Unwrapping here is safe because the execution has finished and it is guaranteed that
-            // the state view is not used anymore.
             state_cache: state_view.into_state_cache(),
         })
     }
diff --git a/types/src/transaction/analyzed_transaction.rs b/types/src/transaction/analyzed_transaction.rs
new file mode 100644
index 0000000000000..e5f402a12171e
--- /dev/null
+++ b/types/src/transaction/analyzed_transaction.rs
@@ -0,0 +1,224 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::{
+    access_path::AccessPath,
+    account_config::{AccountResource, CoinStoreResource},
+    state_store::{state_key::StateKey, table::TableHandle},
+    transaction::{SignedTransaction, Transaction, TransactionPayload},
+};
+use aptos_crypto::{hash::CryptoHash, HashValue};
+pub use move_core_types::abi::{
+    ArgumentABI, ScriptFunctionABI as EntryFunctionABI, TransactionScriptABI, TypeArgumentABI,
+};
+use move_core_types::{
+    account_address::AccountAddress, language_storage::StructTag, move_resource::MoveStructType,
+};
+use std::hash::{Hash, Hasher};
+
+#[derive(Clone, Debug)]
+pub struct AnalyzedTransaction {
+    transaction: Transaction,
+    /// Set of storage locations that are read by the transaction - this doesn't include location
+    /// that are written by the transactions to avoid duplication of locations across read and write sets
+    /// This can be accurate or strictly overestimated.
+    read_hints: Vec,
+    /// Set of storage locations that are written by the transaction. This can be accurate or strictly
+    /// overestimated.
+    write_hints: Vec,
+    /// A transaction is predictable if neither the read_hint or the write_hint have wildcards.
+    predictable_transaction: bool,
+    /// The hash of the transaction - this is cached for performance reasons.
+    hash: HashValue,
+}
+
+#[derive(Debug, Clone, Hash, Eq, PartialEq)]
+// TODO(skedia): Evaluate if we need to cache the HashValue for efficiency reasons.
+pub enum StorageLocation {
+    // A specific storage location denoted by an address and a struct tag.
+    Specific(StateKey),
+    // Storage location denoted by a struct tag and any arbitrary address.
+    // Example read(*), write(*) in Move
+    WildCardStruct(StructTag),
+    // Storage location denoted by a table handle and any arbitrary item in the table.
+    WildCardTable(TableHandle),
+}
+
+impl AnalyzedTransaction {
+    pub fn new(
+        transaction: Transaction,
+        read_hints: Vec,
+        write_hints: Vec,
+    ) -> Self {
+        let hints_contain_wildcard = read_hints
+            .iter()
+            .chain(write_hints.iter())
+            .any(|hint| !matches!(hint, StorageLocation::Specific(_)));
+        let hash = transaction.hash();
+        AnalyzedTransaction {
+            transaction,
+            read_hints,
+            write_hints,
+            predictable_transaction: !hints_contain_wildcard,
+            hash,
+        }
+    }
+
+    pub fn new_with_no_hints(transaction: Transaction) -> Self {
+        AnalyzedTransaction::new(transaction, vec![], vec![])
+    }
+
+    pub fn into_inner(self) -> Transaction {
+        self.transaction
+    }
+
+    pub fn transaction(&self) -> &Transaction {
+        &self.transaction
+    }
+
+    pub fn read_hints(&self) -> &[StorageLocation] {
+        &self.read_hints
+    }
+
+    pub fn write_hints(&self) -> &[StorageLocation] {
+        &self.write_hints
+    }
+
+    pub fn predictable_transaction(&self) -> bool {
+        self.predictable_transaction
+    }
+
+    pub fn sender(&self) -> Option {
+        match &self.transaction {
+            Transaction::UserTransaction(signed_txn) => Some(signed_txn.sender()),
+            _ => None,
+        }
+    }
+
+    pub fn analyzed_transaction_for_coin_transfer(
+        signed_txn: SignedTransaction,
+        sender_address: AccountAddress,
+        receiver_address: AccountAddress,
+        receiver_exists: bool,
+    ) -> Self {
+        let mut write_hints = vec![
+            Self::account_resource_location(sender_address),
+            Self::coin_store_location(sender_address),
+            Self::coin_store_location(receiver_address),
+        ];
+        if !receiver_exists {
+            // If the receiver doesn't exist, we create the receiver account, so we need to write the
+            // receiver account resource.
+            write_hints.push(Self::account_resource_location(receiver_address));
+        }
+        AnalyzedTransaction::new(
+            Transaction::UserTransaction(signed_txn),
+            // Please note that we omit all the modules we read and the global supply we write to?
+            vec![],
+            // read and write locations are same for coin transfer
+            write_hints,
+        )
+    }
+
+    fn account_resource_location(address: AccountAddress) -> StorageLocation {
+        StorageLocation::Specific(StateKey::access_path(AccessPath::new(
+            address,
+            AccountResource::struct_tag().access_vector(),
+        )))
+    }
+
+    fn coin_store_location(address: AccountAddress) -> StorageLocation {
+        StorageLocation::Specific(StateKey::access_path(AccessPath::new(
+            address,
+            CoinStoreResource::struct_tag().access_vector(),
+        )))
+    }
+
+    pub fn analyzed_transaction_for_create_account(
+        signed_txn: SignedTransaction,
+        sender_address: AccountAddress,
+        receiver_address: AccountAddress,
+    ) -> Self {
+        let read_hints = vec![
+            Self::account_resource_location(sender_address),
+            Self::coin_store_location(sender_address),
+            Self::account_resource_location(receiver_address),
+            Self::coin_store_location(receiver_address),
+        ];
+        AnalyzedTransaction::new(
+            Transaction::UserTransaction(signed_txn),
+            vec![],
+            // read and write locations are same for create account
+            read_hints,
+        )
+    }
+}
+
+impl PartialEq for AnalyzedTransaction {
+    fn eq(&self, other: &Self) -> bool {
+        self.hash == other.hash
+    }
+}
+
+impl Eq for AnalyzedTransaction {}
+
+impl Hash for AnalyzedTransaction {
+    fn hash(&self, state: &mut H) {
+        state.write(self.hash.as_ref());
+    }
+}
+
+impl From for AnalyzedTransaction {
+    fn from(txn: Transaction) -> Self {
+        match txn {
+            Transaction::UserTransaction(signed_txn) => match signed_txn.payload() {
+                TransactionPayload::EntryFunction(func) => {
+                    match (
+                        *func.module().address(),
+                        func.module().name().as_str(),
+                        func.function().as_str(),
+                    ) {
+                        (AccountAddress::ONE, "coin", "transfer") => {
+                            let sender_address = signed_txn.sender();
+                            let receiver_address = bcs::from_bytes(&func.args()[0]).unwrap();
+                            AnalyzedTransaction::analyzed_transaction_for_coin_transfer(
+                                signed_txn,
+                                sender_address,
+                                receiver_address,
+                                true,
+                            )
+                        },
+                        (AccountAddress::ONE, "aptos_account", "transfer") => {
+                            let sender_address = signed_txn.sender();
+                            let receiver_address = bcs::from_bytes(&func.args()[0]).unwrap();
+                            AnalyzedTransaction::analyzed_transaction_for_coin_transfer(
+                                signed_txn,
+                                sender_address,
+                                receiver_address,
+                                false,
+                            )
+                        },
+                        (AccountAddress::ONE, "aptos_account", "create_account") => {
+                            let sender_address = signed_txn.sender();
+                            let receiver_address = bcs::from_bytes(&func.args()[0]).unwrap();
+                            AnalyzedTransaction::analyzed_transaction_for_create_account(
+                                signed_txn,
+                                sender_address,
+                                receiver_address,
+                            )
+                        },
+                        _ => todo!("Only coin transfer and create account transactions are supported for now")
+                    }
+                },
+                _ => todo!("Only entry function transactions are supported for now"),
+            },
+            _ => AnalyzedTransaction::new_with_no_hints(txn),
+        }
+    }
+}
+
+impl From for Transaction {
+    fn from(val: AnalyzedTransaction) -> Self {
+        val.transaction
+    }
+}
diff --git a/types/src/transaction/mod.rs b/types/src/transaction/mod.rs
index 549b021cd329d..a7e4fd5c4ac83 100644
--- a/types/src/transaction/mod.rs
+++ b/types/src/transaction/mod.rs
@@ -35,6 +35,7 @@ use std::{
     fmt::{Debug, Display, Formatter},
 };
 
+pub mod analyzed_transaction;
 pub mod authenticator;
 mod change_set;
 mod module;

From 9d04747bc979ed0c0a767570af485ab827550f5c Mon Sep 17 00:00:00 2001
From: "Brian (Sunghoon) Cho" 
Date: Wed, 7 Jun 2023 10:34:17 +0900
Subject: [PATCH 083/200] [mempool] classify client-submitted vs. broadcasted
 transactions (#8486)

### Description

Added a new label for classifying whether a mempool-to-commit latency was measured on a transaction that was directly submitted by the client to this node (via REST api) or came to this node via mempool broadcast.
---
 mempool/src/core_mempool/mempool.rs           |  32 +++--
 mempool/src/core_mempool/mod.rs               |   2 +-
 mempool/src/core_mempool/transaction.rs       |  64 +++++++++-
 mempool/src/core_mempool/transaction_store.rs | 120 +++++++++---------
 mempool/src/counters.rs                       |  15 ++-
 mempool/src/shared_mempool/tasks.rs           |  24 +++-
 mempool/src/tests/common.rs                   |   2 +
 mempool/src/tests/core_mempool_test.rs        |  56 ++++++--
 mempool/src/tests/fuzzing.rs                  |   2 +-
 mempool/src/tests/mocks.rs                    |   1 +
 mempool/src/tests/node.rs                     |   1 +
 11 files changed, 220 insertions(+), 99 deletions(-)

diff --git a/mempool/src/core_mempool/mempool.rs b/mempool/src/core_mempool/mempool.rs
index 278dcc67bb304..d9230ad738839 100644
--- a/mempool/src/core_mempool/mempool.rs
+++ b/mempool/src/core_mempool/mempool.rs
@@ -7,7 +7,7 @@
 use crate::{
     core_mempool::{
         index::TxnPointer,
-        transaction::{MempoolTransaction, TimelineState},
+        transaction::{InsertionInfo, MempoolTransaction, TimelineState},
         transaction_store::TransactionStore,
     },
     counters,
@@ -111,19 +111,27 @@ impl Mempool {
             .reject_transaction(sender, sequence_number, hash);
     }
 
+    pub(crate) fn log_txn_commit_latency(
+        insertion_info: InsertionInfo,
+        bucket: &str,
+        stage: &'static str,
+    ) {
+        if let Ok(time_delta) = SystemTime::now().duration_since(insertion_info.insertion_time) {
+            counters::core_mempool_txn_commit_latency(
+                stage,
+                insertion_info.submitted_by_label(),
+                bucket,
+                time_delta,
+            );
+        }
+    }
+
     fn log_latency(&self, account: AccountAddress, sequence_number: u64, stage: &'static str) {
-        if let Some((&insertion_time, is_end_to_end, bucket)) = self
+        if let Some((&insertion_info, bucket)) = self
             .transactions
-            .get_insertion_time_and_bucket(&account, sequence_number)
+            .get_insertion_info_and_bucket(&account, sequence_number)
         {
-            if let Ok(time_delta) = SystemTime::now().duration_since(insertion_time) {
-                let scope = if is_end_to_end {
-                    counters::E2E_LABEL
-                } else {
-                    counters::LOCAL_LABEL
-                };
-                counters::core_mempool_txn_commit_latency(stage, scope, bucket, time_delta);
-            }
+            Self::log_txn_commit_latency(insertion_info, bucket, stage);
         }
     }
 
@@ -139,6 +147,7 @@ impl Mempool {
         ranking_score: u64,
         db_sequence_number: u64,
         timeline_state: TimelineState,
+        client_submitted: bool,
     ) -> MempoolStatus {
         trace!(
             LogSchema::new(LogEntry::AddTxn)
@@ -166,6 +175,7 @@ impl Mempool {
             timeline_state,
             db_sequence_number,
             now,
+            client_submitted,
         );
 
         let status = self.transactions.insert(txn_info);
diff --git a/mempool/src/core_mempool/mod.rs b/mempool/src/core_mempool/mod.rs
index 0c56692cf6402..434d991d03398 100644
--- a/mempool/src/core_mempool/mod.rs
+++ b/mempool/src/core_mempool/mod.rs
@@ -10,6 +10,6 @@ mod transaction_store;
 pub use self::{
     index::TxnPointer,
     mempool::Mempool as CoreMempool,
-    transaction::{MempoolTransaction, TimelineState},
+    transaction::{MempoolTransaction, SubmittedBy, TimelineState},
     transaction_store::TXN_INDEX_ESTIMATED_BYTES,
 };
diff --git a/mempool/src/core_mempool/transaction.rs b/mempool/src/core_mempool/transaction.rs
index da222baf9a3cf..d6850f5c7b129 100644
--- a/mempool/src/core_mempool/transaction.rs
+++ b/mempool/src/core_mempool/transaction.rs
@@ -2,7 +2,7 @@
 // Parts of the project are originally copyright © Meta Platforms, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-use crate::core_mempool::TXN_INDEX_ESTIMATED_BYTES;
+use crate::{core_mempool::TXN_INDEX_ESTIMATED_BYTES, counters};
 use aptos_crypto::HashValue;
 use aptos_types::{account_address::AccountAddress, transaction::SignedTransaction};
 use serde::{Deserialize, Serialize};
@@ -22,7 +22,7 @@ pub struct MempoolTransaction {
     pub ranking_score: u64,
     pub timeline_state: TimelineState,
     pub sequence_info: SequenceInfo,
-    pub insertion_time: SystemTime,
+    pub insertion_info: InsertionInfo,
     pub was_parked: bool,
 }
 
@@ -34,6 +34,7 @@ impl MempoolTransaction {
         timeline_state: TimelineState,
         seqno: u64,
         insertion_time: SystemTime,
+        client_submitted: bool,
     ) -> Self {
         Self {
             sequence_info: SequenceInfo {
@@ -44,7 +45,7 @@ impl MempoolTransaction {
             expiration_time,
             ranking_score,
             timeline_state,
-            insertion_time,
+            insertion_info: InsertionInfo::new(insertion_time, client_submitted, timeline_state),
             was_parked: false,
         }
     }
@@ -84,6 +85,62 @@ pub struct SequenceInfo {
     pub account_sequence_number: u64,
 }
 
+#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
+pub enum SubmittedBy {
+    /// The transaction was received from a client REST API submission, rather than a mempool
+    /// broadcast. This can be used as the time a transaction first entered the network,
+    /// to measure end-to-end latency within the entire network. However, if a transaction is
+    /// submitted to multiple nodes (by the client) then the end-to-end latency measured will not
+    /// be accurate (the measured value will be lower than the correct value).
+    Client,
+    /// The transaction was received from a downstream peer, i.e., not a client or a peer validator.
+    /// At a validator, a transaction from downstream can be used as the time a transaction first
+    /// entered the validator network, to measure end-to-end latency within the validator network.
+    /// However, if a transaction enters via multiple validators (due to duplication outside of the
+    /// validator network) then the validator end-to-end latency measured will not be accurate
+    /// (the measured value will be lower than the correct value).
+    Downstream,
+    /// The transaction was received at a validator from another validator, rather than from the
+    /// downstream VFN. This transaction should not be used to measure end-to-end latency within the
+    /// validator network (see Downstream).
+    /// Note, with Quorum Store enabled, no transactions will be classified as PeerValidator.
+    PeerValidator,
+}
+
+#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
+pub struct InsertionInfo {
+    pub insertion_time: SystemTime,
+    pub submitted_by: SubmittedBy,
+}
+
+impl InsertionInfo {
+    pub fn new(
+        insertion_time: SystemTime,
+        client_submitted: bool,
+        timeline_state: TimelineState,
+    ) -> Self {
+        let submitted_by = if client_submitted {
+            SubmittedBy::Client
+        } else if timeline_state == TimelineState::NonQualified {
+            SubmittedBy::PeerValidator
+        } else {
+            SubmittedBy::Downstream
+        };
+        Self {
+            insertion_time,
+            submitted_by,
+        }
+    }
+
+    pub fn submitted_by_label(&self) -> &'static str {
+        match self.submitted_by {
+            SubmittedBy::Client => counters::SUBMITTED_BY_CLIENT_LABEL,
+            SubmittedBy::Downstream => counters::SUBMITTED_BY_DOWNSTREAM_LABEL,
+            SubmittedBy::PeerValidator => counters::SUBMITTED_BY_PEER_VALIDATOR_LABEL,
+        }
+    }
+}
+
 #[cfg(test)]
 mod test {
     use crate::core_mempool::{MempoolTransaction, TimelineState};
@@ -113,6 +170,7 @@ mod test {
             TimelineState::NotReady,
             0,
             SystemTime::now(),
+            false,
         )
     }
 
diff --git a/mempool/src/core_mempool/transaction_store.rs b/mempool/src/core_mempool/transaction_store.rs
index 3fb620d718eea..3e5990920c44e 100644
--- a/mempool/src/core_mempool/transaction_store.rs
+++ b/mempool/src/core_mempool/transaction_store.rs
@@ -8,14 +8,12 @@ use crate::{
             AccountTransactions, MultiBucketTimelineIndex, ParkingLotIndex, PriorityIndex,
             PriorityQueueIter, TTLIndex,
         },
-        transaction::{MempoolTransaction, TimelineState},
+        mempool::Mempool,
+        transaction::{InsertionInfo, MempoolTransaction, TimelineState},
         TxnPointer,
     },
     counters,
-    counters::{
-        BROADCAST_BATCHED_LABEL, BROADCAST_READY_LABEL, CONSENSUS_READY_LABEL, E2E_LABEL,
-        LOCAL_LABEL,
-    },
+    counters::{BROADCAST_BATCHED_LABEL, BROADCAST_READY_LABEL, CONSENSUS_READY_LABEL},
     logging::{LogEntry, LogEvent, LogSchema, TxnsLog},
     shared_mempool::types::MultiBucketTimelineIndexIds,
 };
@@ -158,18 +156,13 @@ impl TransactionStore {
         }
     }
 
-    /// Return (SystemTime, is the timestamp for end-to-end)
-    pub(crate) fn get_insertion_time_and_bucket(
+    pub(crate) fn get_insertion_info_and_bucket(
         &self,
         address: &AccountAddress,
         sequence_number: u64,
-    ) -> Option<(&SystemTime, bool, &str)> {
+    ) -> Option<(&InsertionInfo, &str)> {
         if let Some(txn) = self.get_mempool_txn(address, sequence_number) {
-            return Some((
-                &txn.insertion_time,
-                txn.timeline_state != TimelineState::NonQualified,
-                self.get_bucket(txn.ranking_score),
-            ));
+            return Some((&txn.insertion_info, self.get_bucket(txn.ranking_score)));
         }
         None
     }
@@ -382,35 +375,41 @@ impl TransactionStore {
     fn log_ready_transaction(
         ranking_score: u64,
         bucket: &str,
-        time_delta: Duration,
+        insertion_info: InsertionInfo,
         broadcast_ready: bool,
     ) {
+        if let Ok(time_delta) = SystemTime::now().duration_since(insertion_info.insertion_time) {
+            let submitted_by = insertion_info.submitted_by_label();
+            if broadcast_ready {
+                counters::core_mempool_txn_commit_latency(
+                    CONSENSUS_READY_LABEL,
+                    submitted_by,
+                    bucket,
+                    time_delta,
+                );
+                counters::core_mempool_txn_commit_latency(
+                    BROADCAST_READY_LABEL,
+                    submitted_by,
+                    bucket,
+                    time_delta,
+                );
+            } else {
+                counters::core_mempool_txn_commit_latency(
+                    CONSENSUS_READY_LABEL,
+                    submitted_by,
+                    bucket,
+                    time_delta,
+                );
+            }
+        }
+
         if broadcast_ready {
-            counters::core_mempool_txn_commit_latency(
-                CONSENSUS_READY_LABEL,
-                E2E_LABEL,
-                bucket,
-                time_delta,
-            );
-            counters::core_mempool_txn_commit_latency(
-                BROADCAST_READY_LABEL,
-                E2E_LABEL,
-                bucket,
-                time_delta,
-            );
             counters::core_mempool_txn_ranking_score(
                 BROADCAST_READY_LABEL,
                 BROADCAST_READY_LABEL,
                 bucket,
                 ranking_score,
             );
-        } else {
-            counters::core_mempool_txn_commit_latency(
-                CONSENSUS_READY_LABEL,
-                LOCAL_LABEL,
-                bucket,
-                time_delta,
-            );
         }
         counters::core_mempool_txn_ranking_score(
             CONSENSUS_READY_LABEL,
@@ -439,14 +438,12 @@ impl TransactionStore {
                 }
 
                 if process_ready {
-                    if let Ok(time_delta) = SystemTime::now().duration_since(txn.insertion_time) {
-                        Self::log_ready_transaction(
-                            txn.ranking_score,
-                            self.timeline_index.get_bucket(txn.ranking_score),
-                            time_delta,
-                            process_broadcast_ready,
-                        );
-                    }
+                    Self::log_ready_transaction(
+                        txn.ranking_score,
+                        self.timeline_index.get_bucket(txn.ranking_score),
+                        txn.insertion_info,
+                        process_broadcast_ready,
+                    );
                 }
 
                 // Remove txn from parking lot after it has been promoted to
@@ -603,22 +600,18 @@ impl TransactionStore {
                         if let TimelineState::Ready(timeline_id) = txn.timeline_state {
                             last_timeline_id[i] = timeline_id;
                         }
-                        if let Ok(time_delta) = SystemTime::now().duration_since(txn.insertion_time)
-                        {
-                            let bucket = self.timeline_index.get_bucket(txn.ranking_score);
-                            counters::core_mempool_txn_commit_latency(
-                                BROADCAST_BATCHED_LABEL,
-                                E2E_LABEL,
-                                bucket,
-                                time_delta,
-                            );
-                            counters::core_mempool_txn_ranking_score(
-                                BROADCAST_BATCHED_LABEL,
-                                BROADCAST_BATCHED_LABEL,
-                                bucket,
-                                txn.ranking_score,
-                            );
-                        }
+                        let bucket = self.timeline_index.get_bucket(txn.ranking_score);
+                        Mempool::log_txn_commit_latency(
+                            txn.insertion_info,
+                            bucket,
+                            BROADCAST_BATCHED_LABEL,
+                        );
+                        counters::core_mempool_txn_ranking_score(
+                            BROADCAST_BATCHED_LABEL,
+                            BROADCAST_BATCHED_LABEL,
+                            bucket,
+                            txn.ranking_score,
+                        );
                     }
                 }
             }
@@ -658,7 +651,7 @@ impl TransactionStore {
         for key in self.system_ttl_index.iter().take(20) {
             if let Some(txn) = self.get_mempool_txn(&key.address, key.sequence_number) {
                 if !txn.was_parked {
-                    oldest_insertion_time = Some(txn.insertion_time);
+                    oldest_insertion_time = Some(txn.insertion_info.insertion_time);
                     break;
                 }
             }
@@ -740,7 +733,9 @@ impl TransactionStore {
                     let account = txn.get_sender();
                     let txn_sequence_number = txn.sequence_info.transaction_sequence_number;
                     gc_txns_log.add_with_status(account, txn_sequence_number, status);
-                    if let Ok(time_delta) = SystemTime::now().duration_since(txn.insertion_time) {
+                    if let Ok(time_delta) =
+                        SystemTime::now().duration_since(txn.insertion_info.insertion_time)
+                    {
                         counters::CORE_MEMPOOL_GC_LATENCY
                             .with_label_values(&[metric_label, status])
                             .observe(time_delta.as_secs_f64());
@@ -773,7 +768,12 @@ impl TransactionStore {
                 } else {
                     "ready"
                 };
-                txns_log.add_full_metadata(*account, *seq_num, status, txn.insertion_time);
+                txns_log.add_full_metadata(
+                    *account,
+                    *seq_num,
+                    status,
+                    txn.insertion_info.insertion_time,
+                );
             }
         }
         txns_log
diff --git a/mempool/src/counters.rs b/mempool/src/counters.rs
index 586332efeebe3..3984791f91593 100644
--- a/mempool/src/counters.rs
+++ b/mempool/src/counters.rs
@@ -85,14 +85,15 @@ pub const SENT_LABEL: &str = "sent";
 // invalid ACK type labels
 pub const UNKNOWN_PEER: &str = "unknown_peer";
 
-// Inserted transaction scope labels
-pub const LOCAL_LABEL: &str = "local";
-pub const E2E_LABEL: &str = "e2e";
-
 // Event types for ranking_score
 pub const INSERT_LABEL: &str = "insert";
 pub const REMOVE_LABEL: &str = "remove";
 
+// The submission point where the transaction originated from
+pub const SUBMITTED_BY_CLIENT_LABEL: &str = "client";
+pub const SUBMITTED_BY_DOWNSTREAM_LABEL: &str = "downstream";
+pub const SUBMITTED_BY_PEER_VALIDATOR_LABEL: &str = "peer_validator";
+
 // Histogram buckets that make more sense at larger timescales than DEFAULT_BUCKETS
 const LARGER_LATENCY_BUCKETS: &[f64; 11] = &[
     0.25, 0.5, 1.0, 2.5, 5.0, 10.0, 20.0, 40.0, 80.0, 160.0, 320.0,
@@ -179,12 +180,12 @@ pub static CORE_MEMPOOL_IDEMPOTENT_TXNS: Lazy = Lazy::new(|| {
 
 pub fn core_mempool_txn_commit_latency(
     stage: &'static str,
-    scope: &'static str,
+    submitted_by: &'static str,
     bucket: &str,
     latency: Duration,
 ) {
     CORE_MEMPOOL_TXN_COMMIT_LATENCY
-        .with_label_values(&[stage, scope, bucket])
+        .with_label_values(&[stage, submitted_by, bucket])
         .observe(latency.as_secs_f64());
 }
 
@@ -196,7 +197,7 @@ static CORE_MEMPOOL_TXN_COMMIT_LATENCY: Lazy = Lazy::new(|| {
         "Latency of txn reaching various stages in core mempool after insertion",
         LARGER_LATENCY_BUCKETS.to_vec()
     );
-    register_histogram_vec!(histogram_opts, &["stage", "scope", "bucket"]).unwrap()
+    register_histogram_vec!(histogram_opts, &["stage", "submitted_by", "bucket"]).unwrap()
 });
 
 pub fn core_mempool_txn_ranking_score(
diff --git a/mempool/src/shared_mempool/tasks.rs b/mempool/src/shared_mempool/tasks.rs
index 8c1ee6b69c634..4d952c2330c63 100644
--- a/mempool/src/shared_mempool/tasks.rs
+++ b/mempool/src/shared_mempool/tasks.rs
@@ -117,7 +117,7 @@ pub(crate) async fn process_client_transaction_submission
     smp: &SharedMempool,
     transactions: Vec,
     timeline_state: TimelineState,
+    client_submitted: bool,
 ) -> Vec
 where
     NetworkClient: NetworkClientInterface,
@@ -308,7 +309,13 @@ where
         })
         .collect();
 
-    validate_and_add_transactions(transactions, smp, timeline_state, &mut statuses);
+    validate_and_add_transactions(
+        transactions,
+        smp,
+        timeline_state,
+        &mut statuses,
+        client_submitted,
+    );
     notify_subscribers(SharedMempoolNotification::NewTransactions, &smp.subscribers);
     statuses
 }
@@ -321,6 +328,7 @@ fn validate_and_add_transactions(
     smp: &SharedMempool,
     timeline_state: TimelineState,
     statuses: &mut Vec<(SignedTransaction, (MempoolStatus, Option))>,
+    client_submitted: bool,
 ) where
     NetworkClient: NetworkClientInterface,
     TransactionValidator: TransactionValidation,
@@ -346,6 +354,7 @@ fn validate_and_add_transactions(
                             ranking_score,
                             sequence_info,
                             timeline_state,
+                            client_submitted,
                         );
                         statuses.push((transaction, (mempool_status, None)));
                     },
@@ -385,13 +394,20 @@ fn validate_and_add_transactions(
     smp: &SharedMempool,
     timeline_state: TimelineState,
     statuses: &mut Vec<(SignedTransaction, (MempoolStatus, Option))>,
+    client_submitted: bool,
 ) where
     NetworkClient: NetworkClientInterface,
     TransactionValidator: TransactionValidation,
 {
     let mut mempool = smp.mempool.lock();
     for (transaction, sequence_info) in transactions.into_iter() {
-        let mempool_status = mempool.add_txn(transaction.clone(), 0, sequence_info, timeline_state);
+        let mempool_status = mempool.add_txn(
+            transaction.clone(),
+            0,
+            sequence_info,
+            timeline_state,
+            client_submitted,
+        );
         statuses.push((transaction, (mempool_status, None)));
     }
 }
diff --git a/mempool/src/tests/common.rs b/mempool/src/tests/common.rs
index b4b30c8ab8bef..4085cb7ec0af8 100644
--- a/mempool/src/tests/common.rs
+++ b/mempool/src/tests/common.rs
@@ -122,6 +122,7 @@ pub(crate) fn add_txns_to_mempool(
             txn.gas_unit_price(),
             transaction.account_seqno,
             TimelineState::NotReady,
+            false,
         );
         transactions.push(txn);
     }
@@ -139,6 +140,7 @@ pub(crate) fn add_signed_txn(pool: &mut CoreMempool, transaction: SignedTransact
             transaction.gas_unit_price(),
             0,
             TimelineState::NotReady,
+            false,
         )
         .code
     {
diff --git a/mempool/src/tests/core_mempool_test.rs b/mempool/src/tests/core_mempool_test.rs
index 81d55de50a702..c4cae0ac76611 100644
--- a/mempool/src/tests/core_mempool_test.rs
+++ b/mempool/src/tests/core_mempool_test.rs
@@ -3,7 +3,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::{
-    core_mempool::{CoreMempool, MempoolTransaction, TimelineState},
+    core_mempool::{CoreMempool, MempoolTransaction, SubmittedBy, TimelineState},
     tests::common::{
         add_signed_txn, add_txn, add_txns_to_mempool, setup_mempool,
         setup_mempool_with_broadcast_buckets, TestTransaction,
@@ -73,28 +73,44 @@ fn test_transaction_metrics() {
         txn.gas_unit_price(),
         0,
         TimelineState::NotReady,
+        false,
     );
-    let txn = TestTransaction::new(1, 0, 2).make_signed_transaction();
+    let txn = TestTransaction::new(1, 0, 1).make_signed_transaction();
     mempool.add_txn(
         txn.clone(),
         txn.gas_unit_price(),
         0,
         TimelineState::NonQualified,
+        false,
+    );
+    let txn = TestTransaction::new(2, 0, 1).make_signed_transaction();
+    mempool.add_txn(
+        txn.clone(),
+        txn.gas_unit_price(),
+        0,
+        TimelineState::NotReady,
+        true,
     );
 
     // Check timestamp returned as end-to-end for broadcast-able transaction
-    let (&_insertion_time, is_end_to_end, _bucket) = mempool
+    let (insertion_info, _bucket) = mempool
         .get_transaction_store()
-        .get_insertion_time_and_bucket(&TestTransaction::get_address(0), 0)
+        .get_insertion_info_and_bucket(&TestTransaction::get_address(0), 0)
         .unwrap();
-    assert!(is_end_to_end);
+    assert_eq!(insertion_info.submitted_by, SubmittedBy::Downstream);
 
     // Check timestamp returned as not end-to-end for non-broadcast-able transaction
-    let (&_insertion_time, is_end_to_end, _bucket) = mempool
+    let (insertion_info, _bucket) = mempool
         .get_transaction_store()
-        .get_insertion_time_and_bucket(&TestTransaction::get_address(1), 0)
+        .get_insertion_info_and_bucket(&TestTransaction::get_address(1), 0)
         .unwrap();
-    assert!(!is_end_to_end);
+    assert_eq!(insertion_info.submitted_by, SubmittedBy::PeerValidator);
+
+    let (insertion_info, _bucket) = mempool
+        .get_transaction_store()
+        .get_insertion_info_and_bucket(&TestTransaction::get_address(2), 0)
+        .unwrap();
+    assert_eq!(insertion_info.submitted_by, SubmittedBy::Client);
 }
 
 #[test]
@@ -548,6 +564,7 @@ fn test_capacity_bytes() {
                 txn.ranking_score,
                 txn.sequence_info.account_sequence_number,
                 txn.timeline_state,
+                false,
             );
             assert_eq!(status.code, MempoolStatusCode::Accepted);
         });
@@ -558,6 +575,7 @@ fn test_capacity_bytes() {
                 txn.ranking_score,
                 txn.sequence_info.account_sequence_number,
                 txn.timeline_state,
+                false,
             );
             assert_eq!(status.code, MempoolStatusCode::MempoolIsFull);
         }
@@ -575,6 +593,7 @@ fn new_test_mempool_transaction(address: usize, sequence_number: u64) -> Mempool
         TimelineState::NotReady,
         0,
         SystemTime::now(),
+        false,
     )
 }
 
@@ -643,7 +662,7 @@ fn test_gc_ready_transaction() {
 
     // Insert in the middle transaction that's going to be expired.
     let txn = TestTransaction::new(1, 1, 1).make_signed_transaction_with_expiration_time(0);
-    pool.add_txn(txn, 1, 0, TimelineState::NotReady);
+    pool.add_txn(txn, 1, 0, TimelineState::NotReady, false);
 
     // Insert few transactions after it.
     // They are supposed to be ready because there's a sequential path from 0 to them.
@@ -682,7 +701,7 @@ fn test_clean_stuck_transactions() {
     }
     let db_sequence_number = 10;
     let txn = TestTransaction::new(0, db_sequence_number, 1).make_signed_transaction();
-    pool.add_txn(txn, 1, db_sequence_number, TimelineState::NotReady);
+    pool.add_txn(txn, 1, db_sequence_number, TimelineState::NotReady, false);
     let block = pool.get_batch(1, 1024, true, false, vec![]);
     assert_eq!(block.len(), 1);
     assert_eq!(block[0].sequence_number(), 10);
@@ -693,7 +712,13 @@ fn test_get_transaction_by_hash() {
     let mut pool = setup_mempool().0;
     let db_sequence_number = 10;
     let txn = TestTransaction::new(0, db_sequence_number, 1).make_signed_transaction();
-    pool.add_txn(txn.clone(), 1, db_sequence_number, TimelineState::NotReady);
+    pool.add_txn(
+        txn.clone(),
+        1,
+        db_sequence_number,
+        TimelineState::NotReady,
+        false,
+    );
     let hash = txn.clone().committed_hash();
     let ret = pool.get_by_hash(hash);
     assert_eq!(ret, Some(txn));
@@ -707,7 +732,13 @@ fn test_get_transaction_by_hash_after_the_txn_is_updated() {
     let mut pool = setup_mempool().0;
     let db_sequence_number = 10;
     let txn = TestTransaction::new(0, db_sequence_number, 1).make_signed_transaction();
-    pool.add_txn(txn.clone(), 1, db_sequence_number, TimelineState::NotReady);
+    pool.add_txn(
+        txn.clone(),
+        1,
+        db_sequence_number,
+        TimelineState::NotReady,
+        false,
+    );
     let hash = txn.committed_hash();
 
     // new txn with higher gas price
@@ -717,6 +748,7 @@ fn test_get_transaction_by_hash_after_the_txn_is_updated() {
         1,
         db_sequence_number,
         TimelineState::NotReady,
+        false,
     );
     let new_txn_hash = new_txn.clone().committed_hash();
 
diff --git a/mempool/src/tests/fuzzing.rs b/mempool/src/tests/fuzzing.rs
index 898f2efadddb5..2b756bcb6a33f 100644
--- a/mempool/src/tests/fuzzing.rs
+++ b/mempool/src/tests/fuzzing.rs
@@ -57,7 +57,7 @@ pub fn test_mempool_process_incoming_transactions_impl(
         config.base.role,
     );
 
-    let _ = tasks::process_incoming_transactions(&smp, txns, timeline_state);
+    let _ = tasks::process_incoming_transactions(&smp, txns, timeline_state, false);
 }
 
 proptest! {
diff --git a/mempool/src/tests/mocks.rs b/mempool/src/tests/mocks.rs
index 92ec705f8c388..b7259bb783355 100644
--- a/mempool/src/tests/mocks.rs
+++ b/mempool/src/tests/mocks.rs
@@ -166,6 +166,7 @@ impl MockSharedMempool {
                         txn.gas_unit_price(),
                         0,
                         TimelineState::NotReady,
+                        false,
                     )
                     .code
                     != MempoolStatusCode::Accepted
diff --git a/mempool/src/tests/node.rs b/mempool/src/tests/node.rs
index b5d715e257d9f..d2537c36a06e1 100644
--- a/mempool/src/tests/node.rs
+++ b/mempool/src/tests/node.rs
@@ -375,6 +375,7 @@ impl Node {
                 transaction.gas_unit_price(),
                 0,
                 TimelineState::NotReady,
+                false,
             );
         }
     }

From aaadc26166e57780c01e566cedc1588ecadd9d78 Mon Sep 17 00:00:00 2001
From: Teng Zhang 
Date: Tue, 6 Jun 2023 18:57:02 -0700
Subject: [PATCH 084/200] [Prover][Spec] Fix apply schema (#8518)

* fix apply schema

* fix coin spec

* fix trigger condition for build jobs

---------

Co-authored-by: geekflyer 
---
 .../framework/aptos-framework/doc/coin.md      |  6 ++++--
 .../aptos-framework/sources/coin.spec.move     |  6 ++++--
 .../move-model/src/builder/module_builder.rs   |  8 +++++---
 .../tests/sources/functional/schema_apply.exp  |  8 ++++++++
 .../tests/sources/functional/schema_apply.move | 18 ++++++++++++++++++
 5 files changed, 39 insertions(+), 7 deletions(-)
 create mode 100644 third_party/move/move-prover/tests/sources/functional/schema_apply.exp
 create mode 100644 third_party/move/move-prover/tests/sources/functional/schema_apply.move

diff --git a/aptos-move/framework/aptos-framework/doc/coin.md b/aptos-move/framework/aptos-framework/doc/coin.md
index 12c1cea63524f..1dc3bd18f4d2b 100644
--- a/aptos-move/framework/aptos-framework/doc/coin.md
+++ b/aptos-move/framework/aptos-framework/doc/coin.md
@@ -1889,8 +1889,10 @@ Destroy a burn capability.
 
 
 
schema TotalSupplyTracked<CoinType> {
-    invariant spec_fun_supply_tracked<CoinType>(supply<CoinType> + aggregate_supply<CoinType>,
-                global<CoinInfo<CoinType>>(type_info::type_of<CoinType>().account_address).supply);
+    ensures old(spec_fun_supply_tracked<CoinType>(supply<CoinType> + aggregate_supply<CoinType>,
+        global<CoinInfo<CoinType>>(type_info::type_of<CoinType>().account_address).supply)) ==>
+        spec_fun_supply_tracked<CoinType>(supply<CoinType> + aggregate_supply<CoinType>,
+            global<CoinInfo<CoinType>>(type_info::type_of<CoinType>().account_address).supply);
 }
 

 
diff --git a/aptos-move/framework/aptos-framework/sources/coin.spec.move b/aptos-move/framework/aptos-framework/sources/coin.spec.move
index 0aea237d0ced4..da2e8a308f38d 100644
--- a/aptos-move/framework/aptos-framework/sources/coin.spec.move
+++ b/aptos-move/framework/aptos-framework/sources/coin.spec.move
@@ -15,8 +15,10 @@ spec aptos_framework::coin {
     }
 
     spec schema TotalSupplyTracked {
-        invariant spec_fun_supply_tracked(supply + aggregate_supply,
-                    global>(type_info::type_of().account_address).supply);
+        ensures old(spec_fun_supply_tracked(supply + aggregate_supply,
+            global>(type_info::type_of().account_address).supply)) ==>
+            spec_fun_supply_tracked(supply + aggregate_supply,
+                global>(type_info::type_of().account_address).supply);
     }
 
     spec fun spec_fun_supply_no_change(old_supply: Option,
diff --git a/third_party/move/move-model/src/builder/module_builder.rs b/third_party/move/move-model/src/builder/module_builder.rs
index 3226db0480166..6c93c5f97be2b 100644
--- a/third_party/move/move-model/src/builder/module_builder.rs
+++ b/third_party/move/move-model/src/builder/module_builder.rs
@@ -22,8 +22,8 @@ use crate::{
     options::ModelBuilderOptions,
     pragmas::{
         is_pragma_valid_for_block, is_property_valid_for_condition, CONDITION_ABSTRACT_PROP,
-        CONDITION_CONCRETE_PROP, CONDITION_DEACTIVATED_PROP, CONDITION_INJECTED_PROP,
-        OPAQUE_PRAGMA, VERIFY_PRAGMA,
+        CONDITION_CONCRETE_PROP, CONDITION_DEACTIVATED_PROP, CONDITION_EXPORT_PROP,
+        CONDITION_INJECTED_PROP, OPAQUE_PRAGMA, VERIFY_PRAGMA,
     },
     symbol::{Symbol, SymbolPool},
     ty::{PrimitiveType, Type, BOOL_TYPE},
@@ -2951,8 +2951,10 @@ impl<'env, 'translator> ModuleBuilder<'env, 'translator> {
                     et.get_type_params()
                 };
                 // Create a property marking this as injected.
-                let context_properties =
+                let mut context_properties =
                     self.add_bool_property(PropertyBag::default(), CONDITION_INJECTED_PROP, true);
+                context_properties =
+                    self.add_bool_property(context_properties, CONDITION_EXPORT_PROP, true);
                 self.def_ana_schema_inclusion_outside_schema(
                     loc,
                     &SpecBlockContext::Function(fun_name),
diff --git a/third_party/move/move-prover/tests/sources/functional/schema_apply.exp b/third_party/move/move-prover/tests/sources/functional/schema_apply.exp
new file mode 100644
index 0000000000000..226c05ee84a21
--- /dev/null
+++ b/third_party/move/move-prover/tests/sources/functional/schema_apply.exp
@@ -0,0 +1,8 @@
+Move prover returns: exiting with verification errors
+error: precondition does not hold at this call
+   ┌─ tests/sources/functional/schema_apply.move:16:9
+   │
+16 │         requires false;
+   │         ^^^^^^^^^^^^^^^
+   │
+   =     at tests/sources/functional/schema_apply.move:16
diff --git a/third_party/move/move-prover/tests/sources/functional/schema_apply.move b/third_party/move/move-prover/tests/sources/functional/schema_apply.move
new file mode 100644
index 0000000000000..91c6ca5230699
--- /dev/null
+++ b/third_party/move/move-prover/tests/sources/functional/schema_apply.move
@@ -0,0 +1,18 @@
+module 0x42::requires {
+    public fun g() {
+        f();
+    }
+
+    public fun f() {
+    }
+    spec f {
+    }
+
+    spec module {
+        apply RequiresFalse to f;
+    }
+
+    spec schema RequiresFalse {
+        requires false;
+    }
+}

From 3a0c43372a889ba39383cbb9564b498889984c9c Mon Sep 17 00:00:00 2001
From: William Law 
Date: Tue, 6 Jun 2023 22:25:20 -0700
Subject: [PATCH 085/200] [aptos-gas] fix typo (#8540)

---
 aptos-move/aptos-gas/src/gas_meter.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/aptos-move/aptos-gas/src/gas_meter.rs b/aptos-move/aptos-gas/src/gas_meter.rs
index 3851f84aef59e..30a1bcc676c83 100644
--- a/aptos-move/aptos-gas/src/gas_meter.rs
+++ b/aptos-move/aptos-gas/src/gas_meter.rs
@@ -54,7 +54,7 @@ use std::collections::BTreeMap;
 //   - Storage charges:
 //     - Distinguish between new and existing resources
 //     - One item write comes with 1K free bytes
-//     - abort with STORATGE_WRITE_LIMIT_REACHED if WriteOps or Events are too large
+//     - abort with STORAGE_WRITE_LIMIT_REACHED if WriteOps or Events are too large
 // - V2
 //   - Table
 //     - Fix the gas formula for loading resources so that they are consistent with other

From eac528c77fcd54d0562367c302efcd624b20ce8d Mon Sep 17 00:00:00 2001
From: Jin <128556004+0xjinn@users.noreply.github.com>
Date: Wed, 7 Jun 2023 05:12:32 -0700
Subject: [PATCH 086/200] mark crypto and types public (#8543)

---
 crates/aptos-ledger/src/lib.rs | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/crates/aptos-ledger/src/lib.rs b/crates/aptos-ledger/src/lib.rs
index 72f9812d100bc..a2442044877d4 100644
--- a/crates/aptos-ledger/src/lib.rs
+++ b/crates/aptos-ledger/src/lib.rs
@@ -7,8 +7,10 @@
 
 #![deny(missing_docs)]
 
-use aptos_crypto::{ed25519::Ed25519PublicKey, ValidCryptoMaterialStringExt};
-use aptos_types::{account_address::AccountAddress, transaction::authenticator::AuthenticationKey};
+pub use aptos_crypto::{ed25519::Ed25519PublicKey, ValidCryptoMaterialStringExt};
+pub use aptos_types::{
+    account_address::AccountAddress, transaction::authenticator::AuthenticationKey,
+};
 use hex::encode;
 use ledger_apdu::APDUCommand;
 use ledger_transport_hid::{hidapi::HidApi, LedgerHIDError, TransportNativeHID};

From c06488341e3337dd1257b901e78a1557b2b80c80 Mon Sep 17 00:00:00 2001
From: Jin <128556004+0xjinn@users.noreply.github.com>
Date: Wed, 7 Jun 2023 07:19:49 -0700
Subject: [PATCH 087/200] update version (#8562)

---
 ecosystem/python/sdk/setup.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ecosystem/python/sdk/setup.py b/ecosystem/python/sdk/setup.py
index fe9a526f997d2..b63e624d26eae 100644
--- a/ecosystem/python/sdk/setup.py
+++ b/ecosystem/python/sdk/setup.py
@@ -19,5 +19,5 @@
     packages=["aptos_sdk"],
     python_requires=">=3.7",
     url="https://github.com/aptos-labs/aptos-core",
-    version="0.6.0",
+    version="0.6.2",
 )

From c10ec10d61e2854a7030f3d7bbff276408c856e0 Mon Sep 17 00:00:00 2001
From: Maayan 
Date: Wed, 7 Jun 2023 17:59:32 +0300
Subject: [PATCH 088/200] [TS SDK] Support write operations for Fungible Assets
 (#8294)

* add token v2 support

* support aptos token

* support aptos token

* add functionalities support

* get token address from txn events

* get token address from txn events

* get token address from txn events

* update changelog

* move fungiable asset yransfer method to fungible asset client class

* add support for fungible assets

* change console warn message

* add tests for fungible asset client

* support fungible asset in coin client

* modify changelog

* revert unneeded changes

* update comments

* reorganize

* reorganize

* fix lint

* address feedback

* remove type argument parameters

* support get balance for any fungible store

* Revert "support get balance for any fungible store"

This reverts commit a2dd855e1b23224309e9161d977494b093784ccb.

* support fa in coin client class

* support fa in coin client class

* support fa in coin client class

* fix lint

* comments

* update changelog

* update changelog

* rename functions
---
 ecosystem/typescript/sdk/CHANGELOG.md         |   2 +
 .../typescript/sdk/src/plugins/coin_client.ts |  62 ++++++++-
 .../sdk/src/plugins/fungible_asset_client.ts  | 102 ++++++++++++++
 ecosystem/typescript/sdk/src/plugins/index.ts |   1 +
 .../sdk/src/providers/aptos_client.ts         |  15 +-
 .../tests/e2e/fungible_asset_client.test.ts   | 128 ++++++++++++++++++
 .../typescript/sdk/src/utils/api-endpoints.ts |   6 +
 7 files changed, 309 insertions(+), 7 deletions(-)
 create mode 100644 ecosystem/typescript/sdk/src/plugins/fungible_asset_client.ts
 create mode 100644 ecosystem/typescript/sdk/src/tests/e2e/fungible_asset_client.test.ts

diff --git a/ecosystem/typescript/sdk/CHANGELOG.md b/ecosystem/typescript/sdk/CHANGELOG.md
index 151f0b5be3108..3d9909697182d 100644
--- a/ecosystem/typescript/sdk/CHANGELOG.md
+++ b/ecosystem/typescript/sdk/CHANGELOG.md
@@ -9,6 +9,8 @@ All notable changes to the Aptos Node SDK will be captured in this file. This ch
 - Change `indexerUrl` param on `Provider` class to an optional parameter
 - Add `getCollectionsWithOwnedTokens` query to fetch all collections that an account has tokens for
 - Support `tokenStandard` param in `getOwnedTokens` and `getTokenOwnedFromCollectionAddress` queries
+- Add `FungibleAssetClient` plugin to support fungible assets
+- Support fungible assets in `CoinClient` class operations
 
 ## 1.9.1 (2023-05-24)
 
diff --git a/ecosystem/typescript/sdk/src/plugins/coin_client.ts b/ecosystem/typescript/sdk/src/plugins/coin_client.ts
index 8eff1e09d1337..4d45f86a4472a 100644
--- a/ecosystem/typescript/sdk/src/plugins/coin_client.ts
+++ b/ecosystem/typescript/sdk/src/plugins/coin_client.ts
@@ -1,10 +1,12 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
-
 import { AptosAccount, getAddressFromAccountOrAddress } from "../account/aptos_account";
 import { AptosClient, OptionalTransactionArgs } from "../providers/aptos_client";
-import { MaybeHexString, APTOS_COIN } from "../utils";
+import { MaybeHexString, APTOS_COIN, NetworkToIndexerAPI, NodeAPIToNetwork } from "../utils";
 import { TransactionBuilderRemoteABI } from "../transaction_builder";
+import { FungibleAssetClient } from "./fungible_asset_client";
+import { Provider } from "../providers";
+import { AccountAddress } from "../aptos_types";
 
 /**
  * Class for working with the coin module, such as transferring coins and
@@ -32,6 +34,11 @@ export class CoinClient {
    * this to true, the transaction will fail if the receiver account does not
    * exist on-chain.
    *
+   * The TS SDK supports fungible assets operations. If you want to use CoinClient
+   * with this feature, set the `coinType` to be the fungible asset metadata address.
+   * This option uses the `FungibleAssetClient` class and queries the
+   * fungible asset primary store.
+   *
    * @param from Account sending the coins
    * @param to Account to receive the coins
    * @param amount Number of coins to transfer
@@ -45,8 +52,10 @@ export class CoinClient {
     to: AptosAccount | MaybeHexString,
     amount: number | bigint,
     extraArgs?: OptionalTransactionArgs & {
-      // The coin type to use, defaults to 0x1::aptos_coin::AptosCoin
-      coinType?: string;
+      // The coin type to use, defaults to 0x1::aptos_coin::AptosCoin.
+      // If you want to transfer a fungible asset, set this param to be the
+      // fungible asset address
+      coinType?: string | MaybeHexString;
       // If set, create the `receiver` account if it doesn't exist on-chain.
       // This is done by calling `0x1::aptos_account::transfer` instead, which
       // will create the account on-chain first if it doesn't exist before
@@ -56,6 +65,23 @@ export class CoinClient {
       createReceiverIfMissing?: boolean;
     },
   ): Promise {
+    if (extraArgs?.coinType && AccountAddress.isValid(extraArgs.coinType)) {
+      /* eslint-disable no-console */
+      console.warn("to transfer a fungible asset, use `FungibleAssetClient()` class for better support");
+      const provider = new Provider({
+        fullnodeUrl: this.aptosClient.nodeUrl,
+        indexerUrl: NetworkToIndexerAPI[NodeAPIToNetwork[this.aptosClient.nodeUrl]] ?? this.aptosClient.nodeUrl,
+      });
+      const fungibleAsset = new FungibleAssetClient(provider);
+      const txnHash = await fungibleAsset.transfer(
+        from,
+        extraArgs?.coinType,
+        getAddressFromAccountOrAddress(to),
+        amount,
+      );
+      return txnHash;
+    }
+
     // If none is explicitly given, use 0x1::aptos_coin::AptosCoin as the coin type.
     const coinTypeToTransfer = extraArgs?.coinType ?? APTOS_COIN;
 
@@ -67,7 +93,7 @@ export class CoinClient {
     const toAddress = getAddressFromAccountOrAddress(to);
 
     const builder = new TransactionBuilderRemoteABI(this.aptosClient, { sender: from.address(), ...extraArgs });
-    const rawTxn = await builder.build(func, [coinTypeToTransfer], [toAddress, amount]);
+    const rawTxn = await builder.build(func, [coinTypeToTransfer as string], [toAddress, amount]);
 
     const bcsTxn = AptosClient.generateBCSTransaction(from, rawTxn);
     const pendingTransaction = await this.aptosClient.submitSignedBCSTransaction(bcsTxn);
@@ -78,6 +104,13 @@ export class CoinClient {
    * Get the balance of the account. By default it checks the balance of
    * 0x1::aptos_coin::AptosCoin, but you can specify a different coin type.
    *
+   * to use a different type, set the `coinType` to be the fungible asset type.
+   *
+   * The TS SDK supports fungible assets operations. If you want to use CoinClient
+   * with this feature, set the `coinType` to be the fungible asset metadata address.
+   * This option uses the FungibleAssetClient class and queries the
+   * fungible asset primary store.
+   *
    * @param account Account that you want to get the balance of.
    * @param extraArgs Extra args for checking the balance.
    * @returns Promise that resolves to the balance as a bigint.
@@ -86,10 +119,27 @@ export class CoinClient {
   async checkBalance(
     account: AptosAccount | MaybeHexString,
     extraArgs?: {
-      // The coin type to use, defaults to 0x1::aptos_coin::AptosCoin
+      // The coin type to use, defaults to 0x1::aptos_coin::AptosCoin.
+      // If you want to check the balance of a fungible asset, set this param to be the
+      // fungible asset address
       coinType?: string;
     },
   ): Promise {
+    if (extraArgs?.coinType && AccountAddress.isValid(extraArgs.coinType)) {
+      /* eslint-disable no-console */
+      console.warn("to check balance of a fungible asset, use `FungibleAssetClient()` class for better support");
+      const provider = new Provider({
+        fullnodeUrl: this.aptosClient.nodeUrl,
+        indexerUrl: NetworkToIndexerAPI[NodeAPIToNetwork[this.aptosClient.nodeUrl]] ?? this.aptosClient.nodeUrl,
+      });
+      const fungibleAsset = new FungibleAssetClient(provider);
+      const balance = await fungibleAsset.getPrimaryBalance(
+        getAddressFromAccountOrAddress(account),
+        extraArgs?.coinType,
+      );
+      return balance;
+    }
+
     const coinType = extraArgs?.coinType ?? APTOS_COIN;
     const typeTag = `0x1::coin::CoinStore<${coinType}>`;
     const address = getAddressFromAccountOrAddress(account);
diff --git a/ecosystem/typescript/sdk/src/plugins/fungible_asset_client.ts b/ecosystem/typescript/sdk/src/plugins/fungible_asset_client.ts
new file mode 100644
index 0000000000000..519413e6fc14d
--- /dev/null
+++ b/ecosystem/typescript/sdk/src/plugins/fungible_asset_client.ts
@@ -0,0 +1,102 @@
+import { AptosAccount } from "../account";
+import { RawTransaction } from "../aptos_types";
+import * as Gen from "../generated/index";
+import { OptionalTransactionArgs, Provider } from "../providers";
+import { TransactionBuilderRemoteABI } from "../transaction_builder";
+import { MaybeHexString, HexString } from "../utils";
+
+export class FungibleAssetClient {
+  provider: Provider;
+
+  readonly assetType: string = "0x1::fungible_asset::Metadata";
+
+  /**
+   * Creates new FungibleAssetClient instance
+   *
+   * @param provider Provider instance
+   */
+  constructor(provider: Provider) {
+    this.provider = provider;
+  }
+
+  /**
+   *  Transfer `amount` of fungible asset from sender's primary store to recipient's primary store.
+   *
+   * Use this method to transfer any fungible asset including fungible token.
+   *
+   * @param sender The sender account
+   * @param fungibleAssetMetadataAddress The fungible asset address.
+   * For example if you’re transferring USDT this would be the USDT address
+   * @param recipient Recipient address
+   * @param amount Number of assets to transfer
+   * @returns The hash of the transaction submitted to the API
+   */
+  async transfer(
+    sender: AptosAccount,
+    fungibleAssetMetadataAddress: MaybeHexString,
+    recipient: MaybeHexString,
+    amount: number | bigint,
+    extraArgs?: OptionalTransactionArgs,
+  ): Promise {
+    const rawTransaction = await this.generateTransfer(
+      sender,
+      fungibleAssetMetadataAddress,
+      recipient,
+      amount,
+      extraArgs,
+    );
+    const txnHash = await this.provider.signAndSubmitTransaction(sender, rawTransaction);
+    return txnHash;
+  }
+
+  /**
+   * Get the balance of a fungible asset from the account's primary fungible store.
+   *
+   * @param account Account that you want to get the balance of.
+   * @param fungibleAssetMetadataAddress The fungible asset address you want to check the balance of
+   * @returns Promise that resolves to the balance
+   */
+  async getPrimaryBalance(account: MaybeHexString, fungibleAssetMetadataAddress: MaybeHexString): Promise {
+    const payload: Gen.ViewRequest = {
+      function: "0x1::primary_fungible_store::balance",
+      type_arguments: [this.assetType],
+      arguments: [HexString.ensure(account).hex(), HexString.ensure(fungibleAssetMetadataAddress).hex()],
+    };
+    const response = await this.provider.view(payload);
+    return BigInt((response as any)[0]);
+  }
+
+  /**
+   *
+   * Generate a transfer transaction that can be used to sign and submit to transfer an asset amount
+   * from the sender primary fungible store to the recipient primary fungible store.
+   *
+   * This method can be used if you want/need to get the raw transaction so you can
+   * first simulate the transaction and then sign and submit it.
+   *
+   * @param sender The sender account
+   * @param fungibleAssetMetadataAddress The fungible asset address.
+   * For example if you’re transferring USDT this would be the USDT address
+   * @param recipient Recipient address
+   * @param amount Number of assets to transfer
+   * @returns Raw Transaction
+   */
+  async generateTransfer(
+    sender: AptosAccount,
+    fungibleAssetMetadataAddress: MaybeHexString,
+    recipient: MaybeHexString,
+    amount: number | bigint,
+    extraArgs?: OptionalTransactionArgs,
+  ): Promise {
+    const builder = new TransactionBuilderRemoteABI(this.provider, {
+      sender: sender.address(),
+      ...extraArgs,
+    });
+    const rawTxn = await builder.build(
+      "0x1::primary_fungible_store::transfer",
+      [this.assetType],
+      [HexString.ensure(fungibleAssetMetadataAddress).hex(), HexString.ensure(recipient).hex(), amount],
+    );
+    return rawTxn;
+  }
+}
diff --git a/ecosystem/typescript/sdk/src/plugins/index.ts b/ecosystem/typescript/sdk/src/plugins/index.ts
index 9e2df7900c51c..007f729f63e18 100644
--- a/ecosystem/typescript/sdk/src/plugins/index.ts
+++ b/ecosystem/typescript/sdk/src/plugins/index.ts
@@ -3,3 +3,4 @@ export * from "./aptos_token";
 export * from "./coin_client";
 export * from "./faucet_client";
 export * from "./ans_client";
+export * from "./fungible_asset_client";
diff --git a/ecosystem/typescript/sdk/src/providers/aptos_client.ts b/ecosystem/typescript/sdk/src/providers/aptos_client.ts
index 4e83deab9e4b4..67a50acdc577e 100644
--- a/ecosystem/typescript/sdk/src/providers/aptos_client.ts
+++ b/ecosystem/typescript/sdk/src/providers/aptos_client.ts
@@ -35,7 +35,7 @@ import {
   Uint64,
   AnyNumber,
 } from "../bcs";
-import { Ed25519PublicKey, MultiEd25519PublicKey } from "../aptos_types";
+import { Ed25519PublicKey, MultiEd25519PublicKey, RawTransaction } from "../aptos_types";
 
 export interface OptionalTransactionArgs {
   maxGasAmount?: Uint64;
@@ -742,6 +742,19 @@ export class AptosClient {
     // <:!:generateSignSubmitTransactionInner
   }
 
+  /**
+   * Helper for signing and submitting a transaction.
+   *
+   * @param sender AptosAccount of transaction sender.
+   * @param transaction A generated Raw transaction payload.
+   * @returns The transaction response from the API.
+   */
+  async signAndSubmitTransaction(sender: AptosAccount, transaction: RawTransaction): Promise {
+    const bcsTxn = AptosClient.generateBCSTransaction(sender, transaction);
+    const pendingTransaction = await this.submitSignedBCSTransaction(bcsTxn);
+    return pendingTransaction.hash;
+  }
+
   /**
    * Publishes a move package. `packageMetadata` and `modules` can be generated with command
    * `aptos move compile --save-metadata [ --included-artifacts=<...> ]`.
diff --git a/ecosystem/typescript/sdk/src/tests/e2e/fungible_asset_client.test.ts b/ecosystem/typescript/sdk/src/tests/e2e/fungible_asset_client.test.ts
new file mode 100644
index 0000000000000..541a23f254ece
--- /dev/null
+++ b/ecosystem/typescript/sdk/src/tests/e2e/fungible_asset_client.test.ts
@@ -0,0 +1,128 @@
+import * as Gen from "../../generated/index";
+import { AptosAccount } from "../../account";
+import { AptosClient, Provider } from "../../providers";
+import { TxnBuilderTypes } from "../../transaction_builder";
+import { HexString } from "../../utils";
+import { getFaucetClient, longTestTimeout, PROVIDER_LOCAL_NETWORK_CONFIG } from "../unit/test_helper.test";
+import { CoinClient, FungibleAssetClient } from "../../plugins";
+import { RawTransaction } from "../../aptos_types";
+
+const provider = new Provider(PROVIDER_LOCAL_NETWORK_CONFIG);
+const faucetClient = getFaucetClient();
+const publisher = new AptosAccount(
+  new HexString("0x1c2b344cdc1ca1cc33d5810cf93278fd3c2a8e8ba9cd78240c1193766b06a724").toUint8Array(),
+);
+const alice = new AptosAccount();
+const bob = new AptosAccount();
+let fungibleAssetMetadataAddress = "";
+/**
+ * Since there is no ready-to-use fungible asset contract/module on an aptos framework address
+ * we pre compiled ../../../aptos-move/move-examples/fungible_token contract and publish
+ * it here to local testnet so we can interact with it to mint a fungible asset and then
+ * test FungibleAssetClient class
+ */
+describe("fungible asset", () => {
+  /**
+   * Publish the fungible_token module
+   * Mint 5 amount of fungible assets to Alice account
+   * Get the asset address and store it to a later use
+   */
+  beforeAll(async () => {
+    await faucetClient.fundAccount(publisher.address(), 100_000_000);
+    await faucetClient.fundAccount(alice.address(), 100_000_000);
+    await faucetClient.fundAccount(bob.address(), 100_000_000);
+
+    // Publish contract
+    const txnHash = await provider.publishPackage(
+      publisher,
+      new HexString(
+        // eslint-disable-next-line max-len
+        "0d46756e6769626c65546f6b656e0100000000000000004045334431344231344134414439413146423742463233424534344546313232313739303138453736304544413330463346384344373435423338383138314237b6011f8b08000000000002ff858fbb0ec3200c4577be02b12769a5ae1dba64edd22d8a22024e94260504f42155fdf76240a85b652ff6b5cfb53bc3c5ca67e889e237a047cadabb9a9771838b5e4131f200eb16ad50d9d52118211d97d28273e07ac28dd76e986c587e6abbc6b1d79ee5be47c6a0c72b08ef92766064ca0e49c6f68054090694042516049f10d0fe70df74d3826f385ed74dc862da44b3aad48c7ed27a7ce15cdcff12e23d553e17295f4b33167a1e01000001166d616e616765645f66756e6769626c655f746f6b656eee0e1f8b08000000000002ffed59eb6edb3614fe9fa7e052c0930b217686b6ebd4a668bba55b81a5019a0cc5500c0a2d51361749f4482a4e1af8dd7778d18d92eca4698a025b7e04327578782edfb95193c904bdca11b9c4d932252862d98ce6349fa3a4c8e774064b580822055a51b940929d931c56eab77a650fbdcd915c5051f2f111b6b46cf637892482578520316cdd99c089199138c65211a188132c49cdb1c8a914c0e01cfbce31626f27637191d6c4a15e0f820ce7784ee2b0bd8eae7710fcc1c1082f251361c27146568c9f074145a9d50b82eb1392263e3aa2b97c4fe0e194e35c2484eb1faf0b9eeb87232bb78fded8fdafd4f6f5b3e1838c01aa038ef5cf4d1b969c66985fd5ba08c938a93708190701e19c71674dd0794e3a8b928337e1f842264f7d74a27fae1d22b69494e5ae4cda86a1915f048135f5b5f1579883c0b1a1f1ad0fed0e4148bcdec22c62690a4f702a3c9bcd09bd0486f58b673b9a8582cb719e5e3980ac21c456a0358a708e327c0e085ee07c4e002a6a73c47221d1e1bbe3d3f0f8c3bbc3f7012a9e3c420768df3237ef5f9d9c1c9e86277f1ebd3efe3d4017703ce3cf8ba72f8070b67b7a7872ba6bc91f7ce444b08247249c73562cc38c6433c23dfd03a8079d6fbcfeab221bff55a9f51b4b63c449227418b05c729642181194010ac14d3e92168508e7319a010a5564b2c40d4ea32cb8ba80503b32b1d002285a40cc9e932b1b11ea4f9d11c2e14185f9ea5579aa79dd8c848a44c9625e97b1a15fad6b9fbd8530a638a59f48c3552619286534a8b5b2ca004601d00a41f291a189720fc72064804606d8e386f029a85423456331b0d8063728a87bb35d4944930a29aaddf1b3161303cb0dfb4d2271b70e40d6ab08d49f16df6f2d0d4816131171aa837077dcdeb1dffee928dd7e69c238087296136fdc7bf242ca65309968a0a67826f620e14f6aa6cdd31d4be9505100631a1760a6513713783d3a6f14b96bea0db6a89df565f4d6fc1c95abe7fe345c65abf2b55e0d498e81a4517f745c7a8e1d5a06bcb50ada464e1234b8f4d1e4a17e440f27dd9dcdec6648c55536834ce310ffa0dfc52402c552d1cb6ac08e09bea0a0dd1efcdbbd85f977c7bd8687dcf1b36909548a9aa84c33a9f260992d719ab2950943c6d582e900744269db68af85e232eb017cdd0e604e20c928d796349ee3312720ca14b8895549b3855533e16e62d7a4dbc2b2ccb9b6e486268702f3b224554ccd9b0dec3276a14a7b1bcda3fe03dadeef2d45d79513fc96e27e6dd1750d8c665979f0f18292555d3fdf13093bb4cf711c436916aa36ea026a0e76c3452eb0fc5ed8ec1da3d582d8b6d5b695f0149365caae486c60b32c66298d74619a13a84b56676f1cd846ee79d911bef886aa93daaa150e4bb3d46eb7e9cb3acdbe775cfbb2dd463be9dc6df5bc919be1d1a8167cdc574f4a61ecf1c0cc0a549bd36b293076bb0bd5b3a8394439db3480e079a7cf68b9904077a57b488d3ea7b580692363452e757b08a8644109a831c2d13f0585c70130778d0ec66e63c5094c77542937e1422e18877e290e670cdafb950a05612baa61dd8147b88244a8770f952b989a0ade2957975448e149d6cf37c13d49489b6dd42ffd5e1dd1c6900d862e1f083026a0c753f3a4ce63433cdbb9a1d21586426cd937f0705a35ca9b3181c0df4c07d2992e21219ca97241955acf5042491a0f60a7a4eae027e12cab40d342500b5b5f1e4e4ee918dd04452dd33aae073dee062ac5e1ebc1d54557a55905af368c1afab530d5826d03576abae95c857c5ede51d56d1b6eee152a8d86e5663029377c1d88b8aed4a72b52af94c371df90cfde704260ea840b011c458a040986a854570439ab230631d54e46845e90fe79bae3c144330e2dd76e0d31ebf7583bbe70b0dfc98956dbed7e54651cfcf6091a8224c5732720ab58e405e9baf28f3c1976e61d3c59e4fffbf2fe7c99c0fcd8e3cc0f9092638e57f752a3955757f680cddd5d2be54223df76e47fb43ebb8e2e4d79a33a6a13b1ebef5f4ca7776feeb69d64c7dbade62bc18e87bff948fe1a6d52a709bf55b3fd5a6ba59d4ab3ac90eaee4bddcc104ef2889433b8beaa81e7b3d26e677b75bbae86ee0bb81d867522f45caef7d85b0a6a10e3000526778d21c386e629cd75be1f9a9cea7153edaa0152ad1b6374267943009961d40b909bc24771e7f23baf1c76a908b52066b2f5adaef510cc124fbf1fc3259dfebc039f8208cfa8106ab08e494e61d6ae3f658c1beeb55acf5336c3e9f33eb95e54623893ffc840c5b96751970b5e79bb76809c0b01fb09430f444018ceb0a0111404b6f2da37e4ccb5facd83aff91dc0f2722fa4cd6ae38ea3c7a2fd5b31e660d27ae3cbe9658223d2b884d4d3aeddeca3fde9d477cfebbb6fd990284a340c4534380e43f078ce296528a3830323c5a36654b77b984adc6149b74941852def4372f8e871835d350e0f1dedb74dad2cf919367178342de2a327cdbbe34e5f770b9b7c7707a3fcd80c4635e70d1be4a7693ba16e0b366bc21aa536fa1e7c24974b8864757182690ae5c0c39007247c8e8a09504f2f1f4fa7d37d1fa52cc2fa86f100a94fd06ef07673cc9618d636532255ebdf4a689b9b3d25dac6905defac77fe05f79b78dcf720000000000400000000000000000000000000000000000000000000000000000000000000010e4170746f734672616d65776f726b00000000000000000000000000000000000000000000000000000000000000010b4170746f735374646c696200000000000000000000000000000000000000000000000000000000000000010a4d6f76655374646c69620000000000000000000000000000000000000000000000000000000000000004114170746f73546f6b656e4f626a6563747300",
+      ).toUint8Array(),
+      [
+        new TxnBuilderTypes.Module(
+          new HexString(
+            // eslint-disable-next-line max-len
+            "a11ceb0b060000000c010016021634034aaa0104f40116058a028c03079605fb0508910b6006f10bb20210a30ea1010ac40f0c0cd00fef040dbf14060000010101020103010401050106010702080209020a000b0800020d00000310070100010211080002190600021b0600021d0600021e080007270700032c0200092d0b00042e07010000000c000100000e020100000f030100001201040000130501000014060100001507010000160301000017060800061f050a0003200c0d010801210e0e0003220f0a01080523101101080224130101080225150101080226170101080728191a000a291b1900032a1c0a00032b0a1d0108042f0120010008302122000a3123220005322501000233262700023426280002352629000336262a0002142c080002372e0101080238300801080a0b0c0b0d0b0e120f121012140b151f15241e121f1203060c05030003060c05080102060c05010b0201080301060c03060c030504060c050503010801050b020108030b020108030608060b02010807060c0105010803020b02010900050101010301060b0201090002050b02010900010b02010807010807030608060b0201090003050b020108030b02010803060c0b02010807060805030608050b020109000801050b020108030b02010803060c0608050b02010807030608050b0201090001030508080808010a02010808020608080608080206050a02010b02010900080809080608080608090c08040808080501080a010b0b01090006060c08080308080b0b01080a080801080906060c0808080808080b0b01080a08080104070608090b0b010408080808020808080801060809010804010806010805010c060b020108030b020108030801060800060c0b020108070206080403060b020108030b020108030b02010807060c0b02010807060805040608050b020109000b0201090003050b020108030b020108030b02010807060c060805030608050b0201090003166d616e616765645f66756e6769626c655f746f6b656e056572726f720e66756e6769626c655f6173736574066f626a656374066f7074696f6e167072696d6172795f66756e6769626c655f73746f7265067369676e657206737472696e670a636f6c6c656374696f6e07726f79616c747905746f6b656e144d616e6167656446756e6769626c654173736574046275726e0d46756e6769626c654173736574076465706f7369740e667265657a655f6163636f756e74064f626a656374084d657461646174610c6765745f6d657461646174610b696e69745f6d6f64756c65046d696e74087472616e7366657210756e667265657a655f6163636f756e74087769746864726177086d696e745f726566074d696e745265660c7472616e736665725f7265660b5472616e73666572526566086275726e5f726566074275726e5265660d46756e6769626c6553746f72650a616464726573735f6f660869735f6f776e6572117065726d697373696f6e5f64656e6965640e6f626a6563745f616464726573731b656e737572655f7072696d6172795f73746f72655f657869737473096275726e5f66726f6d106465706f7369745f776974685f7265660f7365745f66726f7a656e5f666c616706537472696e670475746638116372656174655f746f6b656e5f73656564156372656174655f6f626a6563745f6164647265737311616464726573735f746f5f6f626a6563740e436f6e7374727563746f7252656607526f79616c7479064f7074696f6e046e6f6e65176372656174655f66697865645f636f6c6c656374696f6e126372656174655f6e616d65645f746f6b656e2b6372656174655f7072696d6172795f73746f72655f656e61626c65645f66756e6769626c655f61737365741167656e65726174655f6d696e745f7265661167656e65726174655f6275726e5f7265661567656e65726174655f7472616e736665725f7265660f67656e65726174655f7369676e6572117472616e736665725f776974685f7265661177697468647261775f776974685f726566d6921a4cfe909980a4012c004e13e5ae6a9e535dbe177b52f24f7fc64b36cb52000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000040a02050454455354030801000000000000000a0215147465737420636f6c6c656374696f6e206e616d650a02100f7465737420746f6b656e206e616d650520d6921a4cfe909980a4012c004e13e5ae6a9e535dbe177b52f24f7fc64b36cb520a021c1b7465737420636f6c6c656374696f6e206465736372697074696f6e0a02201f687474703a2f2f6170746f736c6162732e636f6d2f636f6c6c656374696f6e0a0217167465737420746f6b656e206465736372697074696f6e0a021b1a687474703a2f2f6170746f736c6162732e636f6d2f746f6b656e0a021918746573742066756e6769626c65206173736574206e616d650a022120687474703a2f2f6170746f736c6162732e636f6d2f66617669636f6e2e69636f0a021615687474703a2f2f6170746f736c6162732e636f6d2f126170746f733a3a6d657461646174615f76318c010101000000000000000a454e4f545f4f574e4552344f6e6c792066756e6769626c65206173736574206d65746164617461206f776e65722063616e206d616b65206368616e6765732e01144d616e6167656446756e6769626c654173736574010301183078313a3a6f626a6563743a3a4f626a65637447726f7570010c6765745f6d657461646174610101000002031808041a08051c08060001040100091d11030c030b000a030c040c070a040b0711093800040c050f0701110b270e0438012b0010000c050b010b0338020c060b050b060b023803020101000100141d11030c030b000a030c040c050a040b0511093800040c050f0701110b270e0438012b0010010c070b010b0338020c060b070b060b023804020201040100161d11030c020b000a020c030c040a030b0411093800040c050f0701110b270e0338012b0010010c050b010b0238020c060b050b060838050203010000180f070211110c01070311110c0207040c000e000e010e0211121113380602040000001e3b070211110c03070311110c070a00070511110601000000000000000a033807070611111116010b000b03070711110b0738070708111111170c010e010c040a04380807091111070011113102070a1111070b111111180a0411190c060a04111a0c020a04111b0c080b04111c0c050e050b060b080b0212002d000205010401002b2211030c030b000a030c040c070a040b0711093800040c050f0701110b270e0438012b000c060b020b0338020c080a0610020b01111d0c050b0610010b080b0538040206010401002d2211030c040b000a040c050c070a050b0711093800040c050f0701110b270e0538012b0010010c090b010a0438020c060b020b0438020c080b090b060b080b033809020701040100161d11030c020b000a020c030c040a030b0411093800040c050f0701110b270e0338012b0010010c050b010b0238020c060b050b060938050208010001002f1d11030c030b000a030c040c060a040b0611093800040c050f0701110b270e0438012b0010010c070b020b0338020c050b070b050b01380a0200020001000000",
+          ).toUint8Array(),
+        ),
+      ],
+    );
+    await provider.waitForTransaction(txnHash);
+
+    // Mint 5 fungible assets to Alice
+    const payload: Gen.EntryFunctionPayload = {
+      function: `${publisher.address().hex()}::managed_fungible_token::mint`,
+      type_arguments: [],
+      arguments: [5, alice.address().hex()],
+    };
+    const rawTxn = await provider.generateTransaction(publisher.address(), payload);
+    const bcsTxn = AptosClient.generateBCSTransaction(publisher, rawTxn);
+    const transactionRes = await provider.submitSignedBCSTransaction(bcsTxn);
+    await provider.waitForTransaction(transactionRes.hash);
+
+    // Get the asset address
+    const viewPayload: Gen.ViewRequest = {
+      function: `${publisher.address().hex()}::managed_fungible_token::get_metadata`,
+      type_arguments: [],
+      arguments: [],
+    };
+    const metadata = await provider.view(viewPayload);
+    fungibleAssetMetadataAddress = (metadata as any)[0].inner;
+  }, longTestTimeout);
+
+  /**
+   * Test `transferFromPrimaryFungibleStore` and `balance` functions in FungibleAssetClient class
+   */
+  test(
+    "it trasfers amount of fungible asset and gets the correct balance",
+    async () => {
+      const fungibleAsset = new FungibleAssetClient(provider);
+      // Alice has 5 amounts of the fungible asset
+      const aliceInitialBalance = await fungibleAsset.getPrimaryBalance(alice.address(), fungibleAssetMetadataAddress);
+      expect(aliceInitialBalance).toEqual(BigInt(5));
+
+      // Alice transfers 2 amounts of the fungible asset to Bob
+      const transactionHash = await fungibleAsset.transfer(alice, fungibleAssetMetadataAddress, bob.address(), 2);
+      await provider.waitForTransaction(transactionHash);
+
+      // Alice has 3 amounts of the fungible asset
+      const aliceCurrentBalance = await fungibleAsset.getPrimaryBalance(alice.address(), fungibleAssetMetadataAddress);
+      expect(aliceCurrentBalance).toEqual(BigInt(3));
+
+      // Bob has 2 amounts of the fungible asset
+      const bobBalance = await fungibleAsset.getPrimaryBalance(bob.address(), fungibleAssetMetadataAddress);
+      expect(bobBalance).toEqual(BigInt(2));
+    },
+    longTestTimeout,
+  );
+
+  /**
+   * Test `transferFromPrimaryFungibleStore` and `checkBalance` functions in `CoinClient` class
+   */
+  test("coin client supports fungible assets operations", async () => {
+    const coinClient = new CoinClient(provider.aptosClient);
+    // Test `transferFromPrimaryFungibleStore` and `checkBalance`
+
+    // Alice transfers 2 more amount of fungible asset to Bob
+    await provider.waitForTransaction(
+      await coinClient.transfer(alice, bob, 2, {
+        coinType: fungibleAssetMetadataAddress,
+      }),
+      { checkSuccess: true },
+    );
+    // Bob balance is now 4
+    expect(
+      await coinClient.checkBalance(bob, {
+        coinType: fungibleAssetMetadataAddress,
+      }),
+    ).toEqual(BigInt(4));
+  });
+
+  test("it generates and returns a transferFromPrimaryFungibleStore raw transaction", async () => {
+    const fungibleAsset = new FungibleAssetClient(provider);
+    const rawTxn = await fungibleAsset.generateTransfer(alice, fungibleAssetMetadataAddress, bob.address(), 2);
+    expect(rawTxn instanceof RawTransaction).toBeTruthy();
+    expect(rawTxn.sender.toHexString()).toEqual(alice.address().hex());
+  });
+});
diff --git a/ecosystem/typescript/sdk/src/utils/api-endpoints.ts b/ecosystem/typescript/sdk/src/utils/api-endpoints.ts
index dcb0c1e06d618..3b317b3c98fb5 100644
--- a/ecosystem/typescript/sdk/src/utils/api-endpoints.ts
+++ b/ecosystem/typescript/sdk/src/utils/api-endpoints.ts
@@ -10,6 +10,12 @@ export const NetworkToNodeAPI: Record = {
   devnet: "https://fullnode.devnet.aptoslabs.com/v1",
 };
 
+export const NodeAPIToNetwork: Record = {
+  "https://fullnode.mainnet.aptoslabs.com/v1": "mainnet",
+  "https://fullnode.testnet.aptoslabs.com/v1": "testnet",
+  "https://fullnode.devnet.aptoslabs.com/v1": "devnet",
+};
+
 export enum Network {
   MAINNET = "mainnet",
   TESTNET = "testnet",

From d49a833426d7364f85804cc74db0b00006c70ecf Mon Sep 17 00:00:00 2001
From: "Daniel Porteous (dport)" 
Date: Wed, 7 Jun 2023 17:32:30 +0100
Subject: [PATCH 089/200] [CLI] Improve error message when compilation fails in
 aptos move publish (#8556)

---
 crates/aptos/src/move_tool/mod.rs | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/crates/aptos/src/move_tool/mod.rs b/crates/aptos/src/move_tool/mod.rs
index ca18b93ea491d..47c5349cbf8ed 100644
--- a/crates/aptos/src/move_tool/mod.rs
+++ b/crates/aptos/src/move_tool/mod.rs
@@ -662,7 +662,8 @@ impl TryInto for &PublishPackage {
                 self.move_options.named_addresses(),
                 self.move_options.bytecode_version,
             );
-        let package = BuiltPackage::build(package_path, options)?;
+        let package = BuiltPackage::build(package_path, options)
+            .map_err(|e| CliError::MoveCompilationError(format!("{:#}", e)))?;
         let compiled_units = package.extract_code();
         let metadata_serialized =
             bcs::to_bytes(&package.extract_metadata()?).expect("PackageMetadata has BCS");

From e267e3ed1f07e1f5a430256854dcff33e71c2263 Mon Sep 17 00:00:00 2001
From: Gerardo Di Giacomo <19227040+gedigi@users.noreply.github.com>
Date: Wed, 7 Jun 2023 10:45:48 -0700
Subject: [PATCH 090/200] add new fuzzer + google oss-fuzz integration files
 (#8534)

This commit introduces a new fuzzer crate that hosts fuzz tests for aptos-core.

The first version of the fuzzer includes these fuzz tests:
- Move Bytecode Verifier CodeUnit and Mixed modules
- Move execute entry function
- Move MoveValue decorate/undecorate
- Move MoveValue deserialize
- Move Value deserialize
- Signed Transaction deserialize
---
 Cargo.lock                                    | 40 ++++++--
 Cargo.toml                                    |  3 +
 testsuite/fuzzer/Cargo.toml                   |  7 ++
 testsuite/fuzzer/fuzz/.gitignore              |  4 +
 testsuite/fuzzer/fuzz/Cargo.lock              | 62 ++++++++++++
 testsuite/fuzzer/fuzz/Cargo.toml              | 64 +++++++++++++
 .../move/bytecode_verifier_code_unit.rs       | 82 ++++++++++++++++
 .../move/bytecode_verifier_mixed.rs           | 96 +++++++++++++++++++
 .../move/execute_entry_function.rs            | 54 +++++++++++
 .../fuzz_targets/move/move_value_decorate.rs  | 35 +++++++
 .../move/move_value_deserialize.rs            | 22 +++++
 .../fuzzer/fuzz/fuzz_targets/move/utils.rs    | 23 +++++
 .../fuzz_targets/move/value_deserialize.rs    | 23 +++++
 .../signed_transaction_deserialize.rs         | 16 ++++
 testsuite/fuzzer/google-oss-fuzz/Dockerfile   |  5 +
 testsuite/fuzzer/google-oss-fuzz/build.sh     | 11 +++
 testsuite/fuzzer/google-oss-fuzz/project.yaml | 12 +++
 testsuite/fuzzer/src/main.rs                  |  5 +
 testsuite/fuzzer/test-fuzzers.sh              | 15 +++
 .../move/move-core/types/src/identifier.rs    |  2 +-
 .../move-core/types/src/language_storage.rs   |  2 +
 third_party/move/move-core/types/src/value.rs |  5 +
 22 files changed, 578 insertions(+), 10 deletions(-)
 create mode 100644 testsuite/fuzzer/Cargo.toml
 create mode 100644 testsuite/fuzzer/fuzz/.gitignore
 create mode 100644 testsuite/fuzzer/fuzz/Cargo.lock
 create mode 100644 testsuite/fuzzer/fuzz/Cargo.toml
 create mode 100644 testsuite/fuzzer/fuzz/fuzz_targets/move/bytecode_verifier_code_unit.rs
 create mode 100644 testsuite/fuzzer/fuzz/fuzz_targets/move/bytecode_verifier_mixed.rs
 create mode 100644 testsuite/fuzzer/fuzz/fuzz_targets/move/execute_entry_function.rs
 create mode 100644 testsuite/fuzzer/fuzz/fuzz_targets/move/move_value_decorate.rs
 create mode 100644 testsuite/fuzzer/fuzz/fuzz_targets/move/move_value_deserialize.rs
 create mode 100644 testsuite/fuzzer/fuzz/fuzz_targets/move/utils.rs
 create mode 100644 testsuite/fuzzer/fuzz/fuzz_targets/move/value_deserialize.rs
 create mode 100644 testsuite/fuzzer/fuzz/fuzz_targets/signed_transaction_deserialize.rs
 create mode 100644 testsuite/fuzzer/google-oss-fuzz/Dockerfile
 create mode 100644 testsuite/fuzzer/google-oss-fuzz/build.sh
 create mode 100644 testsuite/fuzzer/google-oss-fuzz/project.yaml
 create mode 100644 testsuite/fuzzer/src/main.rs
 create mode 100755 testsuite/fuzzer/test-fuzzers.sh

diff --git a/Cargo.lock b/Cargo.lock
index d3f77026e59b0..b74549bcecbee 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3545,9 +3545,9 @@ checksum = "db55d72333851e17d572bec876e390cd3b11eb1ef53ae821dd9f3b653d2b4569"
 
 [[package]]
 name = "arbitrary"
-version = "1.1.7"
+version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d86fd10d912cab78764cc44307d9cd5f164e09abbeb87fb19fb6d95937e8da5f"
+checksum = "e2d098ff73c1ca148721f37baad5ea6a465a13f9573aba8641fbbbae8164a54e"
 dependencies = [
  "derive_arbitrary",
 ]
@@ -4393,7 +4393,7 @@ checksum = "e3b5ca7a04898ad4bcd41c90c5285445ff5b791899bb1b0abdd2a2aa791211d7"
 name = "bytecode-verifier-libfuzzer"
 version = "0.0.0"
 dependencies = [
- "arbitrary 1.1.7",
+ "arbitrary 1.3.0",
  "libfuzzer-sys 0.4.6",
  "move-binary-format",
  "move-bytecode-verifier",
@@ -5356,13 +5356,13 @@ dependencies = [
 
 [[package]]
 name = "derive_arbitrary"
-version = "1.1.6"
+version = "1.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "226ad66541d865d7a7173ad6a9e691c33fdb910ac723f4bc734b3e5294a1f931"
+checksum = "53e0efad4403bfc52dc201159c4b842a246a14b98c64b55dfd0f2d89729dfeb8"
 dependencies = [
  "proc-macro2 1.0.59",
  "quote 1.0.28",
- "syn 1.0.105",
+ "syn 2.0.18",
 ]
 
 [[package]]
@@ -6188,6 +6188,28 @@ dependencies = [
  "slab",
 ]
 
+[[package]]
+name = "fuzzer"
+version = "0.1.0"
+
+[[package]]
+name = "fuzzer-fuzz"
+version = "0.0.0"
+dependencies = [
+ "aptos-consensus",
+ "aptos-consensus-types",
+ "aptos-types",
+ "arbitrary 1.3.0",
+ "bcs 0.1.4",
+ "libfuzzer-sys 0.4.6",
+ "move-binary-format",
+ "move-bytecode-verifier",
+ "move-core-types",
+ "move-vm-runtime",
+ "move-vm-test-utils",
+ "move-vm-types",
+]
+
 [[package]]
 name = "gcc"
 version = "0.3.55"
@@ -7472,7 +7494,7 @@ version = "0.4.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "beb09950ae85a0a94b27676cccf37da5ff13f27076aa1adbc6545dd0d0e1bd4e"
 dependencies = [
- "arbitrary 1.1.7",
+ "arbitrary 1.3.0",
  "cc",
  "once_cell",
 ]
@@ -8040,7 +8062,7 @@ name = "move-binary-format"
 version = "0.0.3"
 dependencies = [
  "anyhow",
- "arbitrary 1.1.7",
+ "arbitrary 1.3.0",
  "indexmap",
  "move-core-types",
  "once_cell",
@@ -8217,7 +8239,7 @@ name = "move-core-types"
 version = "0.0.4"
 dependencies = [
  "anyhow",
- "arbitrary 1.1.7",
+ "arbitrary 1.3.0",
  "bcs 0.1.4",
  "ethnum",
  "hex",
diff --git a/Cargo.toml b/Cargo.toml
index d603a65c4a5cb..1b74aedbf767c 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -148,6 +148,8 @@ members = [
     "testsuite/dos/sender",
     "testsuite/forge",
     "testsuite/forge-cli",
+    "testsuite/fuzzer",
+    "testsuite/fuzzer/fuzz",
     "testsuite/generate-format",
     "testsuite/module-publish",
     "testsuite/smoke-test",
@@ -284,6 +286,7 @@ aptos-fallible = { path = "crates/fallible" }
 aptos-forge = { path = "testsuite/forge" }
 aptos-framework = { path = "aptos-move/framework" }
 aptos-fuzzer = { path = "testsuite/aptos-fuzzer" }
+fuzzer = { path = "testsuite/fuzzer" }
 aptos-gas = { path = "aptos-move/aptos-gas" }
 aptos-gas-algebra-ext = { path = "aptos-move/gas-algebra-ext" }
 aptos-gas-profiling = { path = "aptos-move/aptos-gas-profiling" }
diff --git a/testsuite/fuzzer/Cargo.toml b/testsuite/fuzzer/Cargo.toml
new file mode 100644
index 0000000000000..5f07a38412d24
--- /dev/null
+++ b/testsuite/fuzzer/Cargo.toml
@@ -0,0 +1,7 @@
+[package]
+name = "fuzzer"
+version = "0.1.0"
+edition = "2021"
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
diff --git a/testsuite/fuzzer/fuzz/.gitignore b/testsuite/fuzzer/fuzz/.gitignore
new file mode 100644
index 0000000000000..1a45eee7760d2
--- /dev/null
+++ b/testsuite/fuzzer/fuzz/.gitignore
@@ -0,0 +1,4 @@
+target
+corpus
+artifacts
+coverage
diff --git a/testsuite/fuzzer/fuzz/Cargo.lock b/testsuite/fuzzer/fuzz/Cargo.lock
new file mode 100644
index 0000000000000..ee1a7d22086d4
--- /dev/null
+++ b/testsuite/fuzzer/fuzz/Cargo.lock
@@ -0,0 +1,62 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 3
+
+[[package]]
+name = "arbitrary"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e2d098ff73c1ca148721f37baad5ea6a465a13f9573aba8641fbbbae8164a54e"
+
+[[package]]
+name = "cc"
+version = "1.0.79"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "50d30906286121d95be3d479533b458f87493b30a4b5f79a607db8f5d11aa91f"
+dependencies = [
+ "jobserver",
+]
+
+[[package]]
+name = "fuzzer"
+version = "0.1.0"
+
+[[package]]
+name = "fuzzer-fuzz"
+version = "0.0.0"
+dependencies = [
+ "fuzzer",
+ "libfuzzer-sys",
+]
+
+[[package]]
+name = "jobserver"
+version = "0.1.26"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "936cfd212a0155903bcbc060e316fb6cc7cbf2e1907329391ebadc1fe0ce77c2"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.144"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b00cc1c228a6782d0f076e7b232802e0c5689d41bb5df366f2a6b6621cfdfe1"
+
+[[package]]
+name = "libfuzzer-sys"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "beb09950ae85a0a94b27676cccf37da5ff13f27076aa1adbc6545dd0d0e1bd4e"
+dependencies = [
+ "arbitrary",
+ "cc",
+ "once_cell",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7e5500299e16ebb147ae15a00a942af264cf3688f47923b8fc2cd5858f23ad3"
diff --git a/testsuite/fuzzer/fuzz/Cargo.toml b/testsuite/fuzzer/fuzz/Cargo.toml
new file mode 100644
index 0000000000000..9c0da7a38815b
--- /dev/null
+++ b/testsuite/fuzzer/fuzz/Cargo.toml
@@ -0,0 +1,64 @@
+[package]
+name = "fuzzer-fuzz"
+version = "0.0.0"
+publish = false
+edition = "2021"
+
+[package.metadata]
+cargo-fuzz = true
+
+[dependencies]
+aptos-consensus = { workspace = true, features = ["fuzzing"] }
+aptos-consensus-types = { workspace = true, features = ["fuzzing"] }
+aptos-types = { workspace = true }
+arbitrary = "1.3.0"
+bcs = { workspace = true }
+libfuzzer-sys = "0.4"
+move-binary-format = { workspace = true, features = ["fuzzing"] }
+move-bytecode-verifier = { workspace = true }
+move-core-types = { workspace = true, features = ["fuzzing"] }
+move-vm-runtime = { workspace = true }
+move-vm-test-utils = { workspace = true }
+move-vm-types = { workspace = true, features = ["fuzzing"] }
+
+[[bin]]
+name = "move_bytecode_verifier_code_unit"
+path = "fuzz_targets/move/bytecode_verifier_code_unit.rs"
+test = false
+doc = false
+
+[[bin]]
+name = "move_bytecode_verifier_mixed"
+path = "fuzz_targets/move/bytecode_verifier_mixed.rs"
+test = false
+doc = false
+
+[[bin]]
+name = "move_value_deserialize"
+path = "fuzz_targets/move/value_deserialize.rs"
+test = false
+doc = false
+
+[[bin]]
+name = "move_move_value_deserialize"
+path = "fuzz_targets/move/move_value_deserialize.rs"
+test = false
+doc = false
+
+[[bin]]
+name = "move_move_value_decorate"
+path = "fuzz_targets/move/move_value_decorate.rs"
+test = false
+doc = false
+
+[[bin]]
+name = "move_execute_entry_function"
+path = "fuzz_targets/move/execute_entry_function.rs"
+test = false
+doc = false
+
+[[bin]]
+name = "signed_transaction_deserialize"
+path = "fuzz_targets/signed_transaction_deserialize.rs"
+test = false
+doc = false
diff --git a/testsuite/fuzzer/fuzz/fuzz_targets/move/bytecode_verifier_code_unit.rs b/testsuite/fuzzer/fuzz/fuzz_targets/move/bytecode_verifier_code_unit.rs
new file mode 100644
index 0000000000000..50bdd44440963
--- /dev/null
+++ b/testsuite/fuzzer/fuzz/fuzz_targets/move/bytecode_verifier_code_unit.rs
@@ -0,0 +1,82 @@
+// Copyright (c) The Move Contributors
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+#![no_main]
+use libfuzzer_sys::fuzz_target;
+use move_binary_format::file_format::{
+    empty_module, AbilitySet, CodeUnit, Constant, FieldDefinition, FunctionDefinition,
+    FunctionHandle, FunctionHandleIndex, IdentifierIndex, ModuleHandleIndex, Signature,
+    SignatureIndex,
+    SignatureToken::{Address, Bool, U128, U64},
+    StructDefinition, StructFieldInformation, StructHandle, StructHandleIndex, TypeSignature,
+    Visibility,
+};
+use move_core_types::{account_address::AccountAddress, ident_str};
+
+fuzz_target!(|code_unit: CodeUnit| {
+    let mut module = empty_module();
+    module.version = 5;
+
+    module.struct_handles.push(StructHandle {
+        module: ModuleHandleIndex(0),
+        name: IdentifierIndex(1),
+        abilities: AbilitySet::ALL,
+        type_parameters: vec![],
+    });
+
+    let fun_handle = FunctionHandle {
+        module: ModuleHandleIndex(0),
+        name: IdentifierIndex(2),
+        parameters: SignatureIndex(0),
+        return_: SignatureIndex(1),
+        type_parameters: vec![],
+    };
+
+    module.function_handles.push(fun_handle);
+
+    module.signatures.pop();
+    module.signatures.push(Signature(vec![
+        Address, U64, Address, Address, U128, Address, U64, U64, U64,
+    ]));
+    module.signatures.push(Signature(vec![]));
+    module
+        .signatures
+        .push(Signature(vec![Address, Bool, Address]));
+
+    module.identifiers.extend(
+        vec![
+            ident_str!("zf_hello_world").into(),
+            ident_str!("awldFnU18mlDKQfh6qNfBGx8X").into(),
+            ident_str!("aQPwJNHyAHpvJ").into(),
+            ident_str!("aT7ZphKTrKcYCwCebJySrmrKlckmnL5").into(),
+            ident_str!("arYpsFa2fvrpPJ").into(),
+        ]
+        .into_iter(),
+    );
+    module.address_identifiers.push(AccountAddress::random());
+
+    module.constant_pool.push(Constant {
+        type_: Address,
+        data: AccountAddress::ZERO.into_bytes().to_vec(),
+    });
+
+    module.struct_defs.push(StructDefinition {
+        struct_handle: StructHandleIndex(0),
+        field_information: StructFieldInformation::Declared(vec![FieldDefinition {
+            name: IdentifierIndex::new(3),
+            signature: TypeSignature(Address),
+        }]),
+    });
+
+    let fun_def = FunctionDefinition {
+        code: Some(code_unit),
+        function: FunctionHandleIndex(0),
+        visibility: Visibility::Public,
+        is_entry: false,
+        acquires_global_resources: vec![],
+    };
+
+    module.function_defs.push(fun_def);
+    let _ = move_bytecode_verifier::verify_module(&module);
+});
diff --git a/testsuite/fuzzer/fuzz/fuzz_targets/move/bytecode_verifier_mixed.rs b/testsuite/fuzzer/fuzz/fuzz_targets/move/bytecode_verifier_mixed.rs
new file mode 100644
index 0000000000000..cacd65bfedefa
--- /dev/null
+++ b/testsuite/fuzzer/fuzz/fuzz_targets/move/bytecode_verifier_mixed.rs
@@ -0,0 +1,96 @@
+// Copyright (c) The Move Contributors
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+#![no_main]
+use arbitrary::Arbitrary;
+use libfuzzer_sys::fuzz_target;
+use move_binary_format::file_format::{
+    empty_module, AbilitySet, Bytecode, CodeUnit, Constant, FieldDefinition, FunctionDefinition,
+    FunctionHandle, FunctionHandleIndex, IdentifierIndex, ModuleHandleIndex, Signature,
+    SignatureIndex, SignatureToken,
+    SignatureToken::{Address, Bool},
+    StructDefinition, StructFieldInformation, StructHandle, StructHandleIndex, TypeSignature,
+    Visibility,
+};
+use move_core_types::{account_address::AccountAddress, ident_str};
+
+#[derive(Arbitrary, Debug)]
+struct Mixed {
+    code: Vec,
+    abilities: AbilitySet,
+    param_types: Vec,
+    return_type: Option,
+}
+
+fuzz_target!(|mix: Mixed| {
+    let mut module = empty_module();
+    module.version = 5;
+
+    module.struct_handles.push(StructHandle {
+        module: ModuleHandleIndex(0),
+        name: IdentifierIndex(1),
+        abilities: mix.abilities,
+        type_parameters: vec![],
+    });
+
+    let fun_handle = FunctionHandle {
+        module: ModuleHandleIndex(0),
+        name: IdentifierIndex(2),
+        parameters: SignatureIndex(0),
+        return_: SignatureIndex(1),
+        type_parameters: vec![],
+    };
+
+    module.function_handles.push(fun_handle);
+
+    module.signatures.pop();
+    module.signatures.push(Signature(mix.param_types));
+    module.signatures.push(Signature(
+        mix.return_type.map(|s| vec![s]).unwrap_or_default(),
+    ));
+    module
+        .signatures
+        .push(Signature(vec![Address, Bool, Address]));
+
+    module.identifiers.extend(
+        vec![
+            ident_str!("zf_hello_world").into(),
+            ident_str!("awldFnU18mlDKQfh6qNfBGx8X").into(),
+            ident_str!("aQPwJNHyAHpvJ").into(),
+            ident_str!("aT7ZphKTrKcYCwCebJySrmrKlckmnL5").into(),
+            ident_str!("arYpsFa2fvrpPJ").into(),
+        ]
+        .into_iter(),
+    );
+    module.address_identifiers.push(AccountAddress::random());
+
+    module.constant_pool.push(Constant {
+        type_: Address,
+        data: AccountAddress::ZERO.into_bytes().to_vec(),
+    });
+
+    module.struct_defs.push(StructDefinition {
+        struct_handle: StructHandleIndex(0),
+        field_information: StructFieldInformation::Declared(vec![FieldDefinition {
+            name: IdentifierIndex::new(3),
+            signature: TypeSignature(Address),
+        }]),
+    });
+
+    let code_unit = CodeUnit {
+        code: mix.code,
+        locals: SignatureIndex(0),
+    };
+
+    let fun_def = FunctionDefinition {
+        code: Some(code_unit),
+        function: FunctionHandleIndex(0),
+        visibility: Visibility::Public,
+        is_entry: false,
+        acquires_global_resources: vec![],
+    };
+
+    module.function_defs.push(fun_def);
+    let _ = move_bytecode_verifier::verify_module(&module);
+});
diff --git a/testsuite/fuzzer/fuzz/fuzz_targets/move/execute_entry_function.rs b/testsuite/fuzzer/fuzz/fuzz_targets/move/execute_entry_function.rs
new file mode 100644
index 0000000000000..ab979771750c6
--- /dev/null
+++ b/testsuite/fuzzer/fuzz/fuzz_targets/move/execute_entry_function.rs
@@ -0,0 +1,54 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+#![no_main]
+use arbitrary::Arbitrary;
+use libfuzzer_sys::fuzz_target;
+use move_binary_format::file_format::CompiledModule;
+use move_core_types::{
+    account_address::AccountAddress, identifier::IdentStr, language_storage::TypeTag,
+};
+use move_vm_runtime::move_vm::MoveVM;
+use move_vm_test_utils::{gas_schedule::GasStatus, InMemoryStorage};
+
+#[derive(Arbitrary, Debug)]
+struct FuzzData {
+    cm: CompiledModule,
+    ident: String,
+    ty_arg: Vec,
+    args: Vec>,
+    account_address: AccountAddress,
+}
+
+fuzz_target!(|fuzz_data: FuzzData| {
+    let mut cm_serialized = Vec::with_capacity(65536);
+    if fuzz_data.cm.serialize(&mut cm_serialized).is_err() {
+        return;
+    }
+
+    if move_bytecode_verifier::verify_module(&fuzz_data.cm).is_err() {
+        return;
+    }
+
+    let vm = MoveVM::new(vec![]).unwrap();
+    let storage = InMemoryStorage::new();
+    let mut session = vm.new_session(&storage);
+    let mut gas = GasStatus::new_unmetered();
+
+    if session
+        .publish_module(cm_serialized, fuzz_data.account_address, &mut gas)
+        .is_err()
+    {
+        return;
+    }
+
+    let ident =
+        IdentStr::new(fuzz_data.ident.as_str()).unwrap_or_else(|_| IdentStr::new("f").unwrap());
+    let _ = session.execute_entry_function(
+        &fuzz_data.cm.self_id(),
+        ident,
+        fuzz_data.ty_arg,
+        fuzz_data.args,
+        &mut gas,
+    );
+});
diff --git a/testsuite/fuzzer/fuzz/fuzz_targets/move/move_value_decorate.rs b/testsuite/fuzzer/fuzz/fuzz_targets/move/move_value_decorate.rs
new file mode 100644
index 0000000000000..b91192b28cf3d
--- /dev/null
+++ b/testsuite/fuzzer/fuzz/fuzz_targets/move/move_value_decorate.rs
@@ -0,0 +1,35 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+#![no_main]
+use arbitrary::Arbitrary;
+use libfuzzer_sys::fuzz_target;
+use move_core_types::value::{MoveTypeLayout, MoveValue};
+
+mod utils;
+
+#[derive(Arbitrary, Debug)]
+struct FuzzData {
+    move_value: MoveValue,
+    layout: MoveTypeLayout,
+}
+
+fuzz_target!(|fuzz_data: FuzzData| {
+    if !utils::is_valid_layout(&fuzz_data.layout) {
+        return;
+    }
+
+    // Undecorate value
+    let move_value = fuzz_data.move_value.clone();
+    let undecorated_move_value = move_value.undecorate();
+
+    // Decorate value
+    let move_value = fuzz_data.move_value.clone();
+    let decorated_move_value = move_value.decorate(&fuzz_data.layout);
+
+    // Undecorate decorated value
+    decorated_move_value.undecorate();
+
+    // Decorate undecorated value
+    undecorated_move_value.decorate(&fuzz_data.layout);
+});
diff --git a/testsuite/fuzzer/fuzz/fuzz_targets/move/move_value_deserialize.rs b/testsuite/fuzzer/fuzz/fuzz_targets/move/move_value_deserialize.rs
new file mode 100644
index 0000000000000..3c130d708e3bd
--- /dev/null
+++ b/testsuite/fuzzer/fuzz/fuzz_targets/move/move_value_deserialize.rs
@@ -0,0 +1,22 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+#![no_main]
+use arbitrary::Arbitrary;
+use libfuzzer_sys::fuzz_target;
+use move_core_types::value::{MoveTypeLayout, MoveValue};
+
+mod utils;
+
+#[derive(Arbitrary, Debug)]
+struct FuzzData {
+    data: Vec,
+    layout: MoveTypeLayout,
+}
+
+fuzz_target!(|fuzz_data: FuzzData| {
+    if fuzz_data.data.is_empty() || !utils::is_valid_layout(&fuzz_data.layout) {
+        return;
+    }
+    let _ = MoveValue::simple_deserialize(&fuzz_data.data, &fuzz_data.layout);
+});
diff --git a/testsuite/fuzzer/fuzz/fuzz_targets/move/utils.rs b/testsuite/fuzzer/fuzz/fuzz_targets/move/utils.rs
new file mode 100644
index 0000000000000..370261b0da715
--- /dev/null
+++ b/testsuite/fuzzer/fuzz/fuzz_targets/move/utils.rs
@@ -0,0 +1,23 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use move_core_types::value::{MoveStructLayout, MoveTypeLayout};
+
+pub(crate) fn is_valid_layout(layout: &MoveTypeLayout) -> bool {
+    use MoveTypeLayout as L;
+
+    match layout {
+        L::Bool | L::U8 | L::U16 | L::U32 | L::U64 | L::U128 | L::U256 | L::Address | L::Signer => {
+            true
+        },
+        L::Vector(layout) => is_valid_layout(layout),
+        L::Struct(struct_layout) => {
+            if !matches!(struct_layout, MoveStructLayout::Runtime(_))
+                || struct_layout.fields().is_empty()
+            {
+                return false;
+            }
+            struct_layout.fields().iter().all(is_valid_layout)
+        },
+    }
+}
diff --git a/testsuite/fuzzer/fuzz/fuzz_targets/move/value_deserialize.rs b/testsuite/fuzzer/fuzz/fuzz_targets/move/value_deserialize.rs
new file mode 100644
index 0000000000000..adf71d8435fe3
--- /dev/null
+++ b/testsuite/fuzzer/fuzz/fuzz_targets/move/value_deserialize.rs
@@ -0,0 +1,23 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+#![no_main]
+use arbitrary::Arbitrary;
+use libfuzzer_sys::fuzz_target;
+use move_core_types::value::MoveTypeLayout;
+use move_vm_types::values::Value;
+
+mod utils;
+
+#[derive(Arbitrary, Debug)]
+struct FuzzData {
+    data: Vec,
+    layout: MoveTypeLayout,
+}
+
+fuzz_target!(|fuzz_data: FuzzData| {
+    if fuzz_data.data.is_empty() || !utils::is_valid_layout(&fuzz_data.layout) {
+        return;
+    }
+    let _ = Value::simple_deserialize(&fuzz_data.data, &fuzz_data.layout);
+});
diff --git a/testsuite/fuzzer/fuzz/fuzz_targets/signed_transaction_deserialize.rs b/testsuite/fuzzer/fuzz/fuzz_targets/signed_transaction_deserialize.rs
new file mode 100644
index 0000000000000..fd2cfc34edbf6
--- /dev/null
+++ b/testsuite/fuzzer/fuzz/fuzz_targets/signed_transaction_deserialize.rs
@@ -0,0 +1,16 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+#![no_main]
+use aptos_types::transaction::SignedTransaction;
+use arbitrary::Arbitrary;
+use libfuzzer_sys::fuzz_target;
+
+#[derive(Arbitrary, Debug)]
+struct FuzzData {
+    data: Vec,
+}
+
+fuzz_target!(|fuzz_data: FuzzData| {
+    let _ = bcs::from_bytes::(&fuzz_data.data);
+});
diff --git a/testsuite/fuzzer/google-oss-fuzz/Dockerfile b/testsuite/fuzzer/google-oss-fuzz/Dockerfile
new file mode 100644
index 0000000000000..8d49e8a2663a7
--- /dev/null
+++ b/testsuite/fuzzer/google-oss-fuzz/Dockerfile
@@ -0,0 +1,5 @@
+FROM gcr.io/oss-fuzz-base/base-builder-rust
+RUN apt-get update && apt-get install -y make autoconf automake libclang-dev libtool pkg-config
+RUN git clone --depth=1 https://github.com/aptos-labs/aptos-core.git
+WORKDIR aptos-core
+COPY build.sh $SRC
diff --git a/testsuite/fuzzer/google-oss-fuzz/build.sh b/testsuite/fuzzer/google-oss-fuzz/build.sh
new file mode 100644
index 0000000000000..eb6962ffae4e0
--- /dev/null
+++ b/testsuite/fuzzer/google-oss-fuzz/build.sh
@@ -0,0 +1,11 @@
+#!/bin/bash -eu
+
+NIGHTLY_VERSION="nightly-2023-01-01"  # bitvec does not compile with latest nightly
+
+rustup install $NIGHTLY_VERSION
+cd testsuite/fuzzer
+
+RUSTFLAGS="$RUSTFLAGS --cfg tokio_unstable" cargo +$NIGHTLY_VERSION fuzz build -O -a
+for fuzzer in $(cat fuzz/Cargo.toml | grep "name = " | grep -v "fuzzer-fuzz" | cut -d'"' -f2); do
+  cp ../../target/x86_64-unknown-linux-gnu/release/$fuzzer $OUT/
+done
\ No newline at end of file
diff --git a/testsuite/fuzzer/google-oss-fuzz/project.yaml b/testsuite/fuzzer/google-oss-fuzz/project.yaml
new file mode 100644
index 0000000000000..660410573bbcf
--- /dev/null
+++ b/testsuite/fuzzer/google-oss-fuzz/project.yaml
@@ -0,0 +1,12 @@
+homepage: "https://aptos.dev"
+language: rust
+primary_contact: "gerardo@aptoslabs.com"
+main_repo: "https://github.com/aptos-labs/aptos-core"
+auto_ccs:
+  - "davidiw@aptoslabs.com"
+  - "security@aptoslabs.com"
+  - "wg@aptoslabs.com"
+sanitizers:
+  - address
+fuzzing_engines:
+  - libfuzzer
\ No newline at end of file
diff --git a/testsuite/fuzzer/src/main.rs b/testsuite/fuzzer/src/main.rs
new file mode 100644
index 0000000000000..8b4b7415a1a1b
--- /dev/null
+++ b/testsuite/fuzzer/src/main.rs
@@ -0,0 +1,5 @@
+// Copyright © Aptos Foundation
+
+fn main() {
+    println!("Hello, world!");
+}
diff --git a/testsuite/fuzzer/test-fuzzers.sh b/testsuite/fuzzer/test-fuzzers.sh
new file mode 100755
index 0000000000000..b586988fccb75
--- /dev/null
+++ b/testsuite/fuzzer/test-fuzzers.sh
@@ -0,0 +1,15 @@
+#!/bin/bash
+
+export RUSTFLAGS="${RUSTFLAGS} --cfg tokio_unstable"
+export RUNS="1000"
+
+for fuzzer in $(cargo +nightly fuzz list); do
+    echo "[info] compiling and running ${fuzzer} ${RUNS} times"
+    cargo +nightly fuzz run -O -a $fuzzer -- -runs=$RUNS
+    if [ "$?" -ne "0" ]; then
+        echo "[error] failed to run ${fuzzer}"
+        return -1
+    else
+        echo "[ok] ${fuzzer}"
+    fi
+done
\ No newline at end of file
diff --git a/third_party/move/move-core/types/src/identifier.rs b/third_party/move/move-core/types/src/identifier.rs
index 0aed508c74865..d4cef553a26c2 100644
--- a/third_party/move/move-core/types/src/identifier.rs
+++ b/third_party/move/move-core/types/src/identifier.rs
@@ -89,7 +89,7 @@ pub(crate) static ALLOWED_NO_SELF_IDENTIFIERS: &str =
 ///
 /// For more details, see the module level documentation.
 #[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(any(test, feature = "fuzzing"), derive(arbitrary::Arbitrary))]
 pub struct Identifier(Box);
 // An identifier cannot be mutated so use Box instead of String -- it is 1 word smaller.
 
diff --git a/third_party/move/move-core/types/src/language_storage.rs b/third_party/move/move-core/types/src/language_storage.rs
index ee9a88b9c76aa..000e9c9160013 100644
--- a/third_party/move/move-core/types/src/language_storage.rs
+++ b/third_party/move/move-core/types/src/language_storage.rs
@@ -23,6 +23,7 @@ pub const RESOURCE_TAG: u8 = 1;
 pub const CORE_CODE_ADDRESS: AccountAddress = AccountAddress::ONE;
 
 #[derive(Serialize, Deserialize, Debug, PartialEq, Hash, Eq, Clone, PartialOrd, Ord)]
+#[cfg_attr(any(test, feature = "fuzzing"), derive(arbitrary::Arbitrary))]
 pub enum TypeTag {
     // alias for compatibility with old json serialized data.
     #[serde(rename = "bool", alias = "Bool")]
@@ -101,6 +102,7 @@ impl FromStr for TypeTag {
 }
 
 #[derive(Serialize, Deserialize, Debug, PartialEq, Hash, Eq, Clone, PartialOrd, Ord)]
+#[cfg_attr(any(test, feature = "fuzzing"), derive(arbitrary::Arbitrary))]
 pub struct StructTag {
     pub address: AccountAddress,
     pub module: Identifier,
diff --git a/third_party/move/move-core/types/src/value.rs b/third_party/move/move-core/types/src/value.rs
index b0caed49d94bd..4820c2cd6213f 100644
--- a/third_party/move/move-core/types/src/value.rs
+++ b/third_party/move/move-core/types/src/value.rs
@@ -29,6 +29,7 @@ pub const MOVE_STRUCT_TYPE: &str = "type";
 pub const MOVE_STRUCT_FIELDS: &str = "fields";
 
 #[derive(Debug, PartialEq, Eq, Clone)]
+#[cfg_attr(any(test, feature = "fuzzing"), derive(arbitrary::Arbitrary))]
 pub enum MoveStruct {
     /// The representation used by the MoveVM
     Runtime(Vec),
@@ -42,6 +43,7 @@ pub enum MoveStruct {
 }
 
 #[derive(Debug, PartialEq, Eq, Clone)]
+#[cfg_attr(any(test, feature = "fuzzing"), derive(arbitrary::Arbitrary))]
 pub enum MoveValue {
     U8(u8),
     U64(u64),
@@ -59,6 +61,7 @@ pub enum MoveValue {
 
 /// A layout associated with a named field
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(any(test, feature = "fuzzing"), derive(arbitrary::Arbitrary))]
 pub struct MoveFieldLayout {
     pub name: Identifier,
     pub layout: MoveTypeLayout,
@@ -71,6 +74,7 @@ impl MoveFieldLayout {
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(any(test, feature = "fuzzing"), derive(arbitrary::Arbitrary))]
 pub enum MoveStructLayout {
     /// The representation used by the MoveVM
     Runtime(Vec),
@@ -84,6 +88,7 @@ pub enum MoveStructLayout {
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(any(test, feature = "fuzzing"), derive(arbitrary::Arbitrary))]
 pub enum MoveTypeLayout {
     #[serde(rename(serialize = "bool", deserialize = "bool"))]
     Bool,

From faff4ee44632e772ff6881d12eb5d2eabdf69566 Mon Sep 17 00:00:00 2001
From: Victor Gao <10379359+vgao1996@users.noreply.github.com>
Date: Wed, 7 Jun 2023 10:46:16 -0700
Subject: [PATCH 091/200] [gas] fix gas metering for resource groups (#8549)

---
 .../aptos-gas-profiling/src/profiler.rs       |  6 +++--
 aptos-move/aptos-gas/src/gas_meter.rs         | 10 ++++---
 .../aptos-gas/src/transaction/storage.rs      | 20 +++++++-------
 aptos-move/aptos-vm/src/data_cache.rs         | 19 ++++++++------
 aptos-move/framework/src/natives/object.rs    | 10 +------
 .../async/move-async-vm/tests/testsuite.rs    |  7 ++---
 .../move/move-core/types/src/resolver.rs      | 17 +++++-------
 .../src/tests/bad_storage_tests.rs            |  2 +-
 .../move/move-vm/runtime/src/data_cache.rs    | 26 +++++++++----------
 .../move/move-vm/runtime/src/interpreter.rs   | 22 +++++-----------
 .../move-vm/runtime/src/native_functions.rs   |  2 +-
 .../move/move-vm/runtime/src/session.rs       |  2 +-
 .../src/unit_tests/vm_arguments_tests.rs      |  4 +--
 .../move-vm/test-utils/src/gas_schedule.rs    |  3 ++-
 .../move/move-vm/test-utils/src/storage.rs    | 18 +++++++------
 third_party/move/move-vm/types/src/gas.rs     |  8 +++---
 .../src/sandbox/utils/on_disk_state_view.rs   |  7 ++---
 17 files changed, 89 insertions(+), 94 deletions(-)

diff --git a/aptos-move/aptos-gas-profiling/src/profiler.rs b/aptos-move/aptos-gas-profiling/src/profiler.rs
index c682cd882ddb6..e96a9819d4b31 100644
--- a/aptos-move/aptos-gas-profiling/src/profiler.rs
+++ b/aptos-move/aptos-gas-profiling/src/profiler.rs
@@ -428,11 +428,13 @@ where
         &mut self,
         addr: AccountAddress,
         ty: impl TypeView,
-        loaded: Option<(NumBytes, impl ValueView)>,
+        val: Option,
+        bytes_loaded: NumBytes,
     ) -> PartialVMResult<()> {
         let ty_tag = ty.to_type_tag();
 
-        let (cost, res) = self.delegate_charge(|base| base.charge_load_resource(addr, ty, loaded));
+        let (cost, res) =
+            self.delegate_charge(|base| base.charge_load_resource(addr, ty, val, bytes_loaded));
 
         self.active_event_stream()
             .push(ExecutionGasEvent::LoadResource {
diff --git a/aptos-move/aptos-gas/src/gas_meter.rs b/aptos-move/aptos-gas/src/gas_meter.rs
index 30a1bcc676c83..f27088a44907a 100644
--- a/aptos-move/aptos-gas/src/gas_meter.rs
+++ b/aptos-move/aptos-gas/src/gas_meter.rs
@@ -491,11 +491,12 @@ impl MoveGasMeter for StandardGasMeter {
         &mut self,
         _addr: AccountAddress,
         _ty: impl TypeView,
-        loaded: Option<(NumBytes, impl ValueView)>,
+        val: Option,
+        bytes_loaded: NumBytes,
     ) -> PartialVMResult<()> {
         if self.feature_version != 0 {
             // TODO(Gas): Rewrite this in a better way.
-            if let Some((_, val)) = &loaded {
+            if let Some(val) = &val {
                 self.use_heap_memory(
                     self.gas_params
                         .misc
@@ -504,10 +505,13 @@ impl MoveGasMeter for StandardGasMeter {
                 )?;
             }
         }
+        if self.feature_version <= 8 && val.is_none() && bytes_loaded != 0.into() {
+            return Err(PartialVMError::new(StatusCode::UNKNOWN_INVARIANT_VIOLATION_ERROR).with_message("in legacy versions, number of bytes loaded must be zero when the resource does not exist ".to_string()));
+        }
         let cost = self
             .storage_gas_params
             .pricing
-            .calculate_read_gas(loaded.map(|(num_bytes, _)| num_bytes));
+            .calculate_read_gas(val.is_some(), bytes_loaded);
         self.charge_io(cost)
     }
 
diff --git a/aptos-move/aptos-gas/src/transaction/storage.rs b/aptos-move/aptos-gas/src/transaction/storage.rs
index fbe34fe9515e5..1da5181cfecce 100644
--- a/aptos-move/aptos-gas/src/transaction/storage.rs
+++ b/aptos-move/aptos-gas/src/transaction/storage.rs
@@ -143,12 +143,8 @@ impl StoragePricingV2 {
         }
     }
 
-    fn calculate_read_gas(&self, loaded: Option) -> InternalGas {
-        self.per_item_read * (NumArgs::from(1))
-            + match loaded {
-                Some(num_bytes) => self.per_byte_read * num_bytes,
-                None => 0.into(),
-            }
+    fn calculate_read_gas(&self, loaded: NumBytes) -> InternalGas {
+        self.per_item_read * (NumArgs::from(1)) + self.per_byte_read * loaded
     }
 
     fn io_gas_per_write(&self, key: &StateKey, op: &WriteOp) -> InternalGas {
@@ -175,12 +171,18 @@ pub enum StoragePricing {
 }
 
 impl StoragePricing {
-    pub fn calculate_read_gas(&self, loaded: Option) -> InternalGas {
+    pub fn calculate_read_gas(&self, resource_exists: bool, bytes_loaded: NumBytes) -> InternalGas {
         use StoragePricing::*;
 
         match self {
-            V1(v1) => v1.calculate_read_gas(loaded),
-            V2(v2) => v2.calculate_read_gas(loaded),
+            V1(v1) => v1.calculate_read_gas(
+                if resource_exists {
+                    Some(bytes_loaded)
+                } else {
+                    None
+                },
+            ),
+            V2(v2) => v2.calculate_read_gas(bytes_loaded),
         }
     }
 
diff --git a/aptos-move/aptos-vm/src/data_cache.rs b/aptos-move/aptos-vm/src/data_cache.rs
index 9e6c0954e0bd2..7f75f3d4d8bcb 100644
--- a/aptos-move/aptos-vm/src/data_cache.rs
+++ b/aptos-move/aptos-vm/src/data_cache.rs
@@ -21,7 +21,7 @@ use move_core_types::{
     account_address::AccountAddress,
     language_storage::{ModuleId, StructTag},
     metadata::Metadata,
-    resolver::{resource_add_cost, ModuleResolver, ResourceResolver},
+    resolver::{resource_size, ModuleResolver, ResourceResolver},
     vm_status::StatusCode,
 };
 use move_table_extension::{TableHandle, TableResolver};
@@ -94,7 +94,7 @@ impl<'a, S: StateView> StorageAdapter<'a, S> {
         address: &AccountAddress,
         struct_tag: &StructTag,
         metadata: &[Metadata],
-    ) -> Result, u64)>, VMError> {
+    ) -> Result<(Option>, usize), VMError> {
         let resource_group = get_resource_group_from_metadata(struct_tag, metadata);
         if let Some(resource_group) = resource_group {
             let mut cache = self.resource_group_cache.borrow_mut();
@@ -103,12 +103,13 @@ impl<'a, S: StateView> StorageAdapter<'a, S> {
                 // This resource group is already cached for this address. So just return the
                 // cached value.
                 let buf = group_data.get(struct_tag).cloned();
-                return Ok(resource_add_cost(buf, 0));
+                let buf_size = resource_size(&buf);
+                return Ok((buf, buf_size));
             }
             let group_data = self.get_resource_group_data(address, &resource_group)?;
             if let Some(group_data) = group_data {
                 let len = if self.accurate_byte_count {
-                    group_data.len() as u64
+                    group_data.len()
                 } else {
                     0
                 };
@@ -118,15 +119,17 @@ impl<'a, S: StateView> StorageAdapter<'a, S> {
                             .finish(Location::Undefined)
                     })?;
                 let res = group_data.get(struct_tag).cloned();
+                let res_size = resource_size(&res);
                 cache.insert(resource_group, group_data);
-                Ok(resource_add_cost(res, len))
+                Ok((res, res_size + len))
             } else {
                 cache.insert(resource_group, BTreeMap::new());
-                Ok(None)
+                Ok((None, 0))
             }
         } else {
             let buf = self.get_standard_resource(address, struct_tag)?;
-            Ok(resource_add_cost(buf, 0))
+            let buf_size = resource_size(&buf);
+            Ok((buf, buf_size))
         }
     }
 }
@@ -165,7 +168,7 @@ impl<'a, S: StateView> ResourceResolver for StorageAdapter<'a, S> {
         address: &AccountAddress,
         struct_tag: &StructTag,
         metadata: &[Metadata],
-    ) -> anyhow::Result, u64)>> {
+    ) -> anyhow::Result<(Option>, usize)> {
         Ok(self.get_any_resource(address, struct_tag, metadata)?)
     }
 }
diff --git a/aptos-move/framework/src/natives/object.rs b/aptos-move/framework/src/natives/object.rs
index d5c4fd6b869ba..169e25ec52b2b 100644
--- a/aptos-move/framework/src/natives/object.rs
+++ b/aptos-move/framework/src/natives/object.rs
@@ -53,15 +53,7 @@ fn native_exists_at(
     })?;
 
     if let Some(num_bytes) = num_bytes {
-        match num_bytes {
-            Some(num_bytes) => {
-                context
-                    .charge(gas_params.per_item_loaded + num_bytes * gas_params.per_byte_loaded)?;
-            },
-            None => {
-                context.charge(gas_params.per_item_loaded)?;
-            },
-        }
+        context.charge(gas_params.per_item_loaded + num_bytes * gas_params.per_byte_loaded)?;
     }
 
     Ok(smallvec![Value::bool(exists)])
diff --git a/third_party/move/extensions/async/move-async-vm/tests/testsuite.rs b/third_party/move/extensions/async/move-async-vm/tests/testsuite.rs
index 46d8dde897456..28bec3e0cb2cc 100644
--- a/third_party/move/extensions/async/move-async-vm/tests/testsuite.rs
+++ b/third_party/move/extensions/async/move-async-vm/tests/testsuite.rs
@@ -23,7 +23,7 @@ use move_core_types::{
     identifier::{IdentStr, Identifier},
     language_storage::{ModuleId, StructTag},
     metadata::Metadata,
-    resolver::{resource_add_cost, ModuleResolver, ResourceResolver},
+    resolver::{resource_size, ModuleResolver, ResourceResolver},
 };
 use move_prover_test_utils::{baseline_test::verify_or_update_baseline, extract_test_directives};
 use move_vm_test_utils::gas_schedule::GasStatus;
@@ -398,14 +398,15 @@ impl<'a> ResourceResolver for HarnessProxy<'a> {
         address: &AccountAddress,
         typ: &StructTag,
         _metadata: &[Metadata],
-    ) -> anyhow::Result, u64)>> {
+    ) -> anyhow::Result<(Option>, usize)> {
         let res = self
             .harness
             .resource_store
             .borrow()
             .get(&(*address, typ.clone()))
             .cloned();
-        Ok(resource_add_cost(res, 0))
+        let res_size = resource_size(&res);
+        Ok((res, res_size))
     }
 }
 
diff --git a/third_party/move/move-core/types/src/resolver.rs b/third_party/move/move-core/types/src/resolver.rs
index 5b8e5f405be49..5a43faaced949 100644
--- a/third_party/move/move-core/types/src/resolver.rs
+++ b/third_party/move/move-core/types/src/resolver.rs
@@ -26,6 +26,10 @@ pub trait ModuleResolver {
     fn get_module(&self, id: &ModuleId) -> Result>, Error>;
 }
 
+pub fn resource_size(resource: &Option>) -> usize {
+    resource.as_ref().map(|bytes| bytes.len()).unwrap_or(0)
+}
+
 /// A persistent storage backend that can resolve resources by address + type
 /// Storage backends should return
 ///   - Ok(Some(..)) if the data exists
@@ -41,14 +45,7 @@ pub trait ResourceResolver {
         address: &AccountAddress,
         typ: &StructTag,
         metadata: &[Metadata],
-    ) -> Result, u64)>, Error>;
-}
-
-pub fn resource_add_cost(buf: Option>, extra: u64) -> Option<(Vec, u64)> {
-    buf.map(|b| {
-        let len = b.len() as u64 + extra;
-        (b, len)
-    })
+    ) -> Result<(Option>, usize), Error>;
 }
 
 /// A persistent storage implementation that can resolve both resources and modules
@@ -60,7 +57,7 @@ pub trait MoveResolver: ModuleResolver + ResourceResolver {
     ) -> Result>, Error> {
         Ok(self
             .get_resource_with_metadata(address, typ, &self.get_module_metadata(&typ.module_id()))?
-            .map(|(buf, _)| buf))
+            .0)
     }
 }
 
@@ -72,7 +69,7 @@ impl ResourceResolver for &T {
         address: &AccountAddress,
         tag: &StructTag,
         metadata: &[Metadata],
-    ) -> Result, u64)>, Error> {
+    ) -> Result<(Option>, usize), Error> {
         (**self).get_resource_with_metadata(address, tag, metadata)
     }
 }
diff --git a/third_party/move/move-vm/integration-tests/src/tests/bad_storage_tests.rs b/third_party/move/move-vm/integration-tests/src/tests/bad_storage_tests.rs
index 69cc998a7275b..530b316c35ce7 100644
--- a/third_party/move/move-vm/integration-tests/src/tests/bad_storage_tests.rs
+++ b/third_party/move/move-vm/integration-tests/src/tests/bad_storage_tests.rs
@@ -526,7 +526,7 @@ impl ResourceResolver for BogusStorage {
         _address: &AccountAddress,
         _tag: &StructTag,
         _metadata: &[Metadata],
-    ) -> anyhow::Result, u64)>> {
+    ) -> anyhow::Result<(Option>, usize)> {
         Ok(Err(
             PartialVMError::new(self.bad_status_code).finish(Location::Undefined)
         )?)
diff --git a/third_party/move/move-vm/runtime/src/data_cache.rs b/third_party/move/move-vm/runtime/src/data_cache.rs
index ad8e69c586b6c..095df781c3135 100644
--- a/third_party/move/move-vm/runtime/src/data_cache.rs
+++ b/third_party/move/move-vm/runtime/src/data_cache.rs
@@ -157,7 +157,7 @@ impl<'r> TransactionDataCache<'r> {
         map.get_mut(k).unwrap()
     }
 
-    // Retrieve data from the local cache or loads it from the remote cache into the local cache.
+    // Retrieves data from the local cache or loads it from the remote cache into the local cache.
     // All operations on the global data are based on this API and they all load the data
     // into the cache.
     pub(crate) fn load_resource(
@@ -165,7 +165,7 @@ impl<'r> TransactionDataCache<'r> {
         loader: &Loader,
         addr: AccountAddress,
         ty: &Type,
-    ) -> PartialVMResult<(&mut GlobalValue, Option>)> {
+    ) -> PartialVMResult<(&mut GlobalValue, Option)> {
         let account_cache = Self::get_mut_or_insert_with(&mut self.account_map, &addr, || {
             (addr, AccountDataCache::new())
         });
@@ -189,12 +189,17 @@ impl<'r> TransactionDataCache<'r> {
                 None => &[],
             };
 
-            let gv = match self
+            let (data, bytes_loaded) = self
                 .remote
                 .get_resource_with_metadata(&addr, &ty_tag, metadata)
-            {
-                Ok(Some((blob, bytes))) => {
-                    load_res = Some(Some(NumBytes::new(bytes)));
+                .map_err(|err| {
+                    let msg = format!("Unexpected storage error: {:?}", err);
+                    PartialVMError::new(StatusCode::STORAGE_ERROR).with_message(msg)
+                })?;
+            load_res = Some(NumBytes::new(bytes_loaded as u64));
+
+            let gv = match data {
+                Some(blob) => {
                     let val = match Value::simple_deserialize(&blob, &ty_layout) {
                         Some(val) => val,
                         None => {
@@ -209,14 +214,7 @@ impl<'r> TransactionDataCache<'r> {
 
                     GlobalValue::cached(val)?
                 },
-                Ok(None) => {
-                    load_res = Some(None);
-                    GlobalValue::none()
-                },
-                Err(err) => {
-                    let msg = format!("Unexpected storage error: {:?}", err);
-                    return Err(PartialVMError::new(StatusCode::STORAGE_ERROR).with_message(msg));
-                },
+                None => GlobalValue::none(),
             };
 
             account_cache.data_map.insert(ty.clone(), (ty_layout, gv));
diff --git a/third_party/move/move-vm/runtime/src/interpreter.rs b/third_party/move/move-vm/runtime/src/interpreter.rs
index b2c8ee03884bf..37352abf4ef01 100644
--- a/third_party/move/move-vm/runtime/src/interpreter.rs
+++ b/third_party/move/move-vm/runtime/src/interpreter.rs
@@ -544,21 +544,13 @@ impl Interpreter {
     ) -> PartialVMResult<&'c mut GlobalValue> {
         match data_store.load_resource(loader, addr, ty) {
             Ok((gv, load_res)) => {
-                if let Some(loaded) = load_res {
-                    let opt = match loaded {
-                        Some(num_bytes) => {
-                            let view = gv.view().ok_or_else(|| {
-                                PartialVMError::new(StatusCode::UNKNOWN_INVARIANT_VIOLATION_ERROR)
-                                    .with_message(
-                                        "Failed to create view for global value".to_owned(),
-                                    )
-                            })?;
-
-                            Some((num_bytes, view))
-                        },
-                        None => None,
-                    };
-                    gas_meter.charge_load_resource(addr, TypeWithLoader { ty, loader }, opt)?;
+                if let Some(bytes_loaded) = load_res {
+                    gas_meter.charge_load_resource(
+                        addr,
+                        TypeWithLoader { ty, loader },
+                        gv.view(),
+                        bytes_loaded,
+                    )?;
                 }
                 Ok(gv)
             },
diff --git a/third_party/move/move-vm/runtime/src/native_functions.rs b/third_party/move/move-vm/runtime/src/native_functions.rs
index 3446e6e4ffd5e..d93a593231690 100644
--- a/third_party/move/move-vm/runtime/src/native_functions.rs
+++ b/third_party/move/move-vm/runtime/src/native_functions.rs
@@ -128,7 +128,7 @@ impl<'a, 'b, 'c> NativeContext<'a, 'b, 'c> {
         &mut self,
         address: AccountAddress,
         type_: &Type,
-    ) -> VMResult<(bool, Option>)> {
+    ) -> VMResult<(bool, Option)> {
         let (value, num_bytes) = self
             .data_store
             .load_resource(self.resolver.loader(), address, type_)
diff --git a/third_party/move/move-vm/runtime/src/session.rs b/third_party/move/move-vm/runtime/src/session.rs
index b0f93f0c1c886..a0582d785d78e 100644
--- a/third_party/move/move-vm/runtime/src/session.rs
+++ b/third_party/move/move-vm/runtime/src/session.rs
@@ -311,7 +311,7 @@ impl<'r, 'l> Session<'r, 'l> {
         &mut self,
         addr: AccountAddress,
         ty: &Type,
-    ) -> PartialVMResult<(&mut GlobalValue, Option>)> {
+    ) -> PartialVMResult<(&mut GlobalValue, Option)> {
         self.data_cache
             .load_resource(self.move_vm.runtime.loader(), addr, ty)
     }
diff --git a/third_party/move/move-vm/runtime/src/unit_tests/vm_arguments_tests.rs b/third_party/move/move-vm/runtime/src/unit_tests/vm_arguments_tests.rs
index 0dea6cca8c0b1..b7d2c457fe536 100644
--- a/third_party/move/move-vm/runtime/src/unit_tests/vm_arguments_tests.rs
+++ b/third_party/move/move-vm/runtime/src/unit_tests/vm_arguments_tests.rs
@@ -265,8 +265,8 @@ impl ResourceResolver for RemoteStore {
         _address: &AccountAddress,
         _tag: &StructTag,
         _metadata: &[Metadata],
-    ) -> anyhow::Result, u64)>> {
-        Ok(None)
+    ) -> anyhow::Result<(Option>, usize)> {
+        Ok((None, 0))
     }
 }
 
diff --git a/third_party/move/move-vm/test-utils/src/gas_schedule.rs b/third_party/move/move-vm/test-utils/src/gas_schedule.rs
index 7394a2c306b7a..3a0d918ca18d2 100644
--- a/third_party/move/move-vm/test-utils/src/gas_schedule.rs
+++ b/third_party/move/move-vm/test-utils/src/gas_schedule.rs
@@ -355,7 +355,8 @@ impl<'b> GasMeter for GasStatus<'b> {
         &mut self,
         _addr: AccountAddress,
         _ty: impl TypeView,
-        _loaded: Option<(NumBytes, impl ValueView)>,
+        _val: Option,
+        _bytes_loaded: NumBytes,
     ) -> PartialVMResult<()> {
         Ok(())
     }
diff --git a/third_party/move/move-vm/test-utils/src/storage.rs b/third_party/move/move-vm/test-utils/src/storage.rs
index 5f596e097ae2e..47b3cd80c61ef 100644
--- a/third_party/move/move-vm/test-utils/src/storage.rs
+++ b/third_party/move/move-vm/test-utils/src/storage.rs
@@ -9,7 +9,7 @@ use move_core_types::{
     identifier::Identifier,
     language_storage::{ModuleId, StructTag},
     metadata::Metadata,
-    resolver::{resource_add_cost, ModuleResolver, MoveResolver, ResourceResolver},
+    resolver::{resource_size, ModuleResolver, MoveResolver, ResourceResolver},
 };
 #[cfg(feature = "table-extension")]
 use move_table_extension::{TableChangeSet, TableHandle, TableResolver};
@@ -44,8 +44,8 @@ impl ResourceResolver for BlankStorage {
         _address: &AccountAddress,
         _tag: &StructTag,
         _metadata: &[Metadata],
-    ) -> Result, u64)>> {
-        Ok(None)
+    ) -> Result<(Option>, usize)> {
+        Ok((None, 0))
     }
 }
 
@@ -90,11 +90,12 @@ impl<'a, 'b, S: ResourceResolver> ResourceResolver for DeltaStorage<'a, 'b, S> {
         address: &AccountAddress,
         tag: &StructTag,
         metadata: &[Metadata],
-    ) -> Result, u64)>> {
+    ) -> Result<(Option>, usize)> {
         if let Some(account_storage) = self.delta.accounts().get(address) {
             if let Some(blob_opt) = account_storage.resources().get(tag) {
                 let buf = blob_opt.clone().ok();
-                return Ok(resource_add_cost(buf, 0));
+                let buf_size = resource_size(&buf);
+                return Ok((buf, buf_size));
             }
         }
 
@@ -304,12 +305,13 @@ impl ResourceResolver for InMemoryStorage {
         address: &AccountAddress,
         tag: &StructTag,
         _metadata: &[Metadata],
-    ) -> Result, u64)>> {
+    ) -> Result<(Option>, usize)> {
         if let Some(account_storage) = self.accounts.get(address) {
             let buf = account_storage.resources.get(tag).cloned();
-            return Ok(resource_add_cost(buf, 0));
+            let buf_size = resource_size(&buf);
+            return Ok((buf, buf_size));
         }
-        Ok(None)
+        Ok((None, 0))
     }
 }
 
diff --git a/third_party/move/move-vm/types/src/gas.rs b/third_party/move/move-vm/types/src/gas.rs
index 9afb608d2020d..5cd0c01d776aa 100644
--- a/third_party/move/move-vm/types/src/gas.rs
+++ b/third_party/move/move-vm/types/src/gas.rs
@@ -264,8 +264,6 @@ pub trait GasMeter {
 
     /// Charges for loading a resource from storage. This is only called when the resource is not
     /// cached.
-    /// - `Some(n)` means `n` bytes are loaded.
-    /// - `None` means a load operation is performed but the resource does not exist.
     ///
     /// WARNING: This can be dangerous if you execute multiple user transactions in the same
     /// session -- identical transactions can have different gas costs. Use at your own risk.
@@ -273,7 +271,8 @@ pub trait GasMeter {
         &mut self,
         addr: AccountAddress,
         ty: impl TypeView,
-        loaded: Option<(NumBytes, impl ValueView)>,
+        val: Option,
+        bytes_loaded: NumBytes,
     ) -> PartialVMResult<()>;
 
     /// Charge for executing a native function.
@@ -501,7 +500,8 @@ impl GasMeter for UnmeteredGasMeter {
         &mut self,
         _addr: AccountAddress,
         _ty: impl TypeView,
-        _loaded: Option<(NumBytes, impl ValueView)>,
+        _val: Option,
+        _bytes_loaded: NumBytes,
     ) -> PartialVMResult<()> {
         Ok(())
     }
diff --git a/third_party/move/tools/move-cli/src/sandbox/utils/on_disk_state_view.rs b/third_party/move/tools/move-cli/src/sandbox/utils/on_disk_state_view.rs
index 04489f2f8254d..7cd608489522a 100644
--- a/third_party/move/tools/move-cli/src/sandbox/utils/on_disk_state_view.rs
+++ b/third_party/move/tools/move-cli/src/sandbox/utils/on_disk_state_view.rs
@@ -17,7 +17,7 @@ use move_core_types::{
     language_storage::{ModuleId, StructTag, TypeTag},
     metadata::Metadata,
     parser,
-    resolver::{resource_add_cost, ModuleResolver, ResourceResolver},
+    resolver::{resource_size, ModuleResolver, ResourceResolver},
 };
 use move_disassembler::disassembler::Disassembler;
 use move_ir_types::location::Spanned;
@@ -418,9 +418,10 @@ impl ResourceResolver for OnDiskStateView {
         address: &AccountAddress,
         struct_tag: &StructTag,
         _metadata: &[Metadata],
-    ) -> Result, u64)>> {
+    ) -> Result<(Option>, usize)> {
         let buf = self.get_resource_bytes(*address, struct_tag.clone())?;
-        Ok(resource_add_cost(buf, 0))
+        let buf_size = resource_size(&buf);
+        Ok((buf, buf_size))
     }
 }
 

From c7f46d13c13753a0c9097a37672577743b1792be Mon Sep 17 00:00:00 2001
From: Maayan 
Date: Wed, 7 Jun 2023 21:22:19 +0300
Subject: [PATCH 092/200] bump version (#8564)

---
 ecosystem/typescript/sdk/CHANGELOG.md   | 2 ++
 ecosystem/typescript/sdk/package.json   | 2 +-
 ecosystem/typescript/sdk/src/version.ts | 2 +-
 3 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/ecosystem/typescript/sdk/CHANGELOG.md b/ecosystem/typescript/sdk/CHANGELOG.md
index 3d9909697182d..159286c05d29f 100644
--- a/ecosystem/typescript/sdk/CHANGELOG.md
+++ b/ecosystem/typescript/sdk/CHANGELOG.md
@@ -4,6 +4,8 @@ All notable changes to the Aptos Node SDK will be captured in this file. This ch
 
 ## Unreleased
 
+## 1.10.0 (2023-06-07)
+
 - Add `x-aptos-client` header to `IndexerClient` requests
 - Add `standardizeAddress` static function to `AccountAddress` class to standardizes an address to the format "0x" followed by 64 lowercase hexadecimal digits.
 - Change `indexerUrl` param on `Provider` class to an optional parameter
diff --git a/ecosystem/typescript/sdk/package.json b/ecosystem/typescript/sdk/package.json
index ffc4b37b0f88d..5f25d03e79885 100644
--- a/ecosystem/typescript/sdk/package.json
+++ b/ecosystem/typescript/sdk/package.json
@@ -85,5 +85,5 @@
     "typedoc": "^0.23.20",
     "typescript": "4.8.2"
   },
-  "version": "1.9.1"
+  "version": "1.10.0"
 }
diff --git a/ecosystem/typescript/sdk/src/version.ts b/ecosystem/typescript/sdk/src/version.ts
index ab7311f69fa54..db143ad4badcd 100644
--- a/ecosystem/typescript/sdk/src/version.ts
+++ b/ecosystem/typescript/sdk/src/version.ts
@@ -1,2 +1,2 @@
 // hardcoded for now, we would want to have it injected dynamically
-export const VERSION = "1.9.1";
+export const VERSION = "1.10.0";

From 129d9e14d5667d2b25e9fee9e8d56d0afacfab49 Mon Sep 17 00:00:00 2001
From: Perry Randall 
Date: Wed, 7 Jun 2023 10:45:17 -0700
Subject: [PATCH 093/200] [gha] Filter build node on pull request

Stop this workflow from running on all PRs

Test Plan: execute on PR, once landed shouldnt run on PR
---
 .github/workflows/build-node-binaries.yaml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/workflows/build-node-binaries.yaml b/.github/workflows/build-node-binaries.yaml
index fd4e64d8ae3de..a010b9d77f487 100644
--- a/.github/workflows/build-node-binaries.yaml
+++ b/.github/workflows/build-node-binaries.yaml
@@ -5,6 +5,8 @@ name: "Build Aptos Node Binaries"
 
 on:
   pull_request:
+    paths:
+      - ".github/workflows/build-node-binaries.yaml"
   workflow_dispatch:
     inputs:
       git_ref:

From c286ce75b2f2ed92a61bef979170d79507727ed1 Mon Sep 17 00:00:00 2001
From: gerben-stavenga <54682677+gerben-stavenga@users.noreply.github.com>
Date: Wed, 7 Jun 2023 21:36:40 +0200
Subject: [PATCH 094/200] Integrate fixes into mainnet (#8568)

---
 .../verifier/transaction_arg_validation.rs    | 217 ++++++++++++------
 .../aptos-vm/src/verifier/view_function.rs    |  50 +---
 .../pack/sources/args_test.move               |  19 ++
 .../src/tests/constructor_args.rs             |  22 ++
 4 files changed, 197 insertions(+), 111 deletions(-)

diff --git a/aptos-move/aptos-vm/src/verifier/transaction_arg_validation.rs b/aptos-move/aptos-vm/src/verifier/transaction_arg_validation.rs
index 3e69987cd8ac9..ec00229ebe57d 100644
--- a/aptos-move/aptos-vm/src/verifier/transaction_arg_validation.rs
+++ b/aptos-move/aptos-vm/src/verifier/transaction_arg_validation.rs
@@ -7,7 +7,11 @@
 //! for strings whether they consist of correct characters.
 
 use crate::{move_vm_ext::SessionExt, VMStatus};
-use move_binary_format::{errors::VMError, file_format_common::read_uleb128_as_u64};
+use move_binary_format::{
+    errors::{Location, PartialVMError},
+    file_format::FunctionDefinitionIndex,
+    file_format_common::read_uleb128_as_u64,
+};
 use move_core_types::{
     account_address::AccountAddress,
     ident_str,
@@ -123,10 +127,9 @@ pub(crate) fn validate_combine_signer_and_txn_args(
     }
 
     let allowed_structs = get_allowed_structs(are_struct_constructors_enabled);
-    // validate all non_signer params
-    let mut needs_construction = vec![];
-    for (idx, ty) in func.parameters[signer_param_cnt..].iter().enumerate() {
-        let (valid, construction) = is_valid_txn_arg(
+    // Need to keep this here to ensure we return the historic correct error code for replay
+    for ty in func.parameters[signer_param_cnt..].iter() {
+        let valid = is_valid_txn_arg(
             session,
             &ty.subst(&func.type_arguments).unwrap(),
             allowed_structs,
@@ -137,9 +140,6 @@ pub(crate) fn validate_combine_signer_and_txn_args(
                 None,
             ));
         }
-        if construction {
-            needs_construction.push(idx + signer_param_cnt);
-        }
     }
 
     if (signer_param_cnt + args.len()) != func.parameters.len() {
@@ -148,10 +148,20 @@ pub(crate) fn validate_combine_signer_and_txn_args(
             None,
         ));
     }
+
+    let args = construct_args(
+        session,
+        &func.parameters[signer_param_cnt..],
+        args,
+        &func.type_arguments,
+        allowed_structs,
+        false,
+    )?;
+
     // if function doesn't require signer, we reuse txn args
     // if the function require signer, we check senders number same as signers
     // and then combine senders with txn args.
-    let mut combined_args = if signer_param_cnt == 0 {
+    let combined_args = if signer_param_cnt == 0 {
         args
     } else {
         // the number of txn senders should be the same number of signers
@@ -167,15 +177,6 @@ pub(crate) fn validate_combine_signer_and_txn_args(
             .chain(args)
             .collect()
     };
-    if !needs_construction.is_empty() {
-        construct_args(
-            session,
-            &needs_construction,
-            &mut combined_args,
-            func,
-            allowed_structs,
-        )?;
-    }
     Ok(combined_args)
 }
 
@@ -184,21 +185,21 @@ pub(crate) fn is_valid_txn_arg(
     session: &SessionExt,
     typ: &Type,
     allowed_structs: &ConstructorMap,
-) -> (bool, bool) {
+) -> bool {
     use move_vm_types::loaded_data::runtime_types::Type::*;
 
     match typ {
-        Bool | U8 | U16 | U32 | U64 | U128 | U256 | Address => (true, false),
+        Bool | U8 | U16 | U32 | U64 | U128 | U256 | Address => true,
         Vector(inner) => is_valid_txn_arg(session, inner, allowed_structs),
         Struct(idx) | StructInstantiation(idx, _) => {
             if let Some(st) = session.get_struct_type(*idx) {
                 let full_name = format!("{}::{}", st.module.short_str_lossless(), st.name);
-                (allowed_structs.contains_key(&full_name), true)
+                allowed_structs.contains_key(&full_name)
             } else {
-                (false, false)
+                false
             }
         },
-        Signer | Reference(_) | MutableReference(_) | TyParam(_) => (false, false),
+        Signer | Reference(_) | MutableReference(_) | TyParam(_) => false,
     }
 }
 
@@ -207,41 +208,81 @@ pub(crate) fn is_valid_txn_arg(
 // TODO: This needs a more solid story and a tighter integration with the VM.
 pub(crate) fn construct_args(
     session: &mut SessionExt,
-    idxs: &[usize],
-    args: &mut [Vec],
-    func: &LoadedFunctionInstantiation,
+    types: &[Type],
+    args: Vec>,
+    ty_args: &[Type],
     allowed_structs: &ConstructorMap,
-) -> Result<(), VMStatus> {
+    is_view: bool,
+) -> Result>, VMStatus> {
     // Perhaps in a future we should do proper gas metering here
     let mut gas_meter = UnmeteredGasMeter;
-    for (idx, ty) in func.parameters.iter().enumerate() {
-        if !idxs.contains(&idx) {
-            continue;
-        }
-        let arg = &mut args[idx];
-        let mut cursor = Cursor::new(&arg[..]);
-        let mut new_arg = vec![];
-        recursively_construct_arg(
+    let mut res_args = vec![];
+    if types.len() != args.len() {
+        return Err(invalid_signature());
+    }
+    for (ty, arg) in types.iter().zip(args.into_iter()) {
+        let arg = construct_arg(
             session,
-            &ty.subst(&func.type_arguments).unwrap(),
+            &ty.subst(ty_args).unwrap(),
             allowed_structs,
-            &mut cursor,
+            arg,
             &mut gas_meter,
-            &mut new_arg,
+            is_view,
         )?;
-        // Check cursor has parsed everything
-        // Unfortunately, is_empty is only enabled in nightly, so we check this way.
-        if cursor.position() != arg.len() as u64 {
-            return Err(VMStatus::Error(
-                StatusCode::FAILED_TO_DESERIALIZE_ARGUMENT,
-                Some(String::from(
-                    "The serialized arguments to constructor contained extra data",
-                )),
-            ));
-        }
-        *arg = new_arg;
+        res_args.push(arg);
+    }
+    Ok(res_args)
+}
+
+fn invalid_signature() -> VMStatus {
+    VMStatus::Error(StatusCode::INVALID_MAIN_FUNCTION_SIGNATURE, None)
+}
+
+fn construct_arg(
+    session: &mut SessionExt,
+    ty: &Type,
+    allowed_structs: &ConstructorMap,
+    arg: Vec,
+    gas_meter: &mut impl GasMeter,
+    is_view: bool,
+) -> Result, VMStatus> {
+    use move_vm_types::loaded_data::runtime_types::Type::*;
+    match ty {
+        Bool | U8 | U16 | U32 | U64 | U128 | U256 | Address => Ok(arg),
+        Vector(_) | Struct(_) | StructInstantiation(_, _) => {
+            let mut cursor = Cursor::new(&arg[..]);
+            let mut new_arg = vec![];
+            let mut max_invocations = 10; // Read from config in the future
+            recursively_construct_arg(
+                session,
+                ty,
+                allowed_structs,
+                &mut cursor,
+                gas_meter,
+                &mut max_invocations,
+                &mut new_arg,
+            )?;
+            // Check cursor has parsed everything
+            // Unfortunately, is_empty is only enabled in nightly, so we check this way.
+            if cursor.position() != arg.len() as u64 {
+                return Err(VMStatus::Error(
+                    StatusCode::FAILED_TO_DESERIALIZE_ARGUMENT,
+                    Some(String::from(
+                        "The serialized arguments to constructor contained extra data",
+                    )),
+                ));
+            }
+            Ok(new_arg)
+        },
+        Signer => {
+            if is_view {
+                Ok(arg)
+            } else {
+                Err(invalid_signature())
+            }
+        },
+        Reference(_) | MutableReference(_) | TyParam(_) => Err(invalid_signature()),
     }
-    Ok(())
 }
 
 // A Cursor is used to recursively walk the serialized arg manually and correctly. In effect we
@@ -253,6 +294,7 @@ pub(crate) fn recursively_construct_arg(
     allowed_structs: &ConstructorMap,
     cursor: &mut Cursor<&[u8]>,
     gas_meter: &mut impl GasMeter,
+    max_invocations: &mut u64,
     arg: &mut Vec,
 ) -> Result<(), VMStatus> {
     use move_vm_types::loaded_data::runtime_types::Type::*;
@@ -263,7 +305,15 @@ pub(crate) fn recursively_construct_arg(
             let mut len = get_len(cursor)?;
             serialize_uleb128(len, arg);
             while len > 0 {
-                recursively_construct_arg(session, inner, allowed_structs, cursor, gas_meter, arg)?;
+                recursively_construct_arg(
+                    session,
+                    inner,
+                    allowed_structs,
+                    cursor,
+                    gas_meter,
+                    max_invocations,
+                    arg,
+                )?;
                 len -= 1;
             }
         },
@@ -272,11 +322,11 @@ pub(crate) fn recursively_construct_arg(
             // performed in `is_valid_txn_arg`
             let st = session
                 .get_struct_type(*idx)
-                .expect("unreachable, type must exist");
+                .ok_or_else(invalid_signature)?;
             let full_name = format!("{}::{}", st.module.short_str_lossless(), st.name);
             let constructor = allowed_structs
                 .get(&full_name)
-                .expect("unreachable: struct must be allowed");
+                .ok_or_else(invalid_signature)?;
             // By appending the BCS to the output parameter we construct the correct BCS format
             // of the argument.
             arg.append(&mut validate_and_construct(
@@ -286,6 +336,7 @@ pub(crate) fn recursively_construct_arg(
                 allowed_structs,
                 cursor,
                 gas_meter,
+                max_invocations,
             )?);
         },
         Bool | U8 => read_n_bytes(1, cursor, arg)?,
@@ -294,11 +345,8 @@ pub(crate) fn recursively_construct_arg(
         U64 => read_n_bytes(8, cursor, arg)?,
         U128 => read_n_bytes(16, cursor, arg)?,
         U256 | Address => read_n_bytes(32, cursor, arg)?,
-        Signer | Reference(_) | MutableReference(_) | TyParam(_) => {
-            unreachable!("We already checked for this in is-valid-txn-arg")
-        },
+        Signer | Reference(_) | MutableReference(_) | TyParam(_) => return Err(invalid_signature()),
     };
-
     Ok(())
 }
 
@@ -313,7 +361,45 @@ fn validate_and_construct(
     allowed_structs: &ConstructorMap,
     cursor: &mut Cursor<&[u8]>,
     gas_meter: &mut impl GasMeter,
+    max_invocations: &mut u64,
 ) -> Result, VMStatus> {
+    if *max_invocations == 0 {
+        return Err(VMStatus::Error(
+            StatusCode::FAILED_TO_DESERIALIZE_ARGUMENT,
+            None,
+        ));
+    }
+    // HACK mitigation of performance attack
+    // To maintain compatibility with vector or so on, we need to allow unlimited strings.
+    // So we do not count the string constructor against the max_invocations, instead we
+    // shortcut the string case to avoid the performance attack.
+    if constructor.func_name.as_str() == "utf8" {
+        let constructor_error = || {
+            // A slight hack, to prevent additional piping of the feature flag through all
+            // function calls. We know the feature is active when more structs then just strings are
+            // allowed.
+            let are_struct_constructors_enabled = allowed_structs.len() > 1;
+            if are_struct_constructors_enabled {
+                PartialVMError::new(StatusCode::ABORTED)
+                    .with_sub_status(1)
+                    .at_code_offset(FunctionDefinitionIndex::new(0), 0)
+                    .finish(Location::Module(constructor.module_id.clone()))
+                    .into_vm_status()
+            } else {
+                VMStatus::Error(StatusCode::FAILED_TO_DESERIALIZE_ARGUMENT, None)
+            }
+        };
+        // short cut for the utf8 constructor, which is a special case
+        let len = get_len(cursor)?;
+        let mut arg = vec![];
+        read_n_bytes(len, cursor, &mut arg)?;
+        std::str::from_utf8(&arg).map_err(|_| constructor_error())?;
+        return bcs::to_bytes(&arg)
+            .map_err(|_| VMStatus::Error(StatusCode::FAILED_TO_DESERIALIZE_ARGUMENT, None));
+    } else {
+        *max_invocations -= 1;
+    }
+
     let (function, instantiation) = session.load_function_with_type_arg_inference(
         &constructor.module_id,
         constructor.func_name,
@@ -328,24 +414,13 @@ fn validate_and_construct(
             allowed_structs,
             cursor,
             gas_meter,
+            max_invocations,
             &mut arg,
         )?;
         args.push(arg);
     }
-    let constructor_error = |e: VMError| {
-        // A slight hack, to prevent additional piping of the feature flag through all
-        // function calls. We know the feature is active when more structs then just strings are
-        // allowed.
-        let are_struct_constructors_enabled = allowed_structs.len() > 1;
-        if are_struct_constructors_enabled {
-            e.into_vm_status()
-        } else {
-            VMStatus::Error(StatusCode::FAILED_TO_DESERIALIZE_ARGUMENT, None)
-        }
-    };
-    let serialized_result = session
-        .execute_instantiated_function(function, instantiation, args, gas_meter)
-        .map_err(constructor_error)?;
+    let serialized_result =
+        session.execute_instantiated_function(function, instantiation, args, gas_meter)?;
     let mut ret_vals = serialized_result.return_values;
     // We know ret_vals.len() == 1
     let deserialize_error = VMStatus::Error(
diff --git a/aptos-move/aptos-vm/src/verifier/view_function.rs b/aptos-move/aptos-vm/src/verifier/view_function.rs
index 1870fddcf9ddd..00cc38e0efd3c 100644
--- a/aptos-move/aptos-vm/src/verifier/view_function.rs
+++ b/aptos-move/aptos-vm/src/verifier/view_function.rs
@@ -9,7 +9,6 @@ use aptos_framework::RuntimeModuleMetadataV1;
 use move_binary_format::errors::{PartialVMError, PartialVMResult};
 use move_core_types::{identifier::IdentStr, vm_status::StatusCode};
 use move_vm_runtime::session::LoadedFunctionInstantiation;
-use move_vm_types::loaded_data::runtime_types::Type;
 
 /// Based on the function attributes in the module metadata, determine whether a
 /// function is a view function.
@@ -31,7 +30,7 @@ pub fn determine_is_view(
 /// function, and validates the arguments.
 pub(crate) fn validate_view_function(
     session: &mut SessionExt,
-    mut args: Vec>,
+    args: Vec>,
     fun_name: &IdentStr,
     fun_inst: &LoadedFunctionInstantiation,
     module_metadata: Option<&RuntimeModuleMetadataV1>,
@@ -55,43 +54,14 @@ pub(crate) fn validate_view_function(
     }
 
     let allowed_structs = get_allowed_structs(struct_constructors_feature);
-    // Validate arguments. We allow all what transaction allows, in addition, signers can
-    // be passed. Some arguments (e.g. utf8 strings) need validation which happens here.
-    let mut needs_construction = vec![];
-    for (idx, ty) in fun_inst.parameters.iter().enumerate() {
-        match ty {
-            Type::Signer => continue,
-            Type::Reference(inner_type) if matches!(&**inner_type, Type::Signer) => continue,
-            _ => {
-                let (valid, construction) =
-                    transaction_arg_validation::is_valid_txn_arg(session, ty, allowed_structs);
-                if !valid {
-                    return Err(
-                        PartialVMError::new(StatusCode::INVALID_MAIN_FUNCTION_SIGNATURE)
-                            .with_message("invalid view function argument".to_string()),
-                    );
-                }
-                if construction {
-                    needs_construction.push(idx);
-                }
-            },
-        }
-    }
-    if !needs_construction.is_empty()
-        && transaction_arg_validation::construct_args(
-            session,
-            &needs_construction,
-            &mut args,
-            fun_inst,
-            allowed_structs,
-        )
-        .is_err()
-    {
-        return Err(
-            PartialVMError::new(StatusCode::INVALID_MAIN_FUNCTION_SIGNATURE)
-                .with_message("invalid view function argument: failed validation".to_string()),
-        );
-    }
-
+    let args = transaction_arg_validation::construct_args(
+        session,
+        &fun_inst.parameters,
+        args,
+        &fun_inst.type_arguments,
+        allowed_structs,
+        true,
+    )
+    .map_err(|e| PartialVMError::new(e.status_code()))?;
     Ok(args)
 }
diff --git a/aptos-move/e2e-move-tests/src/tests/constructor_args.data/pack/sources/args_test.move b/aptos-move/e2e-move-tests/src/tests/constructor_args.data/pack/sources/args_test.move
index a5fbaed167e68..0dd613099c3c9 100644
--- a/aptos-move/e2e-move-tests/src/tests/constructor_args.data/pack/sources/args_test.move
+++ b/aptos-move/e2e-move-tests/src/tests/constructor_args.data/pack/sources/args_test.move
@@ -90,6 +90,25 @@ module 0xCAFE::test {
         };
     }
 
+    // Valuable data that should not be able to be fabricated by a malicious tx
+    struct MyPrecious {
+        value: u64,
+    }
+
+    public entry fun ensure_no_fabrication(my_precious: Option) {
+        if (std::option::is_none(&my_precious)) {
+            std::option::destroy_none(my_precious)
+        } else {
+            let MyPrecious { value : _ } = std::option::destroy_some(my_precious);
+        }
+    }
+
+    public entry fun ensure_vector_vector_u8(o: Object, _: vector>) acquires ModuleData {
+        let addr = aptos_std::object::object_address(&o);
+        // guaranteed to exist
+        borrow_global_mut(addr).state = std::string::utf8(b"vector>");
+    }
+
     fun convert(x: u128): String {
         let s = std::vector::empty();
         let ascii0 = 48;
diff --git a/aptos-move/e2e-move-tests/src/tests/constructor_args.rs b/aptos-move/e2e-move-tests/src/tests/constructor_args.rs
index 89e5275f063d7..f4fa91804d09d 100644
--- a/aptos-move/e2e-move-tests/src/tests/constructor_args.rs
+++ b/aptos-move/e2e-move-tests/src/tests/constructor_args.rs
@@ -156,6 +156,14 @@ fn constructor_args_good() {
             ],
             "pff vectors of optionals",
         ),
+        (
+            "0xcafe::test::ensure_vector_vector_u8",
+            vec![
+                bcs::to_bytes(&OBJECT_ADDRESS).unwrap(), // Object
+                bcs::to_bytes(&vec![vec![1u8], vec![2u8]]).unwrap(), // vector>
+            ],
+            "vector>",
+        ),
     ];
 
     let mut h = MoveHarness::new_with_features(vec![FeatureFlag::STRUCT_CONSTRUCTORS], vec![]);
@@ -228,6 +236,20 @@ fn constructor_args_bad() {
                 )
             }),
         ),
+        (
+            "0xcafe::test::ensure_no_fabrication",
+            vec![
+                bcs::to_bytes(&vec![1u64]).unwrap(), // Option
+            ],
+            Box::new(|e| {
+                matches!(
+                    e,
+                    TransactionStatus::Keep(ExecutionStatus::MiscellaneousError(Some(
+                        StatusCode::INVALID_MAIN_FUNCTION_SIGNATURE
+                    )))
+                )
+            }),
+        ),
     ];
 
     fail(tests);

From 1701353b391b3b26ece9c812e588107f66c90831 Mon Sep 17 00:00:00 2001
From: Stelian Ionescu 
Date: Wed, 7 Jun 2023 16:36:52 -0400
Subject: [PATCH 095/200] [TF] Use a ManagedCertificate for testnet-addons
 ingress (#8552)

---
 terraform/aptos-node-testnet/gcp/addons.tf    | 23 ++-----------------
 terraform/helm/testnet-addons/README.md       |  3 +++
 .../testnet-addons/templates/ingress.yaml     | 23 +++++++++++++------
 terraform/helm/testnet-addons/values.yaml     |  6 +++--
 4 files changed, 25 insertions(+), 30 deletions(-)

diff --git a/terraform/aptos-node-testnet/gcp/addons.tf b/terraform/aptos-node-testnet/gcp/addons.tf
index 7773fb4c7cc20..3bd31c0487e19 100644
--- a/terraform/aptos-node-testnet/gcp/addons.tf
+++ b/terraform/aptos-node-testnet/gcp/addons.tf
@@ -130,25 +130,6 @@ resource "google_compute_global_address" "testnet-addons-ingress" {
   name    = "aptos-${local.workspace_name}-testnet-addons-ingress"
 }
 
-# This kind of certificate is a GCE resource, and has to be
-# added to the ingress using ingress.gcp.kubernetes.io/pre-shared-cert.
-# K8s ManagedCertificate resources use
-# networking.gke.io/managed-certificates instead.
-resource "google_compute_managed_ssl_certificate" "testnet-addons" {
-  count   = var.zone_name != "" ? 1 : 0
-  project = var.project
-  name    = "aptos-${local.workspace_name}-testnet-addons"
-  lifecycle {
-    create_before_destroy = true
-  }
-  managed {
-    domains = [
-      "${local.domain}.",
-      "api.${local.domain}.",
-    ]
-  }
-}
-
 resource "helm_release" "testnet-addons" {
   count       = var.enable_forge ? 0 : 1
   name        = "testnet-addons"
@@ -171,8 +152,8 @@ resource "helm_release" "testnet-addons" {
         domain = local.domain
       }
       ingress = {
-        gcp_static_ip   = "aptos-${local.workspace_name}-testnet-addons-ingress"
-        gcp_certificate = "aptos-${local.workspace_name}-testnet-addons"
+        gce_static_ip           = "aptos-${local.workspace_name}-testnet-addons-ingress"
+        gce_managed_certificate = "aptos-${local.workspace_name}-testnet-addons"
       }
       load_test = {
         fullnodeGroups = try(var.aptos_node_helm_values.fullnode.groups, [])
diff --git a/terraform/helm/testnet-addons/README.md b/terraform/helm/testnet-addons/README.md
index 3e787d3fac08d..2e898549d11a2 100644
--- a/terraform/helm/testnet-addons/README.md
+++ b/terraform/helm/testnet-addons/README.md
@@ -14,6 +14,7 @@ Additional components for aptos-nodes testnet
 
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
+| cloud | string | `"EKS"` |  |
 | genesis.chain_id | string | `nil` | Aptos Chain ID |
 | genesis.numValidators | string | `nil` | Number of validators deployed in this testnet |
 | genesis.username_prefix | string | `"aptos-node"` | Validator username prefix, used to get genesis secrets. This should be the fullname for the aptos-node helm release |
@@ -21,6 +22,8 @@ Additional components for aptos-nodes testnet
 | ingress.acm_certificate | string | `nil` | The ACM certificate to install on the ingress |
 | ingress.cookieDurationSeconds | int | `86400` | If stickiness is enabled, how long the session cookie should last |
 | ingress.enableStickyness | bool | `true` | Whether to enable session stickiness on the underlying load balancer |
+| ingress.gce_managed_certificate | string | `nil` | The GCE certificate to install on the ingress |
+| ingress.gce_static_ip | string | `nil` | The GCE static IP to install on the ingress |
 | ingress.loadBalancerSourceRanges | string | `nil` | List of CIDRs to accept traffic from |
 | ingress.wafAclArn | string | `nil` | The ARN of the WAF ACL to install on the ingress |
 | load_test.affinity | object | `{}` |  |
diff --git a/terraform/helm/testnet-addons/templates/ingress.yaml b/terraform/helm/testnet-addons/templates/ingress.yaml
index 5ae3b596ac921..632a9fc2fe545 100644
--- a/terraform/helm/testnet-addons/templates/ingress.yaml
+++ b/terraform/helm/testnet-addons/templates/ingress.yaml
@@ -35,9 +35,9 @@ metadata:
     kubernetes.io/ingress.class: "gce"
     # Allow HTTP but always return 301 because we have redirectToHttps enabled
     kubernetes.io/ingress.allow-http: "true"
-    kubernetes.io/ingress.global-static-ip-name: {{ .Values.ingress.gcp_static_ip }}
-    ingress.gcp.kubernetes.io/pre-shared-cert: {{ .Values.ingress.gcp_certificate }}
-    networking.gke.io/v1beta1.FrontendConfig: {{ include "testnet-addons.fullname" . }}-api
+    kubernetes.io/ingress.global-static-ip-name: {{ .Values.ingress.gce_static_ip }}
+    networking.gke.io/managed-certificates: {{ .Values.ingress.gce_managed_certificate }}
+    networking.gke.io/v1beta1.FrontendConfig: {{ include "testnet-addons.fullname" . }}
     {{- end }} # "GKE"
 spec:
   rules:
@@ -53,7 +53,8 @@ spec:
             port:
               number: 80
   {{- end }}
-  - http:
+  - host: {{ .Values.service.domain }}
+    http:
       paths:
       - path: /waypoint.txt
         pathType: Exact
@@ -81,10 +82,18 @@ spec:
 apiVersion: networking.gke.io/v1beta1
 kind: FrontendConfig
 metadata:
-  name: {{ include "testnet-addons.fullname" . }}-api
-  namespace: default
+  name: {{ include "testnet-addons.fullname" . }}
 spec:
   redirectToHttps:
     enabled: true
-{{- end }}
 ---
+apiVersion: networking.gke.io/v1
+kind: ManagedCertificate
+metadata:
+  name: {{ .Values.ingress.gce_managed_certificate }}
+spec:
+  domains:
+    - {{ .Values.service.domain }}
+    - api.{{ .Values.service.domain }}
+---
+{{- end }}
diff --git a/terraform/helm/testnet-addons/values.yaml b/terraform/helm/testnet-addons/values.yaml
index e9e5974ef483b..f407c62591e2b 100644
--- a/terraform/helm/testnet-addons/values.yaml
+++ b/terraform/helm/testnet-addons/values.yaml
@@ -83,8 +83,10 @@ service:
 ingress:
   # -- The ACM certificate to install on the ingress
   acm_certificate:
-  # -- The GCP certificate to install on the ingress
-  gcp_certificate:
+  # -- The GCE static IP to install on the ingress
+  gce_static_ip:
+  # -- The GCE certificate to install on the ingress
+  gce_managed_certificate:
   # -- The ARN of the WAF ACL to install on the ingress
   wafAclArn:
   # -- List of CIDRs to accept traffic from

From 182e238d634786bdbb3f8690a67c175aefffa44a Mon Sep 17 00:00:00 2001
From: xindingw <127153552+xindingw@users.noreply.github.com>
Date: Wed, 7 Jun 2023 13:40:45 -0700
Subject: [PATCH 096/200] Fix stake flow diagram (#8571)

---
 developer-docs-site/static/img/docs/stake-state-dark.svg | 2 +-
 developer-docs-site/static/img/docs/stake-state.svg      | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/developer-docs-site/static/img/docs/stake-state-dark.svg b/developer-docs-site/static/img/docs/stake-state-dark.svg
index 6bdd4443997d4..4259015529111 100644
--- a/developer-docs-site/static/img/docs/stake-state-dark.svg
+++ b/developer-docs-site/static/img/docs/stake-state-dark.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/developer-docs-site/static/img/docs/stake-state.svg b/developer-docs-site/static/img/docs/stake-state.svg
index bb9691f3aa089..5706b931c2d24 100644
--- a/developer-docs-site/static/img/docs/stake-state.svg
+++ b/developer-docs-site/static/img/docs/stake-state.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
\ No newline at end of file

From 151a29149caaca2cbca7ea947c232d08e0b10c80 Mon Sep 17 00:00:00 2001
From: igor-aptos <110557261+igor-aptos@users.noreply.github.com>
Date: Wed, 7 Jun 2023 14:25:46 -0700
Subject: [PATCH 097/200] real-world network land_blocking test to replace the
 old one (#8542)

* real-world network land_blocking test to replace the old one

* add inner traffic and chain state to report

---------

Co-authored-by: Igor 
---
 .github/workflows/forge-stable.yaml           | 10 ++--
 .../src/emitter/stats.rs                      |  8 ++-
 testsuite/forge-cli/src/main.rs               | 59 ++++++++++++++-----
 testsuite/forge/src/interface/network.rs      |  3 +-
 testsuite/forge/src/report.rs                 | 36 ++++-------
 testsuite/forge/src/success_criteria.rs       | 57 ++++++++++--------
 testsuite/testcases/src/compatibility_test.rs | 10 +---
 .../src/consensus_reliability_tests.rs        |  9 ++-
 testsuite/testcases/src/framework_upgrade.rs  |  1 -
 .../src/fullnode_reboot_stress_test.rs        |  9 ++-
 testsuite/testcases/src/lib.rs                | 13 ++--
 .../testcases/src/partial_nodes_down_test.rs  |  2 +-
 .../src/quorum_store_onchain_enable_test.rs   |  1 +
 testsuite/testcases/src/two_traffics_test.rs  | 18 ++++--
 .../src/validator_join_leave_test.rs          | 10 +++-
 .../src/validator_reboot_stress_test.rs       |  9 ++-
 16 files changed, 157 insertions(+), 98 deletions(-)

diff --git a/.github/workflows/forge-stable.yaml b/.github/workflows/forge-stable.yaml
index 37bb72629c537..2e5eed5c8d212 100644
--- a/.github/workflows/forge-stable.yaml
+++ b/.github/workflows/forge-stable.yaml
@@ -284,18 +284,18 @@ jobs:
       FORGE_TEST_SUITE: state_sync_perf_fullnodes_apply_outputs
       POST_TO_SLACK: ${{ needs.determine-test-metadata.outputs.BRANCH == 'main' }} # only post to slack on main branch
 
-  ### Additional three-region tests. Eventually all consensus-related tests should migrate to three-regions.
+  ### Additional real-world-network tests. Eventually all consensus-related tests should migrate to real-world-network.
 
-  run-forge-land-blocking-three-region:
+  run-forge-realistic-env-max-throughput:
     if: ${{ github.event_name != 'pull_request' }}
     needs: determine-test-metadata
     uses: aptos-labs/aptos-core/.github/workflows/workflow-run-forge.yaml@main
     secrets: inherit
     with:
       IMAGE_TAG: ${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
-      FORGE_NAMESPACE: forge-land-blocking-three-region-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
-      FORGE_RUNNER_DURATION_SECS: 1800
-      FORGE_TEST_SUITE: land_blocking_three_region
+      FORGE_NAMESPACE: forge-land-blocking-new-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
+      FORGE_RUNNER_DURATION_SECS: 600
+      FORGE_TEST_SUITE: realistic_env_max_throughput
       POST_TO_SLACK: true
 
   run-forge-three-region-graceful-overload:
diff --git a/crates/transaction-emitter-lib/src/emitter/stats.rs b/crates/transaction-emitter-lib/src/emitter/stats.rs
index 471757400e394..e95d092453718 100644
--- a/crates/transaction-emitter-lib/src/emitter/stats.rs
+++ b/crates/transaction-emitter-lib/src/emitter/stats.rs
@@ -40,8 +40,12 @@ impl fmt::Display for TxnStatsRate {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(
             f,
-            "submitted: {} txn/s, committed: {} txn/s, expired: {} txn/s, failed submission: {} tnx/s, latency: {} ms, (p50: {} ms, p90: {} ms, p99: {} ms), latency samples: {}",
-            self.submitted, self.committed, self.expired, self.failed_submission, self.latency, self.p50_latency, self.p90_latency, self.p99_latency, self.latency_samples,
+            "committed: {} txn/s{}{}{}, latency: {} ms, (p50: {} ms, p90: {} ms, p99: {} ms), latency samples: {}",
+            self.committed,
+            if self.submitted != self.committed { format!(", submitted: {} txn/s", self.submitted) } else { "".to_string()},
+            if self.failed_submission != 0 { format!(", failed submission: {} txn/s", self.failed_submission) } else { "".to_string()},
+            if self.expired != 0 { format!(", expired: {} txn/s", self.expired) } else { "".to_string()},
+            self.latency, self.p50_latency, self.p90_latency, self.p99_latency, self.latency_samples,
         )
     }
 }
diff --git a/testsuite/forge-cli/src/main.rs b/testsuite/forge-cli/src/main.rs
index 3e5196ea74896..1b219b55b3474 100644
--- a/testsuite/forge-cli/src/main.rs
+++ b/testsuite/forge-cli/src/main.rs
@@ -445,15 +445,13 @@ fn get_changelog(prev_commit: Option<&String>, upstream_commit: &str) -> String
 
 fn get_test_suite(suite_name: &str, duration: Duration) -> Result> {
     match suite_name {
-        "land_blocking" => Ok(land_blocking_test_suite(duration)),
-        "land_blocking_three_region" => Ok(land_blocking_three_region_test_suite(duration)),
         "local_test_suite" => Ok(local_test_suite()),
         "pre_release" => Ok(pre_release_suite()),
         "run_forever" => Ok(run_forever()),
         // TODO(rustielin): verify each test suite
         "k8s_suite" => Ok(k8s_test_suite()),
         "chaos" => Ok(chaos_test_suite(duration)),
-        single_test => single_test_suite(single_test),
+        single_test => single_test_suite(single_test, duration),
     }
 }
 
@@ -485,10 +483,16 @@ fn k8s_test_suite() -> ForgeConfig<'static> {
         ])
 }
 
-fn single_test_suite(test_name: &str) -> Result> {
+fn single_test_suite(test_name: &str, duration: Duration) -> Result> {
     let config =
         ForgeConfig::default().with_initial_validator_count(NonZeroUsize::new(30).unwrap());
     let single_test_suite = match test_name {
+        // Land-blocking tests to be run on every PR:
+        "land_blocking" => land_blocking_test_suite(duration), // to remove land_blocking, superseeded by the below
+        "realistic_env_max_throughput" => realistic_env_max_throughput_test_suite(duration),
+        "compat" => compat(config),
+        "framework_upgrade" => upgrade(config),
+        // Rest of the tests:
         "epoch_changer_performance" => epoch_changer_performance(config),
         "state_sync_perf_fullnodes_apply_outputs" => {
             state_sync_perf_fullnodes_apply_outputs(config)
@@ -499,8 +503,6 @@ fn single_test_suite(test_name: &str) -> Result> {
         "state_sync_perf_fullnodes_fast_sync" => state_sync_perf_fullnodes_fast_sync(config),
         "state_sync_perf_validators" => state_sync_perf_validators(config),
         "validators_join_and_leave" => validators_join_and_leave(config),
-        "compat" => compat(config),
-        "framework_upgrade" => upgrade(config),
         "config" => config.with_network_tests(vec![&ReconfigurationTest]),
         "network_partition" => network_partition(config),
         "three_region_simulation" => three_region_simulation(config),
@@ -873,7 +875,7 @@ fn graceful_overload(config: ForgeConfig) -> ForgeConfig {
         // So having VFNs for all validators
         .with_initial_fullnode_count(10)
         .with_network_tests(vec![&TwoTrafficsTest {
-            inner_tps: 15000,
+            inner_mode: EmitJobMode::ConstTps { tps: 15000 },
             inner_gas_price: aptos_global_constants::GAS_UNIT_PRICE,
             inner_init_gas_price_multiplier: 20,
             // because it is static, cannot use TransactionTypeArg::materialize method
@@ -927,7 +929,7 @@ fn three_region_sim_graceful_overload(config: ForgeConfig) -> ForgeConfig {
         .with_network_tests(vec![&CompositeNetworkTest {
             wrapper: &ThreeRegionSameCloudSimulationTest,
             test: &TwoTrafficsTest {
-                inner_tps: 15000,
+                inner_mode: EmitJobMode::ConstTps { tps: 15000 },
                 inner_gas_price: aptos_global_constants::GAS_UNIT_PRICE,
                 inner_init_gas_price_multiplier: 20,
                 // Cannot use TransactionTypeArg::materialize, as this needs to be static
@@ -1337,18 +1339,46 @@ fn land_blocking_test_suite(duration: Duration) -> ForgeConfig<'static> {
         )
 }
 
-// TODO: Replace land_blocking when performance reaches on par with current land_blocking
-fn land_blocking_three_region_test_suite(duration: Duration) -> ForgeConfig<'static> {
+fn realistic_env_max_throughput_test_suite(duration: Duration) -> ForgeConfig<'static> {
     ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
         .with_initial_fullnode_count(10)
-        .with_network_tests(vec![&ThreeRegionSameCloudSimulationTest])
+        .with_network_tests(vec![&CompositeNetworkTest {
+            wrapper: &MultiRegionNetworkEmulationTest {
+                override_config: None,
+            },
+            test: &CompositeNetworkTest {
+                wrapper: &CpuChaosTest {
+                    override_config: None,
+                },
+                test: &TwoTrafficsTest {
+                    inner_mode: EmitJobMode::MaxLoad {
+                        mempool_backlog: 40000,
+                    },
+                    inner_gas_price: aptos_global_constants::GAS_UNIT_PRICE,
+                    inner_init_gas_price_multiplier: 20,
+                    // because it is static, cannot use TransactionTypeArg::materialize method
+                    inner_transaction_type: TransactionType::CoinTransfer {
+                        invalid_transaction_ratio: 0,
+                        sender_use_account_pool: false,
+                    },
+                    avg_tps: 5000,
+                    latency_thresholds: &[],
+                },
+            },
+        }])
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             // Have single epoch change in land blocking
             helm_values["chain"]["epoch_duration_secs"] = 300.into();
         }))
+        // First start higher gas-fee traffic, to not cause issues with TxnEmitter setup - account creation
+        .with_emit_job(
+            EmitJobRequest::default()
+                .mode(EmitJobMode::ConstTps { tps: 100 })
+                .gas_price(5 * aptos_global_constants::GAS_UNIT_PRICE),
+        )
         .with_success_criteria(
-            SuccessCriteria::new(3500)
+            SuccessCriteria::new(95)
                 .add_no_restarts()
                 .add_wait_for_catchup_s(
                     // Give at least 60s for catchup, give 10% of the run for longer durations.
@@ -1360,6 +1390,8 @@ fn land_blocking_three_region_test_suite(duration: Duration) -> ForgeConfig<'sta
                     // Check that we don't use more than 10 GB of memory for 30% of the time.
                     MetricsThreshold::new(10 * 1024 * 1024 * 1024, 30),
                 ))
+                .add_latency_threshold(4.0, LatencyType::P50)
+                .add_latency_threshold(8.0, LatencyType::P90)
                 .add_chain_progress(StateProgressThreshold {
                     max_no_progress_secs: 10.0,
                     max_round_gap: 4,
@@ -1811,8 +1843,7 @@ impl NetworkTest for EmitTransaction {
             .map(|v| v.peer_id())
             .collect::>();
         let stats = generate_traffic(ctx, &all_validators, duration).unwrap();
-        ctx.report
-            .report_txn_stats(self.name().to_string(), &stats, duration);
+        ctx.report.report_txn_stats(self.name().to_string(), &stats);
 
         Ok(())
     }
diff --git a/testsuite/forge/src/interface/network.rs b/testsuite/forge/src/interface/network.rs
index a6a6dca6b043c..a6f7a94995f7b 100644
--- a/testsuite/forge/src/interface/network.rs
+++ b/testsuite/forge/src/interface/network.rs
@@ -21,7 +21,7 @@ pub trait NetworkTest: Test {
 
 pub struct NetworkContext<'t> {
     core: CoreContext,
-    swarm: &'t mut dyn Swarm,
+    pub swarm: &'t mut dyn Swarm,
     pub report: &'t mut TestReport,
     pub global_duration: Duration,
     pub emit_job: EmitJobRequest,
@@ -70,6 +70,7 @@ impl<'t> NetworkContext<'t> {
             .block_on(SuccessCriteriaChecker::check_for_success(
                 &self.success_criteria,
                 self.swarm,
+                self.report,
                 stats,
                 window,
                 start_time,
diff --git a/testsuite/forge/src/report.rs b/testsuite/forge/src/report.rs
index 4e082f5d8d1c9..b32aa9fb45a6b 100644
--- a/testsuite/forge/src/report.rs
+++ b/testsuite/forge/src/report.rs
@@ -4,7 +4,7 @@
 
 use aptos_transaction_emitter_lib::emitter::stats::TxnStats;
 use serde::Serialize;
-use std::{fmt, time::Duration};
+use std::fmt;
 
 #[derive(Default, Debug, Serialize)]
 pub struct TestReport {
@@ -39,30 +39,16 @@ impl TestReport {
         self.text.push_str(&text);
     }
 
-    pub fn report_txn_stats(&mut self, test_name: String, stats: &TxnStats, window: Duration) {
-        let submitted_txn = stats.submitted;
-        let expired_txn = stats.expired;
-        let avg_tps = stats.committed / window.as_secs();
-        let avg_latency_client = if stats.committed == 0 {
-            0u64
-        } else {
-            stats.latency / stats.committed
-        };
-        let p99_latency = stats.latency_buckets.percentile(99, 100);
-        self.report_metric(test_name.clone(), "submitted_txn", submitted_txn as f64);
-        self.report_metric(test_name.clone(), "expired_txn", expired_txn as f64);
-        self.report_metric(test_name.clone(), "avg_tps", avg_tps as f64);
-        self.report_metric(test_name.clone(), "avg_latency", avg_latency_client as f64);
-        self.report_metric(test_name.clone(), "p99_latency", p99_latency as f64);
-        let expired_text = if expired_txn == 0 {
-            "no expired txns".to_string()
-        } else {
-            format!("(!) expired {} out of {} txns", expired_txn, submitted_txn)
-        };
-        self.report_text(format!(
-            "{} : {:.0} TPS, {:.1} ms latency, {:.1} ms p99 latency,{}",
-            test_name, avg_tps, avg_latency_client, p99_latency, expired_text
-        ));
+    pub fn report_txn_stats(&mut self, test_name: String, stats: &TxnStats) {
+        let rate = stats.rate();
+        self.report_metric(test_name.clone(), "submitted_txn", stats.submitted as f64);
+        self.report_metric(test_name.clone(), "expired_txn", stats.expired as f64);
+        self.report_metric(test_name.clone(), "avg_tps", rate.committed as f64);
+        self.report_metric(test_name.clone(), "avg_latency", rate.latency as f64);
+        self.report_metric(test_name.clone(), "p50_latency", rate.p50_latency as f64);
+        self.report_metric(test_name.clone(), "p90_latency", rate.p90_latency as f64);
+        self.report_metric(test_name.clone(), "p99_latency", rate.p99_latency as f64);
+        self.report_text(format!("{} : {}", test_name, rate));
     }
 
     pub fn print_report(&self) {
diff --git a/testsuite/forge/src/success_criteria.rs b/testsuite/forge/src/success_criteria.rs
index 31516103c364a..c843ff8fb0b0a 100644
--- a/testsuite/forge/src/success_criteria.rs
+++ b/testsuite/forge/src/success_criteria.rs
@@ -1,7 +1,7 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
-use crate::{system_metrics::SystemMetricsThreshold, Swarm, SwarmExt};
+use crate::{system_metrics::SystemMetricsThreshold, Swarm, SwarmExt, TestReport};
 use anyhow::{bail, Context};
 use aptos::node::analyze::fetch_metadata::FetchMetadata;
 use aptos_sdk::types::PeerId;
@@ -78,6 +78,7 @@ impl SuccessCriteriaChecker {
     pub async fn check_for_success(
         success_criteria: &SuccessCriteria,
         swarm: &mut dyn Swarm,
+        report: &mut TestReport,
         stats: &TxnStats,
         window: Duration,
         start_time: i64,
@@ -86,7 +87,7 @@ impl SuccessCriteriaChecker {
         end_version: u64,
     ) -> anyhow::Result<()> {
         println!(
-            "End to end duration: {}s, while txn emitter lasted: {}s",
+            "End to end duration: {}s, performance measured for: {}s",
             window.as_secs(),
             stats.lasted.as_secs()
         );
@@ -131,9 +132,15 @@ impl SuccessCriteriaChecker {
         }
 
         if let Some(chain_progress_threshold) = &success_criteria.chain_progress_check {
-            Self::check_chain_progress(swarm, chain_progress_threshold, start_version, end_version)
-                .await
-                .context("Failed check chain progress")?;
+            Self::check_chain_progress(
+                swarm,
+                report,
+                chain_progress_threshold,
+                start_version,
+                end_version,
+            )
+            .await
+            .context("Failed check chain progress")?;
         }
 
         Ok(())
@@ -141,6 +148,7 @@ impl SuccessCriteriaChecker {
 
     async fn check_chain_progress(
         swarm: &mut dyn Swarm,
+        report: &mut TestReport,
         chain_progress_threshold: &StateProgressThreshold,
         start_version: u64,
         end_version: u64,
@@ -212,28 +220,24 @@ impl SuccessCriteriaChecker {
         }
 
         let max_time_gap_secs = Duration::from_micros(max_time_gap).as_secs_f32();
+
+        let gap_text = format!(
+            "Max round gap was {} [limit {}] at version {}. Max no progress secs was {} [limit {}] at version {}.",
+            max_round_gap,
+            chain_progress_threshold.max_round_gap,
+            max_round_gap_version,
+            max_time_gap_secs,
+            chain_progress_threshold.max_no_progress_secs,
+            max_time_gap_version,
+        );
+
         if max_round_gap > chain_progress_threshold.max_round_gap
             || max_time_gap_secs > chain_progress_threshold.max_no_progress_secs
         {
-            bail!(
-                "Failed chain progress check. Max round gap was {} [limit {}] at version {}. Max no progress secs was {} [limit {}] at version {}.",
-                max_round_gap,
-                chain_progress_threshold.max_round_gap,
-                max_round_gap_version,
-                max_time_gap_secs,
-                chain_progress_threshold.max_no_progress_secs,
-                max_time_gap_version,
-            )
+            bail!("Failed chain progress check. {}", gap_text);
         } else {
-            println!(
-                "Passed progress check. Max round gap was {} [limit {}] at version {}. Max no progress secs was {} [limit {}] at version {}.",
-                max_round_gap,
-                chain_progress_threshold.max_round_gap,
-                max_round_gap_version,
-                max_time_gap_secs,
-                chain_progress_threshold.max_no_progress_secs,
-                max_time_gap_version,
-            )
+            println!("Passed progress check. {}", gap_text);
+            report.report_text(gap_text);
         }
 
         Ok(())
@@ -262,6 +266,13 @@ impl SuccessCriteriaChecker {
                     )
                     .to_string(),
                 );
+            } else {
+                println!(
+                    "{:?} latency is {}s and is within limit of {}s",
+                    latency_type,
+                    latency.as_secs_f32(),
+                    latency_threshold.as_secs_f32()
+                );
             }
         }
         if !failures.is_empty() {
diff --git a/testsuite/testcases/src/compatibility_test.rs b/testsuite/testcases/src/compatibility_test.rs
index 3c2afcc5d116b..c366525c7a59d 100644
--- a/testsuite/testcases/src/compatibility_test.rs
+++ b/testsuite/testcases/src/compatibility_test.rs
@@ -61,11 +61,8 @@ impl NetworkTest for SimpleValidatorUpgrade {
 
         // Generate some traffic
         let txn_stat = generate_traffic(ctx, &all_validators, duration)?;
-        ctx.report.report_txn_stats(
-            format!("{}::liveness-check", self.name()),
-            &txn_stat,
-            duration,
-        );
+        ctx.report
+            .report_txn_stats(format!("{}::liveness-check", self.name()), &txn_stat);
 
         // Update the first Validator
         let msg = format!(
@@ -81,7 +78,6 @@ impl NetworkTest for SimpleValidatorUpgrade {
         ctx.report.report_txn_stats(
             format!("{}::single-validator-upgrade", self.name()),
             &txn_stat,
-            duration,
         );
 
         // Update the rest of the first batch
@@ -98,7 +94,6 @@ impl NetworkTest for SimpleValidatorUpgrade {
         ctx.report.report_txn_stats(
             format!("{}::half-validator-upgrade", self.name()),
             &txn_stat,
-            duration,
         );
 
         ctx.swarm().fork_check()?;
@@ -114,7 +109,6 @@ impl NetworkTest for SimpleValidatorUpgrade {
         ctx.report.report_txn_stats(
             format!("{}::rest-validator-upgrade", self.name()),
             &txn_stat,
-            duration,
         );
 
         let msg = "5. check swarm health".to_string();
diff --git a/testsuite/testcases/src/consensus_reliability_tests.rs b/testsuite/testcases/src/consensus_reliability_tests.rs
index 351dc0598304a..816a5358e8206 100644
--- a/testsuite/testcases/src/consensus_reliability_tests.rs
+++ b/testsuite/testcases/src/consensus_reliability_tests.rs
@@ -7,7 +7,7 @@ use aptos_forge::{
     test_utils::consensus_utils::{
         test_consensus_fault_tolerance, FailPointFailureInjection, NodeState,
     },
-    NetworkContext, NetworkTest, Result, Swarm, SwarmExt, Test,
+    NetworkContext, NetworkTest, Result, Swarm, SwarmExt, Test, TestReport,
 };
 use aptos_logger::{info, warn};
 use rand::Rng;
@@ -51,7 +51,12 @@ impl NetworkLoadTest for ChangingWorkingQuorumTest {
         }
     }
 
-    fn test(&self, swarm: &mut dyn Swarm, duration: Duration) -> Result<()> {
+    fn test(
+        &self,
+        swarm: &mut dyn Swarm,
+        _report: &mut TestReport,
+        duration: Duration,
+    ) -> Result<()> {
         let runtime = Runtime::new().unwrap();
 
         let validators = swarm.get_validator_clients_with_names();
diff --git a/testsuite/testcases/src/framework_upgrade.rs b/testsuite/testcases/src/framework_upgrade.rs
index 7e13a21b8ca93..d0e43222c6374 100644
--- a/testsuite/testcases/src/framework_upgrade.rs
+++ b/testsuite/testcases/src/framework_upgrade.rs
@@ -122,7 +122,6 @@ impl NetworkTest for FrameworkUpgrade {
         ctx.report.report_txn_stats(
             format!("{}::full-framework-upgrade", self.name()),
             &txn_stat,
-            duration,
         );
 
         ctx.swarm().fork_check()?;
diff --git a/testsuite/testcases/src/fullnode_reboot_stress_test.rs b/testsuite/testcases/src/fullnode_reboot_stress_test.rs
index dc8fd6d634bac..ba7a109ae8fc1 100644
--- a/testsuite/testcases/src/fullnode_reboot_stress_test.rs
+++ b/testsuite/testcases/src/fullnode_reboot_stress_test.rs
@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::{LoadDestination, NetworkLoadTest};
-use aptos_forge::{NetworkContext, NetworkTest, Result, Swarm, Test};
+use aptos_forge::{NetworkContext, NetworkTest, Result, Swarm, Test, TestReport};
 use rand::{seq::SliceRandom, thread_rng};
 use std::time::Duration;
 use tokio::{runtime::Runtime, time::Instant};
@@ -20,7 +20,12 @@ impl NetworkLoadTest for FullNodeRebootStressTest {
         Ok(LoadDestination::AllFullnodes)
     }
 
-    fn test(&self, swarm: &mut dyn Swarm, duration: Duration) -> Result<()> {
+    fn test(
+        &self,
+        swarm: &mut dyn Swarm,
+        _report: &mut TestReport,
+        duration: Duration,
+    ) -> Result<()> {
         let start = Instant::now();
         let runtime = Runtime::new().unwrap();
 
diff --git a/testsuite/testcases/src/lib.rs b/testsuite/testcases/src/lib.rs
index 9c5a6209186ac..9a184c887f2ed 100644
--- a/testsuite/testcases/src/lib.rs
+++ b/testsuite/testcases/src/lib.rs
@@ -27,7 +27,7 @@ pub mod validator_reboot_stress_test;
 use anyhow::Context;
 use aptos_forge::{
     EmitJobRequest, NetworkContext, NetworkTest, NodeExt, Result, Swarm, SwarmExt, Test,
-    TxnEmitter, TxnStats, Version,
+    TestReport, TxnEmitter, TxnStats, Version,
 };
 use aptos_logger::info;
 use aptos_sdk::{transaction_builder::TransactionFactory, types::PeerId};
@@ -141,7 +141,12 @@ pub trait NetworkLoadTest: Test {
     // Load is started before this function is called, and stops after this function returns.
     // Expected duration is passed into this function, expecting this function to take that much
     // time to finish. How long this function takes will dictate how long the actual test lasts.
-    fn test(&self, _swarm: &mut dyn Swarm, duration: Duration) -> Result<()> {
+    fn test(
+        &self,
+        _swarm: &mut dyn Swarm,
+        _report: &mut TestReport,
+        duration: Duration,
+    ) -> Result<()> {
         std::thread::sleep(duration);
         Ok(())
     }
@@ -174,7 +179,7 @@ impl NetworkTest for dyn NetworkLoadTest {
                 rng,
             )?;
         ctx.report
-            .report_txn_stats(self.name().to_string(), &txn_stat, actual_test_duration);
+            .report_txn_stats(self.name().to_string(), &txn_stat);
 
         let end_timestamp = SystemTime::now()
             .duration_since(UNIX_EPOCH)
@@ -272,7 +277,7 @@ impl dyn NetworkLoadTest {
             }
             let phase_start = Instant::now();
 
-            self.test(ctx.swarm(), phase_duration)
+            self.test(ctx.swarm, ctx.report, phase_duration)
                 .context("test NetworkLoadTest")?;
             actual_phase_durations.push(phase_start.elapsed());
         }
diff --git a/testsuite/testcases/src/partial_nodes_down_test.rs b/testsuite/testcases/src/partial_nodes_down_test.rs
index 96c7504eedd45..1ba769005f9a4 100644
--- a/testsuite/testcases/src/partial_nodes_down_test.rs
+++ b/testsuite/testcases/src/partial_nodes_down_test.rs
@@ -36,7 +36,7 @@ impl NetworkTest for PartialNodesDown {
         // Generate some traffic
         let txn_stat = generate_traffic(ctx, &up_nodes, duration)?;
         ctx.report
-            .report_txn_stats(self.name().to_string(), &txn_stat, duration);
+            .report_txn_stats(self.name().to_string(), &txn_stat);
         for n in &down_nodes {
             let node = ctx.swarm().validator_mut(*n).unwrap();
             println!("Node {} is going to restart", node.name());
diff --git a/testsuite/testcases/src/quorum_store_onchain_enable_test.rs b/testsuite/testcases/src/quorum_store_onchain_enable_test.rs
index 2946199f9affa..77d08a2d549a5 100644
--- a/testsuite/testcases/src/quorum_store_onchain_enable_test.rs
+++ b/testsuite/testcases/src/quorum_store_onchain_enable_test.rs
@@ -28,6 +28,7 @@ impl NetworkLoadTest for QuorumStoreOnChainEnableTest {
     fn test(
         &self,
         swarm: &mut dyn aptos_forge::Swarm,
+        _report: &mut aptos_forge::TestReport,
         duration: std::time::Duration,
     ) -> anyhow::Result<()> {
         let runtime = Runtime::new().unwrap();
diff --git a/testsuite/testcases/src/two_traffics_test.rs b/testsuite/testcases/src/two_traffics_test.rs
index 8c7b6face4dc5..33445364db473 100644
--- a/testsuite/testcases/src/two_traffics_test.rs
+++ b/testsuite/testcases/src/two_traffics_test.rs
@@ -7,7 +7,8 @@ use crate::{
 use anyhow::{bail, Ok};
 use aptos_forge::{
     success_criteria::{LatencyType, SuccessCriteriaChecker},
-    EmitJobMode, EmitJobRequest, NetworkContext, NetworkTest, Result, Swarm, Test, TransactionType,
+    EmitJobMode, EmitJobRequest, NetworkContext, NetworkTest, Result, Swarm, Test, TestReport,
+    TransactionType,
 };
 use aptos_logger::info;
 use rand::{rngs::OsRng, Rng, SeedableRng};
@@ -16,7 +17,7 @@ use std::time::{Duration, Instant};
 pub struct TwoTrafficsTest {
     // cannot have 'static EmitJobRequest, like below, so need to have inner fields
     // pub inner_emit_job_request: EmitJobRequest,
-    pub inner_tps: usize,
+    pub inner_mode: EmitJobMode,
     pub inner_gas_price: u64,
     pub inner_init_gas_price_multiplier: u64,
     pub inner_transaction_type: TransactionType,
@@ -32,7 +33,12 @@ impl Test for TwoTrafficsTest {
 }
 
 impl NetworkLoadTest for TwoTrafficsTest {
-    fn test(&self, swarm: &mut dyn Swarm, duration: Duration) -> Result<()> {
+    fn test(
+        &self,
+        swarm: &mut dyn Swarm,
+        report: &mut TestReport,
+        duration: Duration,
+    ) -> Result<()> {
         info!(
             "Running TwoTrafficsTest test for duration {}s",
             duration.as_secs_f32()
@@ -44,9 +50,7 @@ impl NetworkLoadTest for TwoTrafficsTest {
         let (emitter, emit_job_request) = create_emitter_and_request(
             swarm,
             EmitJobRequest::default()
-                .mode(EmitJobMode::ConstTps {
-                    tps: self.inner_tps,
-                })
+                .mode(self.inner_mode.clone())
                 .gas_price(self.inner_gas_price)
                 .init_gas_price_multiplier(self.inner_init_gas_price_multiplier)
                 .transaction_type(self.inner_transaction_type),
@@ -84,6 +88,8 @@ impl NetworkLoadTest for TwoTrafficsTest {
             )
         }
 
+        report.report_txn_stats(format!("{}: inner traffic", self.name()), &stats);
+
         SuccessCriteriaChecker::check_latency(
             &self
                 .latency_thresholds
diff --git a/testsuite/testcases/src/validator_join_leave_test.rs b/testsuite/testcases/src/validator_join_leave_test.rs
index 96179f3e74ed8..5e4d79a44ee00 100644
--- a/testsuite/testcases/src/validator_join_leave_test.rs
+++ b/testsuite/testcases/src/validator_join_leave_test.rs
@@ -4,7 +4,8 @@
 use crate::{LoadDestination, NetworkLoadTest};
 use aptos::{account::create::DEFAULT_FUNDED_COINS, test::CliTestFramework};
 use aptos_forge::{
-    reconfig, NetworkContext, NetworkTest, NodeExt, Result, Swarm, SwarmExt, Test, FORGE_KEY_SEED,
+    reconfig, NetworkContext, NetworkTest, NodeExt, Result, Swarm, SwarmExt, Test, TestReport,
+    FORGE_KEY_SEED,
 };
 use aptos_keygen::KeyGen;
 use aptos_logger::info;
@@ -28,7 +29,12 @@ impl NetworkLoadTest for ValidatorJoinLeaveTest {
         Ok(LoadDestination::FullnodesOtherwiseValidators)
     }
 
-    fn test(&self, swarm: &mut dyn Swarm, duration: Duration) -> Result<()> {
+    fn test(
+        &self,
+        swarm: &mut dyn Swarm,
+        _report: &mut TestReport,
+        duration: Duration,
+    ) -> Result<()> {
         // Verify we have at least 7 validators (i.e., 3f+1, where f is 2)
         // so we can lose 2 validators but still make progress.
         let num_validators = swarm.validators().count();
diff --git a/testsuite/testcases/src/validator_reboot_stress_test.rs b/testsuite/testcases/src/validator_reboot_stress_test.rs
index 0842f4ca346f6..8929b8da66e08 100644
--- a/testsuite/testcases/src/validator_reboot_stress_test.rs
+++ b/testsuite/testcases/src/validator_reboot_stress_test.rs
@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::NetworkLoadTest;
-use aptos_forge::{NetworkContext, NetworkTest, Result, Swarm, Test};
+use aptos_forge::{NetworkContext, NetworkTest, Result, Swarm, Test, TestReport};
 use rand::{seq::SliceRandom, thread_rng};
 use std::time::Duration;
 use tokio::{runtime::Runtime, time::Instant};
@@ -20,7 +20,12 @@ impl Test for ValidatorRebootStressTest {
 }
 
 impl NetworkLoadTest for ValidatorRebootStressTest {
-    fn test(&self, swarm: &mut dyn Swarm, duration: Duration) -> Result<()> {
+    fn test(
+        &self,
+        swarm: &mut dyn Swarm,
+        _report: &mut TestReport,
+        duration: Duration,
+    ) -> Result<()> {
         let start = Instant::now();
         let runtime = Runtime::new().unwrap();
 

From 04089c3c1563c54ab3b5d630acd5422d440634c9 Mon Sep 17 00:00:00 2001
From: Guoteng Rao <3603304+grao1991@users.noreply.github.com>
Date: Wed, 7 Jun 2023 15:23:54 -0700
Subject: [PATCH 098/200] [Storage][Pruner] Refactor pruners. (#8532)

---
 storage/aptosdb/src/aptosdb_test.rs           |  19 +-
 storage/aptosdb/src/ledger_db.rs              |  23 ++-
 storage/aptosdb/src/lib.rs                    |  39 ++--
 storage/aptosdb/src/pruner/db_pruner.rs       |   3 -
 .../src/pruner/ledger_pruner_manager.rs       | 152 ++++++++-------
 .../src/pruner/ledger_pruner_worker.rs        |  76 --------
 .../ledger_store/ledger_store_pruner.rs       |   7 +-
 storage/aptosdb/src/pruner/mod.rs             |   4 +-
 storage/aptosdb/src/pruner/pruner_manager.rs  |  20 +-
 storage/aptosdb/src/pruner/pruner_metadata.rs |  22 ---
 storage/aptosdb/src/pruner/pruner_utils.rs    |  43 ++++-
 storage/aptosdb/src/pruner/pruner_worker.rs   | 118 ++++++++++++
 storage/aptosdb/src/pruner/state_kv_pruner.rs |  16 +-
 .../src/pruner/state_kv_pruner_manager.rs     | 164 ++++++++---------
 .../src/pruner/state_kv_pruner_worker.rs      |  76 --------
 .../src/pruner/state_merkle_pruner_manager.rs | 173 +++++++++---------
 .../src/pruner/state_merkle_pruner_worker.rs  |  85 ---------
 storage/aptosdb/src/pruner/state_store/mod.rs |   7 +-
 .../aptosdb/src/pruner/state_store/test.rs    |  49 -----
 .../src/pruner/transaction_store/test.rs      |   4 -
 storage/aptosdb/src/state_kv_db.rs            |   7 +
 storage/aptosdb/src/state_merkle_db.rs        |   7 +
 storage/aptosdb/src/utils/mod.rs              |  17 ++
 .../aptosdb/src/utils/truncation_helper.rs    |  21 +--
 .../backup-cli/src/backup_types/tests.rs      |   5 +
 25 files changed, 494 insertions(+), 663 deletions(-)
 delete mode 100644 storage/aptosdb/src/pruner/ledger_pruner_worker.rs
 delete mode 100644 storage/aptosdb/src/pruner/pruner_metadata.rs
 create mode 100644 storage/aptosdb/src/pruner/pruner_worker.rs
 delete mode 100644 storage/aptosdb/src/pruner/state_kv_pruner_worker.rs
 delete mode 100644 storage/aptosdb/src/pruner/state_merkle_pruner_worker.rs

diff --git a/storage/aptosdb/src/aptosdb_test.rs b/storage/aptosdb/src/aptosdb_test.rs
index 5f345523505c9..02fc5617c7980 100644
--- a/storage/aptosdb/src/aptosdb_test.rs
+++ b/storage/aptosdb/src/aptosdb_test.rs
@@ -122,8 +122,9 @@ fn test_error_if_version_pruned() {
     db.state_store
         .state_db
         .state_merkle_pruner
-        .testonly_update_min_version(5);
-    db.ledger_pruner.testonly_update_min_version(10);
+        .save_min_readable_version(5)
+        .unwrap();
+    db.ledger_pruner.save_min_readable_version(10).unwrap();
     assert_eq!(
         db.error_if_state_merkle_pruned("State", 4)
             .unwrap_err()
@@ -252,15 +253,11 @@ pub fn test_state_merkle_pruning_impl(
         // Prune till the oldest snapshot readable.
         let pruner = &db.state_store.state_db.state_merkle_pruner;
         let epoch_snapshot_pruner = &db.state_store.state_db.epoch_snapshot_pruner;
-        pruner
-            .pruner_worker
-            .set_target_db_version(*snapshots.first().unwrap());
-        epoch_snapshot_pruner
-            .pruner_worker
-            .set_target_db_version(std::cmp::min(
-                *snapshots.first().unwrap(),
-                *epoch_snapshots.first().unwrap_or(&Version::MAX),
-            ));
+        pruner.set_worker_target_version(*snapshots.first().unwrap());
+        epoch_snapshot_pruner.set_worker_target_version(std::cmp::min(
+            *snapshots.first().unwrap(),
+            *epoch_snapshots.first().unwrap_or(&Version::MAX),
+        ));
         pruner.wait_for_pruner().unwrap();
         epoch_snapshot_pruner.wait_for_pruner().unwrap();
 
diff --git a/storage/aptosdb/src/ledger_db.rs b/storage/aptosdb/src/ledger_db.rs
index f3719a23fd7cc..658d05d3f1bfb 100644
--- a/storage/aptosdb/src/ledger_db.rs
+++ b/storage/aptosdb/src/ledger_db.rs
@@ -4,18 +4,22 @@
 #![forbid(unsafe_code)]
 #![allow(dead_code)]
 
-use crate::db_options::{
-    event_db_column_families, gen_event_cfds, gen_ledger_cfds, gen_ledger_metadata_cfds,
-    gen_transaction_accumulator_cfds, gen_transaction_cfds, gen_transaction_info_cfds,
-    gen_write_set_cfds, ledger_db_column_families, ledger_metadata_db_column_families,
-    transaction_accumulator_db_column_families, transaction_db_column_families,
-    transaction_info_db_column_families, write_set_db_column_families,
+use crate::{
+    db_options::{
+        event_db_column_families, gen_event_cfds, gen_ledger_cfds, gen_ledger_metadata_cfds,
+        gen_transaction_accumulator_cfds, gen_transaction_cfds, gen_transaction_info_cfds,
+        gen_write_set_cfds, ledger_db_column_families, ledger_metadata_db_column_families,
+        transaction_accumulator_db_column_families, transaction_db_column_families,
+        transaction_info_db_column_families, write_set_db_column_families,
+    },
+    schema::db_metadata::{DbMetadataKey, DbMetadataSchema, DbMetadataValue},
 };
 use anyhow::Result;
 use aptos_config::config::{RocksdbConfig, RocksdbConfigs};
 use aptos_logger::prelude::info;
 use aptos_rocksdb_options::gen_rocksdb_options;
 use aptos_schemadb::{ColumnFamilyDescriptor, ColumnFamilyName, DB};
+use aptos_types::transaction::Version;
 use std::{
     path::{Path, PathBuf},
     sync::Arc,
@@ -136,6 +140,13 @@ impl LedgerDb {
         todo!()
     }
 
+    pub(crate) fn write_pruner_progress(&self, version: Version) -> Result<()> {
+        self.ledger_metadata_db.put::(
+            &DbMetadataKey::LedgerPrunerProgress,
+            &DbMetadataValue::Version(version),
+        )
+    }
+
     pub fn metadata_db(&self) -> &DB {
         &self.ledger_metadata_db
     }
diff --git a/storage/aptosdb/src/lib.rs b/storage/aptosdb/src/lib.rs
index e763678e080c7..633f86885b7ee 100644
--- a/storage/aptosdb/src/lib.rs
+++ b/storage/aptosdb/src/lib.rs
@@ -54,9 +54,8 @@ use crate::{
         OTHER_TIMERS_SECONDS, ROCKSDB_PROPERTIES,
     },
     pruner::{
-        db_pruner::DBPruner, ledger_pruner_manager::LedgerPrunerManager,
-        pruner_manager::PrunerManager, pruner_utils, state_kv_pruner::StateKvPruner,
-        state_kv_pruner_manager::StateKvPrunerManager,
+        ledger_pruner_manager::LedgerPrunerManager, pruner_manager::PrunerManager, pruner_utils,
+        state_kv_pruner::StateKvPruner, state_kv_pruner_manager::StateKvPrunerManager,
         state_merkle_pruner_manager::StateMerklePrunerManager, state_store::StateMerklePruner,
     },
     schema::*,
@@ -2114,34 +2113,17 @@ impl DbWriter for AptosDB {
                 &DbMetadataValue::Version(version),
             )?;
 
-            self.ledger_pruner
-                .pruner()
-                .save_min_readable_version(version, &batch)?;
-
             let mut state_merkle_batch = SchemaBatch::new();
             StateMerklePruner::prune_genesis(
                 self.state_merkle_db.clone(),
                 &mut state_merkle_batch,
             )?;
 
-            self.state_store
-                .state_merkle_pruner
-                .pruner()
-                .save_min_readable_version(version, &state_merkle_batch)?;
-            self.state_store
-                .epoch_snapshot_pruner
-                .pruner()
-                .save_min_readable_version(version, &state_merkle_batch)?;
-
             let mut state_kv_batch = SchemaBatch::new();
             StateKvPruner::prune_genesis(
                 self.state_store.state_kv_db.clone(),
                 &mut state_kv_batch,
             )?;
-            self.state_store
-                .state_kv_pruner
-                .pruner()
-                .save_min_readable_version(version, &state_kv_batch)?;
 
             // Apply the change set writes to the database (atomically) and update in-memory state
             //
@@ -2154,18 +2136,19 @@ impl DbWriter for AptosDB {
                 .commit_nonsharded(version, state_kv_batch)?;
             self.ledger_db.metadata_db_arc().write_schemas(batch)?;
 
-            restore_utils::update_latest_ledger_info(self.ledger_store.clone(), ledger_infos)?;
-            self.state_store.reset();
-
-            self.ledger_pruner.pruner().record_progress(version);
+            self.ledger_pruner.save_min_readable_version(version)?;
             self.state_store
                 .state_merkle_pruner
-                .pruner()
-                .record_progress(version);
+                .save_min_readable_version(version)?;
             self.state_store
                 .epoch_snapshot_pruner
-                .pruner()
-                .record_progress(version);
+                .save_min_readable_version(version)?;
+            self.state_store
+                .state_kv_pruner
+                .save_min_readable_version(version)?;
+
+            restore_utils::update_latest_ledger_info(self.ledger_store.clone(), ledger_infos)?;
+            self.state_store.reset();
 
             Ok(())
         })
diff --git a/storage/aptosdb/src/pruner/db_pruner.rs b/storage/aptosdb/src/pruner/db_pruner.rs
index 80d4b47595cf4..b55bbeac145a9 100644
--- a/storage/aptosdb/src/pruner/db_pruner.rs
+++ b/storage/aptosdb/src/pruner/db_pruner.rs
@@ -61,7 +61,4 @@ pub trait DBPruner: Send + Sync {
     fn is_pruning_pending(&self) -> bool {
         self.target_version() > self.min_readable_version()
     }
-
-    /// (For tests only.) Updates the minimal readable version kept by pruner.
-    fn testonly_update_min_version(&self, version: Version);
 }
diff --git a/storage/aptosdb/src/pruner/ledger_pruner_manager.rs b/storage/aptosdb/src/pruner/ledger_pruner_manager.rs
index 5488f20fbb4dd..8e9a44eb5c508 100644
--- a/storage/aptosdb/src/pruner/ledger_pruner_manager.rs
+++ b/storage/aptosdb/src/pruner/ledger_pruner_manager.rs
@@ -3,53 +3,42 @@
 
 use crate::{
     ledger_db::LedgerDb,
-    metrics::{PRUNER_BATCH_SIZE, PRUNER_WINDOW},
+    metrics::{PRUNER_BATCH_SIZE, PRUNER_VERSIONS, PRUNER_WINDOW},
     pruner::{
-        db_pruner::DBPruner, ledger_pruner_worker::LedgerPrunerWorker,
         ledger_store::ledger_store_pruner::LedgerPruner, pruner_manager::PrunerManager,
+        pruner_worker::PrunerWorker,
     },
     pruner_utils,
 };
+use anyhow::Result;
 use aptos_config::config::LedgerPrunerConfig;
 use aptos_infallible::Mutex;
-use aptos_types::transaction::Version;
-use std::{sync::Arc, thread::JoinHandle};
+use aptos_types::transaction::{AtomicVersion, Version};
+use std::sync::{atomic::Ordering, Arc};
 
 /// The `PrunerManager` for `LedgerPruner`.
 pub(crate) struct LedgerPrunerManager {
-    pruner_enabled: bool,
+    ledger_db: Arc,
     /// DB version window, which dictates how many version of other stores like transaction, ledger
     /// info, events etc to keep.
     prune_window: Version,
-    /// Ledger pruner. Is always initialized regardless if the pruner is enabled to keep tracks
-    /// of the min_readable_version.
-    pruner: Arc,
-    /// Wrapper class of the ledger pruner.
-    pruner_worker: Arc,
-    /// The worker thread handle for ledger_pruner, created upon Pruner instance construction and
-    /// joined upon its destruction. It is `None` when the ledger pruner is not enabled or it only
-    /// becomes `None` after joined in `drop()`.
-    worker_thread: Option>,
-    /// We send a batch of version to the underlying pruners for performance reason. This tracks the
-    /// last version we sent to the pruners. Will only be set if the pruner is enabled.
-    pub(crate) last_version_sent_to_pruner: Arc>,
+    /// It is None iff the pruner is not enabled.
+    pruner_worker: Option,
     /// Ideal batch size of the versions to be sent to the ledger pruner
     pruning_batch_size: usize,
     /// latest version
     latest_version: Arc>,
     /// Offset for displaying to users
     user_pruning_window_offset: u64,
+    /// The minimal readable version for the ledger data.
+    min_readable_version: AtomicVersion,
 }
 
 impl PrunerManager for LedgerPrunerManager {
     type Pruner = LedgerPruner;
 
-    fn pruner(&self) -> &Self::Pruner {
-        &self.pruner
-    }
-
     fn is_pruner_enabled(&self) -> bool {
-        self.pruner_enabled
+        self.pruner_worker.is_some()
     }
 
     fn get_prune_window(&self) -> Version {
@@ -57,7 +46,7 @@ impl PrunerManager for LedgerPrunerManager {
     }
 
     fn get_min_readable_version(&self) -> Version {
-        self.pruner.as_ref().min_readable_version()
+        self.min_readable_version.load(Ordering::SeqCst)
     }
 
     fn get_min_viable_version(&self) -> Version {
@@ -77,91 +66,98 @@ impl PrunerManager for LedgerPrunerManager {
     fn maybe_set_pruner_target_db_version(&self, latest_version: Version) {
         *self.latest_version.lock() = latest_version;
 
+        let min_readable_version = self.get_min_readable_version();
         // Only wake up the ledger pruner if there are `ledger_pruner_pruning_batch_size` pending
         // versions.
-        if self.pruner_enabled
+        if self.is_pruner_enabled()
             && latest_version
-                >= *self.last_version_sent_to_pruner.as_ref().lock()
-                    + self.pruning_batch_size as u64
+                >= min_readable_version + self.pruning_batch_size as u64 + self.prune_window
         {
             self.set_pruner_target_db_version(latest_version);
-            *self.last_version_sent_to_pruner.as_ref().lock() = latest_version;
         }
     }
 
-    fn set_pruner_target_db_version(&self, latest_version: Version) {
-        assert!(self.pruner_enabled);
+    fn save_min_readable_version(&self, min_readable_version: Version) -> Result<()> {
+        self.min_readable_version
+            .store(min_readable_version, Ordering::SeqCst);
+
+        PRUNER_VERSIONS
+            .with_label_values(&["ledger_pruner", "min_readable"])
+            .set(min_readable_version as i64);
+
+        self.ledger_db.write_pruner_progress(min_readable_version)
+    }
+
+    fn is_pruning_pending(&self) -> bool {
         self.pruner_worker
             .as_ref()
-            .set_target_db_version(latest_version.saturating_sub(self.prune_window));
+            .map_or(false, |w| w.is_pruning_pending())
+    }
+
+    #[cfg(test)]
+    fn set_worker_target_version(&self, target_version: Version) {
+        self.pruner_worker
+            .as_ref()
+            .unwrap()
+            .set_target_db_version(target_version);
     }
 }
 
 impl LedgerPrunerManager {
     /// Creates a worker thread that waits on a channel for pruning commands.
     pub fn new(ledger_db: Arc, ledger_pruner_config: LedgerPrunerConfig) -> Self {
-        let ledger_pruner = pruner_utils::create_ledger_pruner(ledger_db);
-
-        if ledger_pruner_config.enable {
-            PRUNER_WINDOW
-                .with_label_values(&["ledger_pruner"])
-                .set(ledger_pruner_config.prune_window as i64);
-
-            PRUNER_BATCH_SIZE
-                .with_label_values(&["ledger_pruner"])
-                .set(ledger_pruner_config.batch_size as i64);
-        }
-
-        let ledger_pruner_worker = Arc::new(LedgerPrunerWorker::new(
-            Arc::clone(&ledger_pruner),
-            ledger_pruner_config,
-        ));
-
-        let ledger_pruner_worker_clone = Arc::clone(&ledger_pruner_worker);
-
-        let ledger_pruner_worker_thread = if ledger_pruner_config.enable {
-            Some(
-                std::thread::Builder::new()
-                    .name("aptosdb_ledger_pruner".into())
-                    .spawn(move || ledger_pruner_worker_clone.as_ref().work())
-                    .expect("Creating ledger pruner thread should succeed."),
-            )
+        let pruner_worker = if ledger_pruner_config.enable {
+            Some(Self::init_pruner(
+                Arc::clone(&ledger_db),
+                ledger_pruner_config,
+            ))
         } else {
             None
         };
 
-        let min_readable_version = ledger_pruner.min_readable_version();
+        let min_readable_version =
+            pruner_utils::get_ledger_pruner_progress(&ledger_db).expect("Must succeed.");
+
+        PRUNER_VERSIONS
+            .with_label_values(&["ledger_pruner", "min_readable"])
+            .set(min_readable_version as i64);
 
         Self {
-            pruner_enabled: ledger_pruner_config.enable,
+            ledger_db,
             prune_window: ledger_pruner_config.prune_window,
-            pruner: ledger_pruner,
-            pruner_worker: ledger_pruner_worker,
-            worker_thread: ledger_pruner_worker_thread,
-            last_version_sent_to_pruner: Arc::new(Mutex::new(min_readable_version)),
+            pruner_worker,
             pruning_batch_size: ledger_pruner_config.batch_size,
             latest_version: Arc::new(Mutex::new(min_readable_version)),
             user_pruning_window_offset: ledger_pruner_config.user_pruning_window_offset,
+            min_readable_version: AtomicVersion::new(min_readable_version),
         }
     }
 
-    #[cfg(test)]
-    pub fn testonly_update_min_version(&self, version: Version) {
-        self.pruner.testonly_update_min_version(version);
+    fn init_pruner(
+        ledger_db: Arc,
+        ledger_pruner_config: LedgerPrunerConfig,
+    ) -> PrunerWorker {
+        let pruner = pruner_utils::create_ledger_pruner(ledger_db);
+
+        PRUNER_WINDOW
+            .with_label_values(&["ledger_pruner"])
+            .set(ledger_pruner_config.prune_window as i64);
+
+        PRUNER_BATCH_SIZE
+            .with_label_values(&["ledger_pruner"])
+            .set(ledger_pruner_config.batch_size as i64);
+
+        PrunerWorker::new(pruner, ledger_pruner_config.batch_size, "ledger")
     }
-}
 
-impl Drop for LedgerPrunerManager {
-    fn drop(&mut self) {
-        if self.pruner_enabled {
-            self.pruner_worker.stop_pruning();
-
-            assert!(self.worker_thread.is_some());
-            self.worker_thread
-                .take()
-                .expect("Ledger pruner worker thread must exist.")
-                .join()
-                .expect("Ledger pruner worker thread should join peacefully.");
-        }
+    fn set_pruner_target_db_version(&self, latest_version: Version) {
+        assert!(self.pruner_worker.is_some());
+        let min_readable_version = latest_version.saturating_sub(self.prune_window);
+        self.min_readable_version
+            .store(min_readable_version, Ordering::SeqCst);
+        self.pruner_worker
+            .as_ref()
+            .unwrap()
+            .set_target_db_version(min_readable_version);
     }
 }
diff --git a/storage/aptosdb/src/pruner/ledger_pruner_worker.rs b/storage/aptosdb/src/pruner/ledger_pruner_worker.rs
deleted file mode 100644
index 46aa204013a2f..0000000000000
--- a/storage/aptosdb/src/pruner/ledger_pruner_worker.rs
+++ /dev/null
@@ -1,76 +0,0 @@
-// Copyright © Aptos Foundation
-// SPDX-License-Identifier: Apache-2.0
-use crate::pruner::{db_pruner::DBPruner, ledger_store::ledger_store_pruner::LedgerPruner};
-use aptos_config::config::LedgerPrunerConfig;
-use aptos_logger::{
-    error,
-    prelude::{sample, SampleRate},
-};
-use aptos_types::transaction::Version;
-use std::{
-    sync::{
-        atomic::{AtomicBool, Ordering},
-        Arc,
-    },
-    thread::sleep,
-    time::Duration,
-};
-
-/// Maintains the ledger pruner and periodically calls the db_pruner's prune method to prune the DB.
-/// This also exposes API to report the progress to the parent thread.
-pub struct LedgerPrunerWorker {
-    /// The worker will sleep for this period of time after pruning each batch.
-    pruning_time_interval_in_ms: u64,
-    /// Ledger pruner.
-    pruner: Arc,
-    /// Max items to prune per batch. For the ledger pruner, this means the max versions to prune
-    /// and for the state pruner, this means the max stale nodes to prune.
-    max_versions_to_prune_per_batch: u64,
-    /// Indicates whether the pruning loop should be running. Will only be set to true on pruner
-    /// destruction.
-    quit_worker: AtomicBool,
-}
-
-impl LedgerPrunerWorker {
-    pub(crate) fn new(
-        ledger_pruner: Arc,
-        ledger_pruner_config: LedgerPrunerConfig,
-    ) -> Self {
-        Self {
-            pruning_time_interval_in_ms: if cfg!(test) { 100 } else { 1 },
-            pruner: ledger_pruner,
-            max_versions_to_prune_per_batch: ledger_pruner_config.batch_size as u64,
-            quit_worker: AtomicBool::new(false),
-        }
-    }
-
-    // Loop that does the real pruning job.
-    pub(crate) fn work(&self) {
-        while !self.quit_worker.load(Ordering::Relaxed) {
-            let pruner_result = self
-                .pruner
-                .prune(self.max_versions_to_prune_per_batch as usize);
-            if pruner_result.is_err() {
-                sample!(
-                    SampleRate::Duration(Duration::from_secs(1)),
-                    error!(error = ?pruner_result.err().unwrap(),
-                        "Ledger pruner has error.")
-                );
-                sleep(Duration::from_millis(self.pruning_time_interval_in_ms));
-                return;
-            }
-            if !self.pruner.is_pruning_pending() {
-                sleep(Duration::from_millis(self.pruning_time_interval_in_ms));
-            }
-        }
-    }
-
-    pub fn set_target_db_version(&self, target_db_version: Version) {
-        assert!(target_db_version >= self.pruner.target_version());
-        self.pruner.set_target_version(target_db_version);
-    }
-
-    pub fn stop_pruning(&self) {
-        self.quit_worker.store(true, Ordering::Relaxed);
-    }
-}
diff --git a/storage/aptosdb/src/pruner/ledger_store/ledger_store_pruner.rs b/storage/aptosdb/src/pruner/ledger_store/ledger_store_pruner.rs
index bc92e4a82f332..a4f6653cace6d 100644
--- a/storage/aptosdb/src/pruner/ledger_store/ledger_store_pruner.rs
+++ b/storage/aptosdb/src/pruner/ledger_store/ledger_store_pruner.rs
@@ -124,14 +124,9 @@ impl DBPruner for LedgerPruner {
         self.min_readable_version
             .store(min_readable_version, Ordering::Relaxed);
         PRUNER_VERSIONS
-            .with_label_values(&["ledger_pruner", "min_readable"])
+            .with_label_values(&["ledger_pruner", "progress"])
             .set(min_readable_version as i64);
     }
-
-    /// (For tests only.) Updates the minimal readable version kept by pruner.
-    fn testonly_update_min_version(&self, version: Version) {
-        self.min_readable_version.store(version, Ordering::Relaxed)
-    }
 }
 
 impl LedgerPruner {
diff --git a/storage/aptosdb/src/pruner/mod.rs b/storage/aptosdb/src/pruner/mod.rs
index c09e264e6ab33..51393f7fcbd20 100644
--- a/storage/aptosdb/src/pruner/mod.rs
+++ b/storage/aptosdb/src/pruner/mod.rs
@@ -5,13 +5,11 @@
 pub(crate) mod db_pruner;
 pub(crate) mod db_sub_pruner;
 pub(crate) mod event_store;
-pub(crate) mod ledger_pruner_worker;
 pub(crate) mod ledger_store;
 pub(crate) mod pruner_manager;
 pub mod pruner_utils;
+pub(crate) mod pruner_worker;
 pub(crate) mod state_kv_pruner;
-pub(crate) mod state_kv_pruner_worker;
-pub(crate) mod state_merkle_pruner_worker;
 pub(crate) mod state_store;
 pub(crate) mod transaction_store;
 
diff --git a/storage/aptosdb/src/pruner/pruner_manager.rs b/storage/aptosdb/src/pruner/pruner_manager.rs
index 58f26a6a05775..3ba5d94692a44 100644
--- a/storage/aptosdb/src/pruner/pruner_manager.rs
+++ b/storage/aptosdb/src/pruner/pruner_manager.rs
@@ -10,8 +10,9 @@ use aptos_types::transaction::Version;
 /// The `PrunerManager` is meant to be part of a `AptosDB` instance and runs in the background to
 /// prune old data.
 ///
-/// It creates a worker thread on construction and joins it on destruction. When destructed, it
-/// quits the worker thread eagerly without waiting for all pending work to be done.
+/// If the pruner is enabled. It creates a worker thread on construction and joins it on
+/// destruction. When destructed, it quits the worker thread eagerly without waiting for
+/// all pending work to be done.
 pub trait PrunerManager: Sync {
     type Pruner: DBPruner;
 
@@ -19,16 +20,20 @@ pub trait PrunerManager: Sync {
 
     fn get_prune_window(&self) -> Version;
 
-    fn get_min_viable_version(&self) -> Version;
+    fn get_min_viable_version(&self) -> Version {
+        unimplemented!()
+    }
 
     fn get_min_readable_version(&self) -> Version;
 
     /// Sets pruner target version when necessary.
     fn maybe_set_pruner_target_db_version(&self, latest_version: Version);
 
-    fn set_pruner_target_db_version(&self, latest_version: Version);
+    // Only used at the end of fast sync to store the min_readable_version to db and update the
+    // in memory progress.
+    fn save_min_readable_version(&self, min_readable_version: Version) -> anyhow::Result<()>;
 
-    fn pruner(&self) -> &Self::Pruner;
+    fn is_pruning_pending(&self) -> bool;
 
     /// (For tests only.) Notifies the worker thread and waits for it to finish its job by polling
     /// an internal counter.
@@ -54,11 +59,14 @@ pub trait PrunerManager: Sync {
         let end = Instant::now() + TIMEOUT;
 
         while Instant::now() < end {
-            if !self.pruner().is_pruning_pending() {
+            if !self.is_pruning_pending() {
                 return Ok(());
             }
             sleep(Duration::from_millis(1));
         }
         anyhow::bail!("Timeout waiting for pruner worker.");
     }
+
+    #[cfg(test)]
+    fn set_worker_target_version(&self, target_version: Version);
 }
diff --git a/storage/aptosdb/src/pruner/pruner_metadata.rs b/storage/aptosdb/src/pruner/pruner_metadata.rs
deleted file mode 100644
index f38e0f6abc0d0..0000000000000
--- a/storage/aptosdb/src/pruner/pruner_metadata.rs
+++ /dev/null
@@ -1,22 +0,0 @@
-// Copyright © Aptos Foundation
-// SPDX-License-Identifier: Apache-2.0
-
-use aptos_types::transaction::Version;
-use num_derive::FromPrimitive;
-use num_derive::ToPrimitive;
-use serde::{Deserialize, Serialize};
-
-#[derive(Clone, Debug, Deserialize, PartialEq, Eq, Serialize)]
-#[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
-pub(crate) enum PrunerMetadata {
-    LatestVersion(Version),
-}
-
-#[derive(Clone, Debug, Deserialize, FromPrimitive, PartialEq, Eq, ToPrimitive, Serialize)]
-#[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
-#[repr(u8)]
-pub enum PrunerTag {
-    LedgerPruner = 0,
-    StateMerklePruner = 1,
-    EpochEndingStateMerklePruner = 2,
-}
diff --git a/storage/aptosdb/src/pruner/pruner_utils.rs b/storage/aptosdb/src/pruner/pruner_utils.rs
index 5575962f2f80f..581a9672182eb 100644
--- a/storage/aptosdb/src/pruner/pruner_utils.rs
+++ b/storage/aptosdb/src/pruner/pruner_utils.rs
@@ -10,12 +10,16 @@ use crate::{
         state_kv_pruner::StateKvPruner,
         state_store::{generics::StaleNodeIndexSchemaTrait, StateMerklePruner},
     },
+    schema::{db_metadata::DbMetadataKey, version_data::VersionDataSchema},
     state_kv_db::StateKvDb,
     state_merkle_db::StateMerkleDb,
+    utils::get_progress,
     EventStore, TransactionStore,
 };
+use anyhow::Result;
 use aptos_jellyfish_merkle::StaleNodeIndex;
-use aptos_schemadb::schema::KeyCodec;
+use aptos_schemadb::{schema::KeyCodec, ReadOptions};
+use aptos_types::transaction::Version;
 use std::sync::Arc;
 
 /// A utility function to instantiate the state pruner
@@ -41,3 +45,40 @@ pub(crate) fn create_ledger_pruner(ledger_db: Arc) -> Arc) -> Arc {
     Arc::new(StateKvPruner::new(state_kv_db))
 }
+
+pub(crate) fn get_ledger_pruner_progress(ledger_db: &LedgerDb) -> Result {
+    Ok(
+        if let Some(version) = get_progress(
+            ledger_db.metadata_db(),
+            &DbMetadataKey::LedgerPrunerProgress,
+        )? {
+            version
+        } else {
+            let mut iter = ledger_db
+                .metadata_db()
+                .iter::(ReadOptions::default())?;
+            iter.seek_to_first();
+            match iter.next().transpose()? {
+                Some((version, _)) => version,
+                None => 0,
+            }
+        },
+    )
+}
+
+pub(crate) fn get_state_kv_pruner_progress(state_kv_db: &StateKvDb) -> Result {
+    Ok(get_progress(
+        state_kv_db.metadata_db(),
+        &DbMetadataKey::StateKvPrunerProgress,
+    )?
+    .unwrap_or(0))
+}
+
+pub(crate) fn get_state_merkle_pruner_progress(
+    state_merkle_db: &StateMerkleDb,
+) -> Result
+where
+    StaleNodeIndex: KeyCodec,
+{
+    Ok(get_progress(state_merkle_db.metadata_db(), &S::tag())?.unwrap_or(0))
+}
diff --git a/storage/aptosdb/src/pruner/pruner_worker.rs b/storage/aptosdb/src/pruner/pruner_worker.rs
new file mode 100644
index 0000000000000..954758b87e390
--- /dev/null
+++ b/storage/aptosdb/src/pruner/pruner_worker.rs
@@ -0,0 +1,118 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::pruner::db_pruner::DBPruner;
+use aptos_logger::{
+    error,
+    prelude::{sample, SampleRate},
+};
+use aptos_types::transaction::Version;
+use std::{
+    sync::{
+        atomic::{AtomicBool, Ordering},
+        Arc,
+    },
+    thread::{sleep, JoinHandle},
+    time::Duration,
+};
+
+/// Maintains the pruner and periodically calls the db_pruner's prune method to prune the DB.
+/// This also exposes API to report the progress to the parent thread.
+pub struct PrunerWorker {
+    // The name of the worker.
+    worker_name: String,
+    /// The thread to run pruner.
+    worker_thread: Option>,
+
+    inner: Arc,
+}
+
+pub struct PrunerWorkerInner {
+    /// The worker will sleep for this period of time after pruning each batch.
+    pruning_time_interval_in_ms: u64,
+    /// The pruner.
+    pruner: Arc,
+    /// A threshold to control how many items we prune for each batch.
+    batch_size: usize,
+    /// Indicates whether the pruning loop should be running. Will only be set to true on pruner
+    /// destruction.
+    quit_worker: AtomicBool,
+}
+
+impl PrunerWorkerInner {
+    fn new(pruner: Arc, batch_size: usize) -> Arc {
+        Arc::new(Self {
+            pruning_time_interval_in_ms: if cfg!(test) { 100 } else { 1 },
+            pruner,
+            batch_size,
+            quit_worker: AtomicBool::new(false),
+        })
+    }
+
+    // Loop that does the real pruning job.
+    fn work(&self) {
+        while !self.quit_worker.load(Ordering::SeqCst) {
+            let pruner_result = self.pruner.prune(self.batch_size);
+            if pruner_result.is_err() {
+                sample!(
+                    SampleRate::Duration(Duration::from_secs(1)),
+                    error!(error = ?pruner_result.err().unwrap(),
+                        "Pruner has error.")
+                );
+                sleep(Duration::from_millis(self.pruning_time_interval_in_ms));
+                continue;
+            }
+            if !self.pruner.is_pruning_pending() {
+                sleep(Duration::from_millis(self.pruning_time_interval_in_ms));
+            }
+        }
+    }
+
+    fn stop_pruning(&self) {
+        self.quit_worker.store(true, Ordering::SeqCst);
+    }
+}
+
+impl PrunerWorker {
+    pub(crate) fn new(pruner: Arc, batch_size: usize, name: &str) -> Self {
+        let inner = PrunerWorkerInner::new(pruner, batch_size);
+        let inner_cloned = Arc::clone(&inner);
+
+        let worker_thread = std::thread::Builder::new()
+            .name(format!("{name}_pruner"))
+            .spawn(move || inner_cloned.work())
+            .expect("Creating pruner thread should succeed.");
+
+        Self {
+            worker_name: name.into(),
+            worker_thread: Some(worker_thread),
+            inner,
+        }
+    }
+
+    pub fn set_target_db_version(&self, target_db_version: Version) {
+        if target_db_version > self.inner.pruner.target_version() {
+            self.inner.pruner.set_target_version(target_db_version);
+        }
+    }
+
+    pub fn is_pruning_pending(&self) -> bool {
+        self.inner.pruner.is_pruning_pending()
+    }
+}
+
+impl Drop for PrunerWorker {
+    fn drop(&mut self) {
+        self.inner.stop_pruning();
+        self.worker_thread
+            .take()
+            .unwrap_or_else(|| panic!("Pruner worker ({}) thread must exist.", self.worker_name))
+            .join()
+            .unwrap_or_else(|e| {
+                panic!(
+                    "Pruner worker ({}) thread should join peacefully: {e:?}",
+                    self.worker_name
+                )
+            });
+    }
+}
diff --git a/storage/aptosdb/src/pruner/state_kv_pruner.rs b/storage/aptosdb/src/pruner/state_kv_pruner.rs
index ec8dfc160df49..460caf5db06e3 100644
--- a/storage/aptosdb/src/pruner/state_kv_pruner.rs
+++ b/storage/aptosdb/src/pruner/state_kv_pruner.rs
@@ -12,6 +12,7 @@ use crate::{
     schema::db_metadata::{DbMetadataKey, DbMetadataValue},
     state_kv_db::StateKvDb,
 };
+use anyhow::Result;
 use aptos_schemadb::SchemaBatch;
 use aptos_types::transaction::{AtomicVersion, Version};
 use std::sync::{atomic::Ordering, Arc};
@@ -32,7 +33,7 @@ impl DBPruner for StateKvPruner {
         STATE_KV_PRUNER_NAME
     }
 
-    fn prune(&self, max_versions: usize) -> anyhow::Result {
+    fn prune(&self, max_versions: usize) -> Result {
         if !self.is_pruning_pending() {
             return Ok(self.min_readable_version());
         }
@@ -46,11 +47,7 @@ impl DBPruner for StateKvPruner {
         Ok(current_target_version)
     }
 
-    fn save_min_readable_version(
-        &self,
-        version: Version,
-        batch: &SchemaBatch,
-    ) -> anyhow::Result<()> {
+    fn save_min_readable_version(&self, version: Version, batch: &SchemaBatch) -> Result<()> {
         batch.put::(
             &DbMetadataKey::StateKvPrunerProgress,
             &DbMetadataValue::Version(version),
@@ -84,14 +81,9 @@ impl DBPruner for StateKvPruner {
         self.min_readable_version
             .store(min_readable_version, Ordering::Relaxed);
         PRUNER_VERSIONS
-            .with_label_values(&["state_kv_pruner", "min_readable"])
+            .with_label_values(&["state_kv_pruner", "progress"])
             .set(min_readable_version as i64);
     }
-
-    /// (For tests only.) Updates the minimal readable version kept by pruner.
-    fn testonly_update_min_version(&self, version: Version) {
-        self.min_readable_version.store(version, Ordering::Relaxed)
-    }
 }
 
 impl StateKvPruner {
diff --git a/storage/aptosdb/src/pruner/state_kv_pruner_manager.rs b/storage/aptosdb/src/pruner/state_kv_pruner_manager.rs
index 744269b2422fc..936da9eb0cc9f 100644
--- a/storage/aptosdb/src/pruner/state_kv_pruner_manager.rs
+++ b/storage/aptosdb/src/pruner/state_kv_pruner_manager.rs
@@ -2,51 +2,36 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::{
-    metrics::{PRUNER_BATCH_SIZE, PRUNER_WINDOW},
+    metrics::{PRUNER_BATCH_SIZE, PRUNER_VERSIONS, PRUNER_WINDOW},
     pruner::{
-        db_pruner::DBPruner, pruner_manager::PrunerManager, state_kv_pruner::StateKvPruner,
-        state_kv_pruner_worker::StateKvPrunerWorker,
+        pruner_manager::PrunerManager, pruner_worker::PrunerWorker, state_kv_pruner::StateKvPruner,
     },
     pruner_utils,
     state_kv_db::StateKvDb,
 };
+use anyhow::Result;
 use aptos_config::config::LedgerPrunerConfig;
-use aptos_infallible::Mutex;
-use aptos_types::transaction::Version;
-use std::{sync::Arc, thread::JoinHandle};
+use aptos_types::transaction::{AtomicVersion, Version};
+use std::sync::{atomic::Ordering, Arc};
 
 /// The `PrunerManager` for `StateKvPruner`.
 pub(crate) struct StateKvPrunerManager {
-    pruner_enabled: bool,
+    state_kv_db: Arc,
     /// DB version window, which dictates how many version of state values to keep.
     prune_window: Version,
-    /// State kv pruner. Is always initialized regardless if the pruner is enabled to keep tracks
-    /// of the min_readable_version.
-    pruner: Arc,
-    /// Wrapper class of the state kv pruner.
-    pruner_worker: Arc,
-    /// The worker thread handle for state_kv_pruner, created upon Pruner instance construction and
-    /// joined upon its destruction. It is `None` when the state kv pruner is not enabled or it only
-    /// becomes `None` after joined in `drop()`.
-    worker_thread: Option>,
-    /// We send a batch of version to the underlying pruners for performance reason. This tracks the
-    /// last version we sent to the pruners. Will only be set if the pruner is enabled.
-    pub(crate) last_version_sent_to_pruner: Arc>,
+    /// It is None iff the pruner is not enabled.
+    pruner_worker: Option,
     /// Ideal batch size of the versions to be sent to the state kv pruner.
     pruning_batch_size: usize,
-    /// latest version
-    latest_version: Arc>,
+    /// The minimal readable version for the ledger data.
+    min_readable_version: AtomicVersion,
 }
 
 impl PrunerManager for StateKvPrunerManager {
     type Pruner = StateKvPruner;
 
-    fn pruner(&self) -> &Self::Pruner {
-        &self.pruner
-    }
-
     fn is_pruner_enabled(&self) -> bool {
-        self.pruner_enabled
+        self.pruner_worker.is_some()
     }
 
     fn get_prune_window(&self) -> Version {
@@ -54,94 +39,99 @@ impl PrunerManager for StateKvPrunerManager {
     }
 
     fn get_min_readable_version(&self) -> Version {
-        self.pruner.as_ref().min_readable_version()
-    }
-
-    fn get_min_viable_version(&self) -> Version {
-        unimplemented!()
+        self.min_readable_version.load(Ordering::SeqCst)
     }
 
     /// Sets pruner target version when necessary.
     fn maybe_set_pruner_target_db_version(&self, latest_version: Version) {
-        *self.latest_version.lock() = latest_version;
-
-        if self.pruner_enabled
+        let min_readable_version = self.get_min_readable_version();
+        // Only wake up the state kv pruner if there are `ledger_pruner_pruning_batch_size` pending
+        if self.is_pruner_enabled()
             && latest_version
-                >= *self.last_version_sent_to_pruner.as_ref().lock()
-                    + self.pruning_batch_size as u64
+                >= min_readable_version + self.pruning_batch_size as u64 + self.prune_window
         {
             self.set_pruner_target_db_version(latest_version);
-            *self.last_version_sent_to_pruner.as_ref().lock() = latest_version;
         }
     }
 
-    fn set_pruner_target_db_version(&self, latest_version: Version) {
-        assert!(self.pruner_enabled);
+    fn save_min_readable_version(&self, min_readable_version: Version) -> Result<()> {
+        self.min_readable_version
+            .store(min_readable_version, Ordering::SeqCst);
+
+        PRUNER_VERSIONS
+            .with_label_values(&["state_kv_pruner", "min_readable"])
+            .set(min_readable_version as i64);
+
+        self.state_kv_db.write_pruner_progress(min_readable_version)
+    }
+
+    fn is_pruning_pending(&self) -> bool {
+        self.pruner_worker
+            .as_ref()
+            .map_or(false, |w| w.is_pruning_pending())
+    }
+
+    #[cfg(test)]
+    fn set_worker_target_version(&self, target_version: Version) {
         self.pruner_worker
             .as_ref()
-            .set_target_db_version(latest_version.saturating_sub(self.prune_window));
+            .unwrap()
+            .set_target_db_version(target_version);
     }
 }
 
 impl StateKvPrunerManager {
-    /// Creates a worker thread that waits on a channel for pruning commands.
     pub fn new(state_kv_db: Arc, state_kv_pruner_config: LedgerPrunerConfig) -> Self {
-        let state_kv_pruner = pruner_utils::create_state_kv_pruner(state_kv_db);
-
-        if state_kv_pruner_config.enable {
-            PRUNER_WINDOW
-                .with_label_values(&["state_kv_pruner"])
-                .set(state_kv_pruner_config.prune_window as i64);
-
-            PRUNER_BATCH_SIZE
-                .with_label_values(&["state_kv_pruner"])
-                .set(state_kv_pruner_config.batch_size as i64);
-        }
-
-        let state_kv_pruner_worker = Arc::new(StateKvPrunerWorker::new(
-            Arc::clone(&state_kv_pruner),
-            state_kv_pruner_config,
-        ));
-
-        let state_kv_pruner_worker_clone = Arc::clone(&state_kv_pruner_worker);
-
-        let state_kv_pruner_worker_thread = if state_kv_pruner_config.enable {
-            Some(
-                std::thread::Builder::new()
-                    .name("aptosdb_state_kv_pruner".into())
-                    .spawn(move || state_kv_pruner_worker_clone.as_ref().work())
-                    .expect("Creating state kv pruner thread should succeed."),
-            )
+        let pruner_worker = if state_kv_pruner_config.enable {
+            Some(Self::init_pruner(
+                Arc::clone(&state_kv_db),
+                state_kv_pruner_config,
+            ))
         } else {
             None
         };
 
-        let min_readable_version = state_kv_pruner.min_readable_version();
+        let min_readable_version =
+            pruner_utils::get_state_kv_pruner_progress(&state_kv_db).expect("Must succeed.");
+
+        PRUNER_VERSIONS
+            .with_label_values(&["state_kv_pruner", "min_readable"])
+            .set(min_readable_version as i64);
 
         Self {
-            pruner_enabled: state_kv_pruner_config.enable,
+            state_kv_db,
             prune_window: state_kv_pruner_config.prune_window,
-            pruner: state_kv_pruner,
-            pruner_worker: state_kv_pruner_worker,
-            worker_thread: state_kv_pruner_worker_thread,
-            last_version_sent_to_pruner: Arc::new(Mutex::new(min_readable_version)),
+            pruner_worker,
             pruning_batch_size: state_kv_pruner_config.batch_size,
-            latest_version: Arc::new(Mutex::new(min_readable_version)),
+            min_readable_version: AtomicVersion::new(min_readable_version),
         }
     }
-}
 
-impl Drop for StateKvPrunerManager {
-    fn drop(&mut self) {
-        if self.pruner_enabled {
-            self.pruner_worker.stop_pruning();
-
-            assert!(self.worker_thread.is_some());
-            self.worker_thread
-                .take()
-                .expect("State kv pruner worker thread must exist.")
-                .join()
-                .expect("State kv pruner worker thread should join peacefully.");
-        }
+    fn init_pruner(
+        state_kv_db: Arc,
+        state_kv_pruner_config: LedgerPrunerConfig,
+    ) -> PrunerWorker {
+        let pruner = pruner_utils::create_state_kv_pruner(state_kv_db);
+
+        PRUNER_WINDOW
+            .with_label_values(&["state_kv_pruner"])
+            .set(state_kv_pruner_config.prune_window as i64);
+
+        PRUNER_BATCH_SIZE
+            .with_label_values(&["state_kv_pruner"])
+            .set(state_kv_pruner_config.batch_size as i64);
+
+        PrunerWorker::new(pruner, state_kv_pruner_config.batch_size, "state_kv")
+    }
+
+    fn set_pruner_target_db_version(&self, latest_version: Version) {
+        assert!(self.pruner_worker.is_some());
+        let min_readable_version = latest_version.saturating_sub(self.prune_window);
+        self.min_readable_version
+            .store(min_readable_version, Ordering::SeqCst);
+        self.pruner_worker
+            .as_ref()
+            .unwrap()
+            .set_target_db_version(min_readable_version);
     }
 }
diff --git a/storage/aptosdb/src/pruner/state_kv_pruner_worker.rs b/storage/aptosdb/src/pruner/state_kv_pruner_worker.rs
deleted file mode 100644
index abc073ca5fc16..0000000000000
--- a/storage/aptosdb/src/pruner/state_kv_pruner_worker.rs
+++ /dev/null
@@ -1,76 +0,0 @@
-// Copyright © Aptos Foundation
-// SPDX-License-Identifier: Apache-2.0
-
-use crate::pruner::{db_pruner::DBPruner, state_kv_pruner::StateKvPruner};
-use aptos_config::config::LedgerPrunerConfig;
-use aptos_logger::{
-    error,
-    prelude::{sample, SampleRate},
-};
-use aptos_types::transaction::Version;
-use std::{
-    sync::{
-        atomic::{AtomicBool, Ordering},
-        Arc,
-    },
-    thread::sleep,
-    time::Duration,
-};
-
-/// Maintains the state kv pruner and periodically calls the db_pruner's prune method to prune the DB.
-/// This also exposes API to report the progress to the parent thread.
-pub struct StateKvPrunerWorker {
-    /// The worker will sleep for this period of time after pruning each batch.
-    pruning_time_interval_in_ms: u64,
-    /// State kv pruner.
-    pruner: Arc,
-    /// Max number of versions to prune per batch.
-    max_versions_to_prune_per_batch: u64,
-    /// Indicates whether the pruning loop should be running. Will only be set to true on pruner
-    /// destruction.
-    quit_worker: AtomicBool,
-}
-
-impl StateKvPrunerWorker {
-    pub(crate) fn new(
-        state_kv_pruner: Arc,
-        state_kv_pruner_config: LedgerPrunerConfig,
-    ) -> Self {
-        Self {
-            pruning_time_interval_in_ms: if cfg!(test) { 100 } else { 1 },
-            pruner: state_kv_pruner,
-            max_versions_to_prune_per_batch: state_kv_pruner_config.batch_size as u64,
-            quit_worker: AtomicBool::new(false),
-        }
-    }
-
-    // Loop that does the real pruning job.
-    pub(crate) fn work(&self) {
-        while !self.quit_worker.load(Ordering::Relaxed) {
-            let pruner_result = self
-                .pruner
-                .prune(self.max_versions_to_prune_per_batch as usize);
-            if pruner_result.is_err() {
-                sample!(
-                    SampleRate::Duration(Duration::from_secs(1)),
-                    error!(error = ?pruner_result.err().unwrap(),
-                        "State kv pruner has error.")
-                );
-                sleep(Duration::from_millis(self.pruning_time_interval_in_ms));
-                return;
-            }
-            if !self.pruner.is_pruning_pending() {
-                sleep(Duration::from_millis(self.pruning_time_interval_in_ms));
-            }
-        }
-    }
-
-    pub fn set_target_db_version(&self, target_db_version: Version) {
-        assert!(target_db_version >= self.pruner.target_version());
-        self.pruner.set_target_version(target_db_version);
-    }
-
-    pub fn stop_pruning(&self) {
-        self.quit_worker.store(true, Ordering::Relaxed);
-    }
-}
diff --git a/storage/aptosdb/src/pruner/state_merkle_pruner_manager.rs b/storage/aptosdb/src/pruner/state_merkle_pruner_manager.rs
index 73e9c96350d9a..8008e06a4ece0 100644
--- a/storage/aptosdb/src/pruner/state_merkle_pruner_manager.rs
+++ b/storage/aptosdb/src/pruner/state_merkle_pruner_manager.rs
@@ -5,22 +5,24 @@
 //! meant to be triggered by other threads as they commit new data to the DB.
 
 use crate::{
-    metrics::{PRUNER_BATCH_SIZE, PRUNER_WINDOW},
+    metrics::{PRUNER_BATCH_SIZE, PRUNER_VERSIONS, PRUNER_WINDOW},
     pruner::{
-        db_pruner::DBPruner,
         pruner_manager::PrunerManager,
-        state_merkle_pruner_worker::StateMerklePrunerWorker,
+        pruner_worker::PrunerWorker,
         state_store::{generics::StaleNodeIndexSchemaTrait, StateMerklePruner},
     },
     pruner_utils,
     state_merkle_db::StateMerkleDb,
 };
+use anyhow::Result;
 use aptos_config::config::StateMerklePrunerConfig;
-use aptos_infallible::Mutex;
 use aptos_jellyfish_merkle::StaleNodeIndex;
 use aptos_schemadb::schema::KeyCodec;
-use aptos_types::transaction::Version;
-use std::{sync::Arc, thread::JoinHandle};
+use aptos_types::transaction::{AtomicVersion, Version};
+use std::{
+    marker::PhantomData,
+    sync::{atomic::Ordering, Arc},
+};
 
 /// The `Pruner` is meant to be part of a `AptosDB` instance and runs in the background to prune old
 /// data.
@@ -28,29 +30,20 @@ use std::{sync::Arc, thread::JoinHandle};
 /// If the state pruner is enabled, it creates a worker thread on construction and joins it on
 /// destruction. When destructed, it quits the worker thread eagerly without waiting for all
 /// pending work to be done.
-#[derive(Debug)]
 pub struct StateMerklePrunerManager
 where
     StaleNodeIndex: KeyCodec,
 {
-    pruner_enabled: bool,
+    state_merkle_db: Arc,
     /// DB version window, which dictates how many versions of state store
     /// to keep.
     prune_window: Version,
-    /// State pruner. Is always initialized regardless if the pruner is enabled to keep tracks
-    /// of the min_readable_version.
-    pruner: Arc>,
-    /// Wrapper class of the state pruner.
-    pub(crate) pruner_worker: Arc>,
-    /// The worker thread handle for state_merkle_pruner, created upon Pruner instance construction and
-    /// joined upon its destruction. It is `None` when state pruner is not enabled or it only
-    /// becomes `None` after joined in `drop()`.
-    worker_thread: Option>,
-    /// We send a batch of version to the underlying pruners for performance reason. This tracks the
-    /// last version we sent to the pruner. Will only be set if the pruner is enabled.
-    last_version_sent_to_pruner: Arc>,
-    /// latest version
-    latest_version: Arc>,
+    /// It is None iff the pruner is not enabled.
+    pruner_worker: Option,
+    /// The minimal readable version for the ledger data.
+    min_readable_version: AtomicVersion,
+
+    _phantom: PhantomData,
 }
 
 impl PrunerManager for StateMerklePrunerManager
@@ -59,12 +52,8 @@ where
 {
     type Pruner = StateMerklePruner;
 
-    fn pruner(&self) -> &Self::Pruner {
-        &self.pruner
-    }
-
     fn is_pruner_enabled(&self) -> bool {
-        self.pruner_enabled
+        self.pruner_worker.is_some()
     }
 
     fn get_prune_window(&self) -> Version {
@@ -72,29 +61,41 @@ where
     }
 
     fn get_min_readable_version(&self) -> Version {
-        self.pruner.as_ref().min_readable_version()
-    }
-
-    fn get_min_viable_version(&self) -> Version {
-        unimplemented!()
+        self.min_readable_version.load(Ordering::SeqCst)
     }
 
     /// Sets pruner target version when necessary.
     fn maybe_set_pruner_target_db_version(&self, latest_version: Version) {
-        *self.latest_version.lock() = latest_version;
-
         // Always wake up the state pruner.
-        if self.pruner_enabled {
+        if self.is_pruner_enabled() {
             self.set_pruner_target_db_version(latest_version);
-            *self.last_version_sent_to_pruner.as_ref().lock() = latest_version;
         }
     }
 
-    fn set_pruner_target_db_version(&self, latest_version: Version) {
-        assert!(self.pruner_enabled);
+    fn save_min_readable_version(&self, min_readable_version: Version) -> Result<()> {
+        self.min_readable_version
+            .store(min_readable_version, Ordering::SeqCst);
+
+        PRUNER_VERSIONS
+            .with_label_values(&[S::name(), "min_readable"])
+            .set(min_readable_version as i64);
+
+        self.state_merkle_db
+            .write_pruner_progress(min_readable_version)
+    }
+
+    fn is_pruning_pending(&self) -> bool {
         self.pruner_worker
             .as_ref()
-            .set_target_db_version(latest_version.saturating_sub(self.prune_window));
+            .map_or(false, |w| w.is_pruning_pending())
+    }
+
+    #[cfg(test)]
+    fn set_worker_target_version(&self, target_version: Version) {
+        self.pruner_worker
+            .as_ref()
+            .unwrap()
+            .set_target_db_version(target_version);
     }
 }
 
@@ -103,65 +104,61 @@ where
     StaleNodeIndex: KeyCodec,
 {
     /// Creates a worker thread that waits on a channel for pruning commands.
-    pub fn new(state_merkle_db: Arc, config: StateMerklePrunerConfig) -> Self {
-        let state_db_clone = Arc::clone(&state_merkle_db);
-        let pruner = pruner_utils::create_state_merkle_pruner(state_db_clone);
-
-        if config.enable {
-            PRUNER_WINDOW
-                .with_label_values(&[S::name()])
-                .set(config.prune_window as i64);
-
-            PRUNER_BATCH_SIZE
-                .with_label_values(&[S::name()])
-                .set(config.batch_size as i64);
-        }
-
-        let pruner_worker = Arc::new(StateMerklePrunerWorker::new(Arc::clone(&pruner), config));
-        let state_merkle_pruner_worker_clone = Arc::clone(&pruner_worker);
-
-        let worker_thread = if config.enable {
-            Some(
-                std::thread::Builder::new()
-                    .name("aptosdb_state_merkle_pruner".into())
-                    .spawn(move || state_merkle_pruner_worker_clone.as_ref().work())
-                    .expect("Creating state pruner thread should succeed."),
-            )
+    pub fn new(
+        state_merkle_db: Arc,
+        state_merkle_pruner_config: StateMerklePrunerConfig,
+    ) -> Self {
+        let pruner_worker = if state_merkle_pruner_config.enable {
+            Some(Self::init_pruner(
+                Arc::clone(&state_merkle_db),
+                state_merkle_pruner_config,
+            ))
         } else {
             None
         };
 
-        let min_readable_version = pruner.as_ref().min_readable_version();
+        let min_readable_version = pruner_utils::get_state_merkle_pruner_progress(&state_merkle_db)
+            .expect("Must succeed.");
+
+        PRUNER_VERSIONS
+            .with_label_values(&[S::name(), "min_readable"])
+            .set(min_readable_version as i64);
+
         Self {
-            pruner_enabled: config.enable,
-            prune_window: config.prune_window,
-            pruner,
+            state_merkle_db,
+            prune_window: state_merkle_pruner_config.prune_window,
             pruner_worker,
-            worker_thread,
-            last_version_sent_to_pruner: Arc::new(Mutex::new(min_readable_version)),
-            latest_version: Arc::new(Mutex::new(min_readable_version)),
+            min_readable_version: AtomicVersion::new(min_readable_version),
+            _phantom: PhantomData,
         }
     }
 
-    #[cfg(test)]
-    pub fn testonly_update_min_version(&self, version: Version) {
-        self.pruner.testonly_update_min_version(version);
+    fn init_pruner(
+        state_merkle_db: Arc,
+        state_merkle_pruner_config: StateMerklePrunerConfig,
+    ) -> PrunerWorker {
+        let pruner = pruner_utils::create_state_merkle_pruner::(state_merkle_db);
+
+        PRUNER_WINDOW
+            .with_label_values(&[S::name()])
+            .set(state_merkle_pruner_config.prune_window as i64);
+
+        PRUNER_BATCH_SIZE
+            .with_label_values(&[S::name()])
+            .set(state_merkle_pruner_config.batch_size as i64);
+
+        PrunerWorker::new(
+            pruner,
+            state_merkle_pruner_config.batch_size,
+            "state_merkle",
+        )
     }
-}
 
-impl Drop for StateMerklePrunerManager
-where
-    StaleNodeIndex: KeyCodec,
-{
-    fn drop(&mut self) {
-        if self.pruner_enabled {
-            self.pruner_worker.stop_pruning();
-            assert!(self.worker_thread.is_some());
-            self.worker_thread
-                .take()
-                .expect("State merkle pruner worker thread must exist.")
-                .join()
-                .expect("State merkle pruner worker thread should join peacefully.");
-        }
+    fn set_pruner_target_db_version(&self, latest_version: Version) {
+        assert!(self.pruner_worker.is_some());
+        self.pruner_worker
+            .as_ref()
+            .unwrap()
+            .set_target_db_version(latest_version.saturating_sub(self.prune_window));
     }
 }
diff --git a/storage/aptosdb/src/pruner/state_merkle_pruner_worker.rs b/storage/aptosdb/src/pruner/state_merkle_pruner_worker.rs
deleted file mode 100644
index 5d03a6c827dc3..0000000000000
--- a/storage/aptosdb/src/pruner/state_merkle_pruner_worker.rs
+++ /dev/null
@@ -1,85 +0,0 @@
-// Copyright © Aptos Foundation
-// SPDX-License-Identifier: Apache-2.0
-use crate::pruner::{
-    db_pruner::DBPruner,
-    state_store::{generics::StaleNodeIndexSchemaTrait, StateMerklePruner},
-};
-use aptos_config::config::StateMerklePrunerConfig;
-use aptos_jellyfish_merkle::StaleNodeIndex;
-use aptos_logger::{
-    error,
-    prelude::{sample, SampleRate},
-};
-use aptos_schemadb::schema::KeyCodec;
-use aptos_types::transaction::Version;
-use std::{
-    sync::{
-        atomic::{AtomicBool, Ordering},
-        Arc,
-    },
-    thread::sleep,
-    time::Duration,
-};
-
-/// Maintains the state store pruner and periodically calls the db_pruner's prune method to prune
-/// the DB. This also exposes API to report the progress to the parent thread.
-#[derive(Debug)]
-pub struct StateMerklePrunerWorker {
-    /// The worker will sleep for this period of time after pruning each batch.
-    pruning_time_interval_in_ms: u64,
-    /// State store pruner.
-    pruner: Arc>,
-    /// Max items to prune per batch (i.e. the max stale nodes to prune.)
-    max_node_to_prune_per_batch: u64,
-    /// Indicates whether the pruning loop should be running. Will only be set to true on pruner
-    /// destruction.
-    quit_worker: AtomicBool,
-    _phantom: std::marker::PhantomData,
-}
-
-impl StateMerklePrunerWorker
-where
-    StaleNodeIndex: KeyCodec,
-{
-    pub(crate) fn new(
-        state_merkle_pruner: Arc>,
-        state_merkle_pruner_config: StateMerklePrunerConfig,
-    ) -> Self {
-        Self {
-            pruning_time_interval_in_ms: if cfg!(test) { 100 } else { 1 },
-            pruner: state_merkle_pruner,
-            max_node_to_prune_per_batch: state_merkle_pruner_config.batch_size as u64,
-            quit_worker: AtomicBool::new(false),
-            _phantom: std::marker::PhantomData,
-        }
-    }
-
-    // Loop that does the real pruning job.
-    pub(crate) fn work(&self) {
-        while !self.quit_worker.load(Ordering::Relaxed) {
-            let pruner_result = self.pruner.prune(self.max_node_to_prune_per_batch as usize);
-            if pruner_result.is_err() {
-                sample!(
-                    SampleRate::Duration(Duration::from_secs(1)),
-                    error!(error = ?pruner_result.err().unwrap(),
-                        "State pruner has error.")
-                );
-                sleep(Duration::from_millis(self.pruning_time_interval_in_ms));
-                return;
-            }
-            if !self.pruner.is_pruning_pending() {
-                sleep(Duration::from_millis(self.pruning_time_interval_in_ms));
-            }
-        }
-    }
-
-    pub fn set_target_db_version(&self, target_db_version: Version) {
-        if target_db_version > self.pruner.target_version() {
-            self.pruner.set_target_version(target_db_version);
-        }
-    }
-
-    pub fn stop_pruning(&self) {
-        self.quit_worker.store(true, Ordering::Relaxed);
-    }
-}
diff --git a/storage/aptosdb/src/pruner/state_store/mod.rs b/storage/aptosdb/src/pruner/state_store/mod.rs
index f4a0aa418ab98..987e4f47a2d73 100644
--- a/storage/aptosdb/src/pruner/state_store/mod.rs
+++ b/storage/aptosdb/src/pruner/state_store/mod.rs
@@ -109,11 +109,6 @@ where
         let (min_readable_version, fully_pruned) = *self.progress.lock();
         self.target_version() > min_readable_version || !fully_pruned
     }
-
-    /// (For tests only.) Updates the minimal readable version kept by pruner.
-    fn testonly_update_min_version(&self, version: Version) {
-        self.record_progress_impl(version, true /* is_fully_pruned */);
-    }
 }
 
 impl StateMerklePruner
@@ -187,7 +182,7 @@ where
     fn record_progress_impl(&self, min_readable_version: Version, is_fully_pruned: bool) {
         *self.progress.lock() = (min_readable_version, is_fully_pruned);
         PRUNER_VERSIONS
-            .with_label_values(&[S::name(), "min_readable"])
+            .with_label_values(&[S::name(), "progress"])
             .set(min_readable_version as i64);
     }
 
diff --git a/storage/aptosdb/src/pruner/state_store/test.rs b/storage/aptosdb/src/pruner/state_store/test.rs
index 85124a2c2975e..15b53a8b07d77 100644
--- a/storage/aptosdb/src/pruner/state_store/test.rs
+++ b/storage/aptosdb/src/pruner/state_store/test.rs
@@ -3,7 +3,6 @@
 
 use crate::{
     new_sharded_kv_schema_batch,
-    pruner::{state_merkle_pruner_worker::StateMerklePrunerWorker, *},
     stale_node_index::StaleNodeIndexSchema,
     stale_state_value_index::StaleStateValueIndexSchema,
     state_merkle_db::StateMerkleDb,
@@ -327,54 +326,6 @@ fn test_state_store_pruner_disabled() {
     }
 }
 
-#[test]
-fn test_worker_quit_eagerly() {
-    let key = StateKey::raw(String::from("test_key1").into_bytes());
-
-    let value0 = StateValue::from(String::from("test_val1").into_bytes());
-    let value1 = StateValue::from(String::from("test_val2").into_bytes());
-    let value2 = StateValue::from(String::from("test_val3").into_bytes());
-
-    let tmp_dir = TempPath::new();
-    let aptos_db = AptosDB::new_for_test(&tmp_dir);
-    let state_store = &aptos_db.state_store;
-
-    let _root0 = put_value_set(
-        state_store,
-        vec![(key.clone(), value0.clone())],
-        0, /* version */
-    );
-    let _root1 = put_value_set(
-        state_store,
-        vec![(key.clone(), value1.clone())],
-        1, /* version */
-    );
-    let _root2 = put_value_set(
-        state_store,
-        vec![(key.clone(), value2.clone())],
-        2, /* version */
-    );
-
-    {
-        let state_merkle_pruner = pruner_utils::create_state_merkle_pruner::(
-            Arc::clone(&aptos_db.state_merkle_db),
-        );
-        let worker = StateMerklePrunerWorker::new(state_merkle_pruner, StateMerklePrunerConfig {
-            enable: true,
-            prune_window: 1,
-            batch_size: 100,
-        });
-        worker.set_target_db_version(/*target_db_version=*/ 1);
-        worker.set_target_db_version(/*target_db_version=*/ 2);
-        // Worker quits immediately.
-        worker.stop_pruning();
-        worker.work();
-        verify_state_in_store(state_store, key.clone(), Some(&value0), 0);
-        verify_state_in_store(state_store, key.clone(), Some(&value1), 1);
-        verify_state_in_store(state_store, key, Some(&value2), 2);
-    }
-}
-
 proptest! {
     #![proptest_config(ProptestConfig::with_cases(10))]
 
diff --git a/storage/aptosdb/src/pruner/transaction_store/test.rs b/storage/aptosdb/src/pruner/transaction_store/test.rs
index 5b8124bfd09fc..084b76f66b363 100644
--- a/storage/aptosdb/src/pruner/transaction_store/test.rs
+++ b/storage/aptosdb/src/pruner/transaction_store/test.rs
@@ -133,10 +133,6 @@ fn verify_txn_store_pruner(
             .wake_and_wait_pruner(i as u64 /* latest_version */)
             .unwrap();
         // ensure that all transaction up to i * 2 has been pruned
-        assert_eq!(
-            *pruner.last_version_sent_to_pruner.as_ref().lock(),
-            i as u64
-        );
         for j in 0..i {
             verify_txn_not_in_store(transaction_store, &txns, j as u64, ledger_version);
             // Ensure that transaction accumulator is pruned in DB. This can be done by trying to
diff --git a/storage/aptosdb/src/state_kv_db.rs b/storage/aptosdb/src/state_kv_db.rs
index 440b1ea7fc94d..3022957baaa0f 100644
--- a/storage/aptosdb/src/state_kv_db.rs
+++ b/storage/aptosdb/src/state_kv_db.rs
@@ -141,6 +141,13 @@ impl StateKvDb {
         )
     }
 
+    pub(crate) fn write_pruner_progress(&self, version: Version) -> Result<()> {
+        self.state_kv_metadata_db.put::(
+            &DbMetadataKey::StateKvPrunerProgress,
+            &DbMetadataValue::Version(version),
+        )
+    }
+
     pub(crate) fn create_checkpoint(
         db_root_path: impl AsRef,
         cp_root_path: impl AsRef,
diff --git a/storage/aptosdb/src/state_merkle_db.rs b/storage/aptosdb/src/state_merkle_db.rs
index 57ddd55afd293..e44c93073e36a 100644
--- a/storage/aptosdb/src/state_merkle_db.rs
+++ b/storage/aptosdb/src/state_merkle_db.rs
@@ -362,6 +362,13 @@ impl StateMerkleDb {
         &self.lru_cache
     }
 
+    pub(crate) fn write_pruner_progress(&self, version: Version) -> Result<()> {
+        self.state_merkle_metadata_db.put::(
+            &DbMetadataKey::StateMerklePrunerProgress,
+            &DbMetadataValue::Version(version),
+        )
+    }
+
     fn db_by_key(&self, node_key: &NodeKey) -> &DB {
         if let Some(shard_id) = node_key.get_shard_id() {
             self.db_shard(shard_id)
diff --git a/storage/aptosdb/src/utils/mod.rs b/storage/aptosdb/src/utils/mod.rs
index 645bf83b587b7..1ebc49f52b579 100644
--- a/storage/aptosdb/src/utils/mod.rs
+++ b/storage/aptosdb/src/utils/mod.rs
@@ -3,3 +3,20 @@
 
 pub mod iterators;
 pub(crate) mod truncation_helper;
+
+use crate::schema::db_metadata::{DbMetadataKey, DbMetadataSchema, DbMetadataValue};
+use anyhow::Result;
+use aptos_schemadb::DB;
+use aptos_types::transaction::Version;
+
+pub(crate) fn get_progress(db: &DB, progress_key: &DbMetadataKey) -> Result> {
+    Ok(
+        if let Some(DbMetadataValue::Version(progress)) =
+            db.get::(progress_key)?
+        {
+            Some(progress)
+        } else {
+            None
+        },
+    )
+}
diff --git a/storage/aptosdb/src/utils/truncation_helper.rs b/storage/aptosdb/src/utils/truncation_helper.rs
index 40556cc75ae8c..2b40e9218ca24 100644
--- a/storage/aptosdb/src/utils/truncation_helper.rs
+++ b/storage/aptosdb/src/utils/truncation_helper.rs
@@ -17,6 +17,7 @@ use crate::{
     },
     state_kv_db::StateKvDb,
     state_merkle_db::StateMerkleDb,
+    utils::get_progress,
     EventStore, TransactionStore, NUM_STATE_SHARDS,
 };
 use anyhow::Result;
@@ -37,15 +38,15 @@ use std::{
 };
 
 pub(crate) fn get_overall_commit_progress(ledger_metadata_db: &DB) -> Result> {
-    get_commit_progress(ledger_metadata_db, &DbMetadataKey::OverallCommitProgress)
+    get_progress(ledger_metadata_db, &DbMetadataKey::OverallCommitProgress)
 }
 
 pub(crate) fn get_ledger_commit_progress(ledger_metadata_db: &DB) -> Result> {
-    get_commit_progress(ledger_metadata_db, &DbMetadataKey::LedgerCommitProgress)
+    get_progress(ledger_metadata_db, &DbMetadataKey::LedgerCommitProgress)
 }
 
 pub(crate) fn get_state_kv_commit_progress(state_kv_db: &StateKvDb) -> Result> {
-    get_commit_progress(
+    get_progress(
         state_kv_db.metadata_db(),
         &DbMetadataKey::StateKvCommitProgress,
     )
@@ -54,24 +55,12 @@ pub(crate) fn get_state_kv_commit_progress(state_kv_db: &StateKvDb) -> Result Result> {
-    get_commit_progress(
+    get_progress(
         state_merkle_db.metadata_db(),
         &DbMetadataKey::StateMerkleCommitProgress,
     )
 }
 
-fn get_commit_progress(db: &DB, progress_key: &DbMetadataKey) -> Result> {
-    Ok(
-        if let Some(DbMetadataValue::Version(overall_commit_progress)) =
-            db.get::(progress_key)?
-        {
-            Some(overall_commit_progress)
-        } else {
-            None
-        },
-    )
-}
-
 pub(crate) fn truncate_ledger_db(
     ledger_db: Arc,
     current_version: Version,
diff --git a/storage/backup/backup-cli/src/backup_types/tests.rs b/storage/backup/backup-cli/src/backup_types/tests.rs
index 3bcc0cefbf886..7bf8d31e8c8cf 100644
--- a/storage/backup/backup-cli/src/backup_types/tests.rs
+++ b/storage/backup/backup-cli/src/backup_types/tests.rs
@@ -201,6 +201,11 @@ proptest! {
     #![proptest_config(ProptestConfig::with_cases(10))]
 
     #[test]
+    // Ignore for now because the pruner now is going to see the version data to figure out the
+    // progress, but we don't have version data before the state_snapshot_ver. As the result the
+    // API will throw an error when getting the old transactions.
+    // TODO(areshand): Figure out a plan for this.
+    #[ignore]
     #[cfg_attr(feature = "consensus-only-perf-test", ignore)]
     fn test_end_to_end(d in test_data_strategy().no_shrink()) {
         test_end_to_end_impl(d)

From 1399455d5db28b6643e4b1b8ac7c7fd6900deee0 Mon Sep 17 00:00:00 2001
From: Sital Kedia 
Date: Wed, 7 Jun 2023 15:59:13 -0700
Subject: [PATCH 099/200] [Execution][Sharding] Changes to block execution API
 to be able to pass sharded sub-blocks (#8577)

---
 Cargo.lock                                    |  2 +
 api/test-context/src/test_context.rs          |  2 +-
 consensus/src/state_computer.rs               |  5 +-
 .../executor-benchmark/src/native_executor.rs |  7 ++-
 .../src/transaction_executor.rs               |  2 +-
 .../src/integration_test_impl.rs              | 10 +++-
 execution/executor-types/Cargo.toml           |  1 +
 execution/executor-types/src/lib.rs           | 46 +++++++++++++-
 execution/executor/Cargo.toml                 |  1 +
 execution/executor/src/block_executor.rs      | 22 +++----
 execution/executor/src/chunk_executor.rs      |  7 ++-
 .../executor/src/components/chunk_output.rs   | 23 ++++++-
 execution/executor/src/db_bootstrapper.rs     |  2 +-
 execution/executor/src/fuzzing.rs             |  7 ++-
 execution/executor/src/mock_vm/mod.rs         |  3 +-
 .../src/tests/chunk_executor_tests.rs         |  4 +-
 execution/executor/src/tests/mod.rs           | 60 ++++++++++++-------
 .../executor/tests/db_bootstrapper_test.rs    |  2 +-
 .../tests/storage_integration_test.rs         |  2 +-
 19 files changed, 153 insertions(+), 55 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index b74549bcecbee..d7db13a198390 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1011,6 +1011,7 @@ name = "aptos-executor"
 version = "0.1.0"
 dependencies = [
  "anyhow",
+ "aptos-block-partitioner",
  "aptos-cached-packages",
  "aptos-config",
  "aptos-consensus-types",
@@ -1114,6 +1115,7 @@ name = "aptos-executor-types"
 version = "0.1.0"
 dependencies = [
  "anyhow",
+ "aptos-block-partitioner",
  "aptos-crypto",
  "aptos-scratchpad",
  "aptos-secure-net",
diff --git a/api/test-context/src/test_context.rs b/api/test-context/src/test_context.rs
index e1f14dd1796d6..3e91b09d4a0a8 100644
--- a/api/test-context/src/test_context.rs
+++ b/api/test-context/src/test_context.rs
@@ -604,7 +604,7 @@ impl TestContext {
         let parent_id = self.executor.committed_block_id();
         let result = self
             .executor
-            .execute_block((metadata.id(), txns.clone()), parent_id, None)
+            .execute_block((metadata.id(), txns.clone()).into(), parent_id, None)
             .unwrap();
         let mut compute_status = result.compute_status().clone();
         assert_eq!(compute_status.len(), txns.len(), "{:?}", result);
diff --git a/consensus/src/state_computer.rs b/consensus/src/state_computer.rs
index e87161cc9ed6c..9656e5ab4c56d 100644
--- a/consensus/src/state_computer.rs
+++ b/consensus/src/state_computer.rs
@@ -144,7 +144,7 @@ impl StateComputer for ExecutionProxy {
             "execute_block",
             tokio::task::spawn_blocking(move || {
                 executor.execute_block(
-                    (block_id, transactions_to_execute),
+                    (block_id, transactions_to_execute).into(),
                     parent_block_id,
                     block_gas_limit,
                 )
@@ -331,6 +331,7 @@ async fn test_commit_sync_race() {
         transaction_shuffler::create_transaction_shuffler,
     };
     use aptos_consensus_notifications::Error;
+    use aptos_executor_types::ExecutableBlock;
     use aptos_types::{
         aggregate_signature::AggregateSignature,
         block_info::BlockInfo,
@@ -354,7 +355,7 @@ async fn test_commit_sync_race() {
 
         fn execute_block(
             &self,
-            _block: (HashValue, Vec),
+            _block: ExecutableBlock,
             _parent_block_id: HashValue,
             _maybe_block_gas_limit: Option,
         ) -> Result {
diff --git a/execution/executor-benchmark/src/native_executor.rs b/execution/executor-benchmark/src/native_executor.rs
index 7294123769ce1..7685afa52c768 100644
--- a/execution/executor-benchmark/src/native_executor.rs
+++ b/execution/executor-benchmark/src/native_executor.rs
@@ -9,6 +9,7 @@ use anyhow::Result;
 use aptos_executor::{
     block_executor::TransactionBlockExecutor, components::chunk_output::ChunkOutput,
 };
+use aptos_executor_types::ExecutableTransactions;
 use aptos_storage_interface::cached_state_view::CachedStateView;
 use aptos_types::{
     account_address::AccountAddress,
@@ -336,10 +337,14 @@ impl NativeExecutor {
 
 impl TransactionBlockExecutor for NativeExecutor {
     fn execute_transaction_block(
-        transactions: Vec,
+        transactions: ExecutableTransactions,
         state_view: CachedStateView,
         _maybe_block_gas_limit: Option,
     ) -> Result {
+        let transactions = match transactions {
+            ExecutableTransactions::Unsharded(txns) => txns,
+            _ => todo!("sharded execution not yet supported"),
+        };
         let transaction_outputs = NATIVE_EXECUTOR_POOL.install(|| {
             transactions
                 .par_iter()
diff --git a/execution/executor-benchmark/src/transaction_executor.rs b/execution/executor-benchmark/src/transaction_executor.rs
index a156f13d8dc42..6cdaf2c0a72e3 100644
--- a/execution/executor-benchmark/src/transaction_executor.rs
+++ b/execution/executor-benchmark/src/transaction_executor.rs
@@ -61,7 +61,7 @@ where
         let block_id = HashValue::random();
         let output = self
             .executor
-            .execute_block((block_id, transactions), self.parent_block_id, None)
+            .execute_block((block_id, transactions).into(), self.parent_block_id, None)
             .unwrap();
 
         assert_eq!(output.compute_status().len(), num_txns);
diff --git a/execution/executor-test-helpers/src/integration_test_impl.rs b/execution/executor-test-helpers/src/integration_test_impl.rs
index 83d3b77bffa31..42f879d008170 100644
--- a/execution/executor-test-helpers/src/integration_test_impl.rs
+++ b/execution/executor-test-helpers/src/integration_test_impl.rs
@@ -164,7 +164,7 @@ pub fn test_execution_with_storage_impl() -> Arc {
 
     let output1 = executor
         .execute_block(
-            (block1_id, block1.clone()),
+            (block1_id, block1.clone()).into(),
             parent_block_id,
             BLOCK_GAS_LIMIT,
         )
@@ -375,7 +375,11 @@ pub fn test_execution_with_storage_impl() -> Arc {
 
     // Execute block 2, 3, 4
     let output2 = executor
-        .execute_block((block2_id, block2), epoch2_genesis_id, BLOCK_GAS_LIMIT)
+        .execute_block(
+            (block2_id, block2).into(),
+            epoch2_genesis_id,
+            BLOCK_GAS_LIMIT,
+        )
         .unwrap();
     let li2 = gen_ledger_info_with_sigs(2, &output2, block2_id, &[signer.clone()]);
     let epoch3_genesis_id = Block::make_genesis_block_from_ledger_info(li2.ledger_info()).id();
@@ -391,7 +395,7 @@ pub fn test_execution_with_storage_impl() -> Arc {
 
     let output3 = executor
         .execute_block(
-            (block3_id, block3.clone()),
+            (block3_id, block3.clone()).into(),
             epoch3_genesis_id,
             BLOCK_GAS_LIMIT,
         )
diff --git a/execution/executor-types/Cargo.toml b/execution/executor-types/Cargo.toml
index 4a6100161f235..a77177ce6e03a 100644
--- a/execution/executor-types/Cargo.toml
+++ b/execution/executor-types/Cargo.toml
@@ -14,6 +14,7 @@ rust-version = { workspace = true }
 
 [dependencies]
 anyhow = { workspace = true }
+aptos-block-partitioner = { workspace = true }
 aptos-crypto = { workspace = true }
 aptos-scratchpad = { workspace = true }
 aptos-secure-net = { workspace = true }
diff --git a/execution/executor-types/src/lib.rs b/execution/executor-types/src/lib.rs
index eeafe613814f2..4fd1364d45b9c 100644
--- a/execution/executor-types/src/lib.rs
+++ b/execution/executor-types/src/lib.rs
@@ -1,10 +1,10 @@
 // Copyright © Aptos Foundation
 // Parts of the project are originally copyright © Meta Platforms, Inc.
 // SPDX-License-Identifier: Apache-2.0
-
 #![forbid(unsafe_code)]
 
 use anyhow::Result;
+use aptos_block_partitioner::types::SubBlock;
 use aptos_crypto::{
     hash::{EventAccumulatorHasher, TransactionAccumulatorHasher, ACCUMULATOR_PLACEHOLDER_HASH},
     HashValue,
@@ -90,7 +90,7 @@ pub trait BlockExecutorTrait: Send + Sync {
     /// Executes a block.
     fn execute_block(
         &self,
-        block: (HashValue, Vec),
+        block: ExecutableBlock,
         parent_block_id: HashValue,
         maybe_block_gas_limit: Option,
     ) -> Result;
@@ -127,6 +127,48 @@ pub trait BlockExecutorTrait: Send + Sync {
     fn finish(&self);
 }
 
+pub struct ExecutableBlock {
+    pub block_id: HashValue,
+    pub transactions: ExecutableTransactions,
+}
+
+impl ExecutableBlock {
+    pub fn new(block_id: HashValue, transactions: ExecutableTransactions) -> Self {
+        Self {
+            block_id,
+            transactions,
+        }
+    }
+}
+
+impl From<(HashValue, Vec)> for ExecutableBlock {
+    fn from((block_id, transactions): (HashValue, Vec)) -> Self {
+        Self::new(block_id, ExecutableTransactions::Unsharded(transactions))
+    }
+}
+
+pub enum ExecutableTransactions {
+    Unsharded(Vec),
+    Sharded(Vec),
+}
+
+impl ExecutableTransactions {
+    pub fn num_transactions(&self) -> usize {
+        match self {
+            ExecutableTransactions::Unsharded(transactions) => transactions.len(),
+            ExecutableTransactions::Sharded(sub_blocks) => {
+                sub_blocks.iter().map(|sub_block| sub_block.len()).sum()
+            },
+        }
+    }
+}
+
+impl From> for ExecutableTransactions {
+    fn from(txns: Vec) -> Self {
+        Self::Unsharded(txns)
+    }
+}
+
 #[derive(Clone)]
 pub enum VerifyExecutionMode {
     NoVerify,
diff --git a/execution/executor/Cargo.toml b/execution/executor/Cargo.toml
index cb47f7f36d530..aae17baa701f9 100644
--- a/execution/executor/Cargo.toml
+++ b/execution/executor/Cargo.toml
@@ -14,6 +14,7 @@ rust-version = { workspace = true }
 
 [dependencies]
 anyhow = { workspace = true }
+aptos-block-partitioner = { workspace = true }
 aptos-consensus-types = { workspace = true }
 aptos-crypto = { workspace = true }
 aptos-executor-types = { workspace = true }
diff --git a/execution/executor/src/block_executor.rs b/execution/executor/src/block_executor.rs
index 9097df8babcd2..51374d06e6a9e 100644
--- a/execution/executor/src/block_executor.rs
+++ b/execution/executor/src/block_executor.rs
@@ -15,7 +15,9 @@ use crate::{
 };
 use anyhow::Result;
 use aptos_crypto::HashValue;
-use aptos_executor_types::{BlockExecutorTrait, Error, StateComputeResult};
+use aptos_executor_types::{
+    BlockExecutorTrait, Error, ExecutableBlock, ExecutableTransactions, StateComputeResult,
+};
 use aptos_infallible::RwLock;
 use aptos_logger::prelude::*;
 use aptos_scratchpad::SparseMerkleTree;
@@ -23,17 +25,14 @@ use aptos_state_view::StateViewId;
 use aptos_storage_interface::{
     async_proof_fetcher::AsyncProofFetcher, cached_state_view::CachedStateView, DbReaderWriter,
 };
-use aptos_types::{
-    ledger_info::LedgerInfoWithSignatures, state_store::state_value::StateValue,
-    transaction::Transaction,
-};
+use aptos_types::{ledger_info::LedgerInfoWithSignatures, state_store::state_value::StateValue};
 use aptos_vm::AptosVM;
 use fail::fail_point;
 use std::{marker::PhantomData, sync::Arc};
 
 pub trait TransactionBlockExecutor: Send + Sync {
     fn execute_transaction_block(
-        transactions: Vec,
+        transactions: ExecutableTransactions,
         state_view: CachedStateView,
         maybe_block_gas_limit: Option,
     ) -> Result;
@@ -41,7 +40,7 @@ pub trait TransactionBlockExecutor: Send + Sync {
 
 impl TransactionBlockExecutor for AptosVM {
     fn execute_transaction_block(
-        transactions: Vec,
+        transactions: ExecutableTransactions,
         state_view: CachedStateView,
         maybe_block_gas_limit: Option,
     ) -> Result {
@@ -105,7 +104,7 @@ where
 
     fn execute_block(
         &self,
-        block: (HashValue, Vec),
+        block: ExecutableBlock,
         parent_block_id: HashValue,
         maybe_block_gas_limit: Option,
     ) -> Result {
@@ -175,12 +174,15 @@ where
 
     fn execute_block(
         &self,
-        block: (HashValue, Vec),
+        block: ExecutableBlock,
         parent_block_id: HashValue,
         maybe_block_gas_limit: Option,
     ) -> Result {
         let _timer = APTOS_EXECUTOR_EXECUTE_BLOCK_SECONDS.start_timer();
-        let (block_id, transactions) = block;
+        let ExecutableBlock {
+            block_id,
+            transactions,
+        } = block;
         let committed_block = self.block_tree.root_block();
         let mut block_vec = self
             .block_tree
diff --git a/execution/executor/src/chunk_executor.rs b/execution/executor/src/chunk_executor.rs
index e2c3b9f27459f..cfc62b7e12e74 100644
--- a/execution/executor/src/chunk_executor.rs
+++ b/execution/executor/src/chunk_executor.rs
@@ -204,7 +204,7 @@ impl ChunkExecutorInner {
         let chunk_output = {
             let _timer = APTOS_EXECUTOR_VM_EXECUTE_CHUNK_SECONDS.start_timer();
             // State sync executor shouldn't have block gas limit.
-            ChunkOutput::by_transaction_execution::(transactions, state_view, None)?
+            ChunkOutput::by_transaction_execution::(transactions.into(), state_view, None)?
         };
         let executed_chunk = Self::apply_chunk_output_for_state_sync(
             verified_target_li,
@@ -528,10 +528,11 @@ impl ChunkExecutorInner {
             .iter()
             .take((end_version - begin_version) as usize)
             .cloned()
-            .collect();
+            .collect::>();
 
         // State sync executor shouldn't have block gas limit.
-        let chunk_output = ChunkOutput::by_transaction_execution::(txns, state_view, None)?;
+        let chunk_output =
+            ChunkOutput::by_transaction_execution::(txns.into(), state_view, None)?;
         // not `zip_eq`, deliberately
         for (version, txn_out, txn_info, write_set, events) in multizip((
             begin_version..end_version,
diff --git a/execution/executor/src/components/chunk_output.rs b/execution/executor/src/components/chunk_output.rs
index 698317e50f4c0..04a625300dc17 100644
--- a/execution/executor/src/components/chunk_output.rs
+++ b/execution/executor/src/components/chunk_output.rs
@@ -7,7 +7,7 @@
 use crate::{components::apply_chunk_output::ApplyChunkOutput, metrics};
 use anyhow::Result;
 use aptos_crypto::HashValue;
-use aptos_executor_types::{ExecutedBlock, ExecutedChunk};
+use aptos_executor_types::{ExecutableTransactions, ExecutedBlock, ExecutedChunk};
 use aptos_infallible::Mutex;
 use aptos_logger::{sample, sample::SampleRate, trace, warn};
 use aptos_storage_interface::{
@@ -45,6 +45,27 @@ pub struct ChunkOutput {
 
 impl ChunkOutput {
     pub fn by_transaction_execution(
+        transactions: ExecutableTransactions,
+        state_view: CachedStateView,
+        maybe_block_gas_limit: Option,
+    ) -> Result {
+        match transactions {
+            ExecutableTransactions::Unsharded(txns) => {
+                Self::by_transaction_execution_unsharded::(
+                    txns,
+                    state_view,
+                    maybe_block_gas_limit,
+                )
+            },
+            ExecutableTransactions::Sharded(_) => {
+                // TODO(skedia): Change this into sharded once we move partitioner out of the
+                // sharded block executor.
+                todo!("sharded execution integration is not yet done")
+            },
+        }
+    }
+
+    fn by_transaction_execution_unsharded(
         transactions: Vec,
         state_view: CachedStateView,
         maybe_block_gas_limit: Option,
diff --git a/execution/executor/src/db_bootstrapper.rs b/execution/executor/src/db_bootstrapper.rs
index c898a6269b215..d263d8f264e70 100644
--- a/execution/executor/src/db_bootstrapper.rs
+++ b/execution/executor/src/db_bootstrapper.rs
@@ -137,7 +137,7 @@ pub fn calculate_genesis(
     };
 
     let (mut output, _, _) = ChunkOutput::by_transaction_execution::(
-        vec![genesis_txn.clone()],
+        vec![genesis_txn.clone()].into(),
         base_state_view,
         None,
     )?
diff --git a/execution/executor/src/fuzzing.rs b/execution/executor/src/fuzzing.rs
index 45dd95abf8860..3e5a0fd1b3db9 100644
--- a/execution/executor/src/fuzzing.rs
+++ b/execution/executor/src/fuzzing.rs
@@ -8,7 +8,7 @@ use crate::{
 };
 use anyhow::Result;
 use aptos_crypto::{hash::SPARSE_MERKLE_PLACEHOLDER_HASH, HashValue};
-use aptos_executor_types::BlockExecutorTrait;
+use aptos_executor_types::{BlockExecutorTrait, ExecutableTransactions};
 use aptos_state_view::StateView;
 use aptos_storage_interface::{
     cached_state_view::CachedStateView, state_delta::StateDelta, DbReader, DbReaderWriter, DbWriter,
@@ -39,7 +39,8 @@ pub fn fuzz_execute_and_commit_blocks(
     let mut block_ids = vec![];
     for block in blocks {
         let block_id = block.0;
-        let _execution_results = executor.execute_block(block, parent_block_id, BLOCK_GAS_LIMIT);
+        let _execution_results =
+            executor.execute_block(block.into(), parent_block_id, BLOCK_GAS_LIMIT);
         parent_block_id = block_id;
         block_ids.push(block_id);
     }
@@ -51,7 +52,7 @@ pub struct FakeVM;
 
 impl TransactionBlockExecutor for FakeVM {
     fn execute_transaction_block(
-        transactions: Vec,
+        transactions: ExecutableTransactions,
         state_view: CachedStateView,
         maybe_block_gas_limit: Option,
     ) -> Result {
diff --git a/execution/executor/src/mock_vm/mod.rs b/execution/executor/src/mock_vm/mod.rs
index 6df256d61093c..eeec728a7b790 100644
--- a/execution/executor/src/mock_vm/mod.rs
+++ b/execution/executor/src/mock_vm/mod.rs
@@ -8,6 +8,7 @@ mod mock_vm_test;
 use crate::{block_executor::TransactionBlockExecutor, components::chunk_output::ChunkOutput};
 use anyhow::Result;
 use aptos_crypto::{ed25519::Ed25519PrivateKey, PrivateKey, Uniform};
+use aptos_executor_types::ExecutableTransactions;
 use aptos_state_view::StateView;
 use aptos_storage_interface::cached_state_view::CachedStateView;
 use aptos_types::{
@@ -59,7 +60,7 @@ pub struct MockVM;
 
 impl TransactionBlockExecutor for MockVM {
     fn execute_transaction_block(
-        transactions: Vec,
+        transactions: ExecutableTransactions,
         state_view: CachedStateView,
         maybe_block_gas_limit: Option,
     ) -> Result {
diff --git a/execution/executor/src/tests/chunk_executor_tests.rs b/execution/executor/src/tests/chunk_executor_tests.rs
index d7c057bddc8fe..058b7d80e06a7 100644
--- a/execution/executor/src/tests/chunk_executor_tests.rs
+++ b/execution/executor/src/tests/chunk_executor_tests.rs
@@ -274,7 +274,7 @@ fn test_executor_execute_and_commit_chunk_local_result_mismatch() {
             .collect::>();
         let output = executor
             .execute_block(
-                (block_id, block(txns, BLOCK_GAS_LIMIT)),
+                (block_id, block(txns, BLOCK_GAS_LIMIT)).into(),
                 parent_block_id,
                 BLOCK_GAS_LIMIT,
             )
@@ -324,7 +324,7 @@ fn test_executor_execute_and_commit_chunk_without_verify() {
             .map(|_| encode_mint_transaction(tests::gen_address(rng.gen::()), 100))
             .collect::>();
         let output = executor
-            .execute_block((block_id, block(txns)), parent_block_id)
+            .execute_block((block_id, block(txns)).into(), parent_block_id)
             .unwrap();
         let ledger_info = tests::gen_ledger_info(6, output.root_hash(), block_id, 1);
         executor.commit_blocks(vec![block_id], ledger_info).unwrap();
diff --git a/execution/executor/src/tests/mod.rs b/execution/executor/src/tests/mod.rs
index e9e4338642b06..cdcdac761e9bc 100644
--- a/execution/executor/src/tests/mod.rs
+++ b/execution/executor/src/tests/mod.rs
@@ -53,7 +53,7 @@ fn execute_and_commit_block(
 
     let output = executor
         .execute_block(
-            (id, block(vec![txn], BLOCK_GAS_LIMIT)),
+            (id, block(vec![txn], BLOCK_GAS_LIMIT)).into(),
             parent_block_id,
             BLOCK_GAS_LIMIT,
         )
@@ -152,7 +152,7 @@ fn test_executor_status() {
 
     let output = executor
         .execute_block(
-            (block_id, block(vec![txn0, txn1, txn2], BLOCK_GAS_LIMIT)),
+            (block_id, block(vec![txn0, txn1, txn2], BLOCK_GAS_LIMIT)).into(),
             parent_block_id,
             BLOCK_GAS_LIMIT,
         )
@@ -182,7 +182,7 @@ fn test_executor_status_consensus_only() {
 
     let output = executor
         .execute_block(
-            (block_id, block(vec![txn0, txn1, txn2], BLOCK_GAS_LIMIT)),
+            (block_id, block(vec![txn0, txn1, txn2], BLOCK_GAS_LIMIT)).into(),
             parent_block_id,
         )
         .unwrap();
@@ -211,7 +211,7 @@ fn test_executor_one_block() {
         .collect::>();
     let output = executor
         .execute_block(
-            (block_id, block(txns, BLOCK_GAS_LIMIT)),
+            (block_id, block(txns, BLOCK_GAS_LIMIT)).into(),
             parent_block_id,
             BLOCK_GAS_LIMIT,
         )
@@ -257,14 +257,14 @@ fn test_executor_two_blocks_with_failed_txns() {
         .collect::>();
     let _output1 = executor
         .execute_block(
-            (block1_id, block(block1_txns, BLOCK_GAS_LIMIT)),
+            (block1_id, block(block1_txns, BLOCK_GAS_LIMIT)).into(),
             parent_block_id,
             BLOCK_GAS_LIMIT,
         )
         .unwrap();
     let output2 = executor
         .execute_block(
-            (block2_id, block(block2_txns, BLOCK_GAS_LIMIT)),
+            (block2_id, block(block2_txns, BLOCK_GAS_LIMIT)).into(),
             block1_id,
             BLOCK_GAS_LIMIT,
         )
@@ -286,7 +286,7 @@ fn test_executor_commit_twice() {
     let block1_id = gen_block_id(1);
     let output1 = executor
         .execute_block(
-            (block1_id, block(block1_txns, BLOCK_GAS_LIMIT)),
+            (block1_id, block(block1_txns, BLOCK_GAS_LIMIT)).into(),
             parent_block_id,
             BLOCK_GAS_LIMIT,
         )
@@ -316,7 +316,7 @@ fn test_executor_execute_same_block_multiple_times() {
     for _i in 0..100 {
         let output = executor
             .execute_block(
-                (block_id, block(txns.clone(), BLOCK_GAS_LIMIT)),
+                (block_id, block(txns.clone(), BLOCK_GAS_LIMIT)).into(),
                 parent_block_id,
                 BLOCK_GAS_LIMIT,
             )
@@ -363,7 +363,7 @@ fn create_transaction_chunks(
 
     let output = executor
         .execute_block(
-            (id, txns.clone()),
+            (id, txns.clone()).into(),
             executor.committed_block_id(),
             BLOCK_GAS_LIMIT,
         )
@@ -403,7 +403,7 @@ fn test_noop_block_after_reconfiguration() {
     let first_block_id = gen_block_id(1);
     let output1 = executor
         .execute_block(
-            (first_block_id, vec![first_txn]),
+            (first_block_id, vec![first_txn]).into(),
             parent_block_id,
             BLOCK_GAS_LIMIT,
         )
@@ -412,7 +412,7 @@ fn test_noop_block_after_reconfiguration() {
     let second_block = TestBlock::new(10, 10, gen_block_id(2), BLOCK_GAS_LIMIT);
     let output2 = executor
         .execute_block(
-            (second_block.id, second_block.txns),
+            (second_block.id, second_block.txns).into(),
             parent_block_id,
             BLOCK_GAS_LIMIT,
         )
@@ -596,16 +596,32 @@ fn test_reconfig_suffix_empty_blocks() {
     block_b.txns.push(encode_reconfiguration_transaction());
     let parent_block_id = executor.committed_block_id();
     executor
-        .execute_block((block_a.id, block_a.txns), parent_block_id, BLOCK_GAS_LIMIT)
+        .execute_block(
+            (block_a.id, block_a.txns).into(),
+            parent_block_id,
+            BLOCK_GAS_LIMIT,
+        )
         .unwrap();
     let output = executor
-        .execute_block((block_b.id, block_b.txns), block_a.id, BLOCK_GAS_LIMIT)
+        .execute_block(
+            (block_b.id, block_b.txns).into(),
+            block_a.id,
+            BLOCK_GAS_LIMIT,
+        )
         .unwrap();
     executor
-        .execute_block((block_c.id, block_c.txns), block_b.id, BLOCK_GAS_LIMIT)
+        .execute_block(
+            (block_c.id, block_c.txns).into(),
+            block_b.id,
+            BLOCK_GAS_LIMIT,
+        )
         .unwrap();
     executor
-        .execute_block((block_d.id, block_d.txns), block_c.id, BLOCK_GAS_LIMIT)
+        .execute_block(
+            (block_d.id, block_d.txns).into(),
+            block_c.id,
+            BLOCK_GAS_LIMIT,
+        )
         .unwrap();
 
     let ledger_info = gen_ledger_info(20002, output.root_hash(), block_d.id, 1);
@@ -655,7 +671,7 @@ fn run_transactions_naive(
 
     for txn in transactions {
         let out = ChunkOutput::by_transaction_execution::(
-            vec![txn],
+            vec![txn].into(),
             ledger_view
                 .verified_state_view(
                     StateViewId::Miscellaneous,
@@ -703,7 +719,7 @@ proptest! {
 
             let parent_block_id = executor.committed_block_id();
             let output = executor.execute_block(
-                (block_id, block.txns.clone()), parent_block_id, BLOCK_GAS_LIMIT
+                (block_id, block.txns.clone()).into(), parent_block_id, BLOCK_GAS_LIMIT
             ).unwrap();
 
             // assert: txns after the reconfiguration are with status "Retry"
@@ -722,7 +738,7 @@ proptest! {
             // retry txns after reconfiguration
             let retry_block_id = gen_block_id(2);
             let retry_output = executor.execute_block(
-                (retry_block_id, block.txns.iter().skip(reconfig_txn_index as usize + 1).cloned().collect()), parent_block_id, BLOCK_GAS_LIMIT
+                (retry_block_id, block.txns.iter().skip(reconfig_txn_index as usize + 1).cloned().collect()).into(), parent_block_id, BLOCK_GAS_LIMIT
             ).unwrap();
             prop_assert!(retry_output.compute_status().iter().all(|s| matches!(*s, TransactionStatus::Keep(_))));
 
@@ -768,7 +784,7 @@ proptest! {
         {
             parent_block_id = executor.committed_block_id();
             let output_a = executor.execute_block(
-                (block_a.id, block_a.txns.clone()), parent_block_id, BLOCK_GAS_LIMIT
+                (block_a.id, block_a.txns.clone()).into(), parent_block_id, BLOCK_GAS_LIMIT
             ).unwrap();
             root_hash = output_a.root_hash();
             let ledger_info = gen_ledger_info(ledger_version_from_block_size(block_a.txns.len(), BLOCK_GAS_LIMIT) as u64, root_hash, block_a.id, 1);
@@ -779,7 +795,7 @@ proptest! {
         // Now we construct a new executor and run one more block.
         {
             let executor = BlockExecutor::::new(db);
-            let output_b = executor.execute_block((block_b.id, block_b.txns.clone()), parent_block_id, BLOCK_GAS_LIMIT).unwrap();
+            let output_b = executor.execute_block((block_b.id, block_b.txns.clone()).into(), parent_block_id, BLOCK_GAS_LIMIT).unwrap();
             root_hash = output_b.root_hash();
             let ledger_info = gen_ledger_info(
                 (ledger_version_from_block_size(block_a.txns.len(), BLOCK_GAS_LIMIT) + ledger_version_from_block_size(block_b.txns.len(), BLOCK_GAS_LIMIT)) as u64,
@@ -836,13 +852,13 @@ proptest! {
         let parent_block_id = executor.committed_block_id();
         let first_block_id = gen_block_id(1);
         let _output1 = executor.execute_block(
-            (first_block_id, first_block_txns),
+            (first_block_id, first_block_txns).into(),
             parent_block_id, BLOCK_GAS_LIMIT
         ).unwrap();
 
         let second_block_id = gen_block_id(2);
         let output2 = executor.execute_block(
-            (second_block_id, block(second_block_txns, BLOCK_GAS_LIMIT)),
+            (second_block_id, block(second_block_txns, BLOCK_GAS_LIMIT)).into(),
             first_block_id, BLOCK_GAS_LIMIT
         ).unwrap();
 
diff --git a/execution/executor/tests/db_bootstrapper_test.rs b/execution/executor/tests/db_bootstrapper_test.rs
index f6b7f0c946e51..74651fd30b862 100644
--- a/execution/executor/tests/db_bootstrapper_test.rs
+++ b/execution/executor/tests/db_bootstrapper_test.rs
@@ -87,7 +87,7 @@ fn execute_and_commit(txns: Vec, db: &DbReaderWriter, signer: &Vali
     let executor = BlockExecutor::::new(db.clone());
     let output = executor
         .execute_block(
-            (block_id, block(txns, BLOCK_GAS_LIMIT)),
+            (block_id, block(txns, BLOCK_GAS_LIMIT)).into(),
             executor.committed_block_id(),
             BLOCK_GAS_LIMIT,
         )
diff --git a/execution/executor/tests/storage_integration_test.rs b/execution/executor/tests/storage_integration_test.rs
index 158ccf2f391ef..bf358bb94d4d7 100644
--- a/execution/executor/tests/storage_integration_test.rs
+++ b/execution/executor/tests/storage_integration_test.rs
@@ -141,7 +141,7 @@ fn test_reconfiguration() {
     let block_id = gen_block_id(1);
     let vm_output = executor
         .execute_block(
-            (block_id, txn_block.clone()),
+            (block_id, txn_block.clone()).into(),
             parent_block_id,
             BLOCK_GAS_LIMIT,
         )

From 2c4ae768c62ce4912e9e6e1e67f462d0546ef722 Mon Sep 17 00:00:00 2001
From: igor-aptos <110557261+igor-aptos@users.noreply.github.com>
Date: Wed, 7 Jun 2023 16:23:18 -0700
Subject: [PATCH 100/200] Remove static from ForgeConfig (#8573)

Currently, all tests need to be statically defined, which precludes using any utility function for their creation, creating dynamic objects (like vectors), etc.
Boxing everything, resolves this issue
---
 testsuite/forge-cli/src/main.rs               | 431 +++++++++---------
 testsuite/forge/src/runner.rs                 | 111 +++--
 testsuite/testcases/src/lib.rs                |  39 +-
 .../tests/forge-local-compatibility.rs        |   2 +-
 .../tests/forge-local-performance.rs          |   2 +-
 5 files changed, 325 insertions(+), 260 deletions(-)

diff --git a/testsuite/forge-cli/src/main.rs b/testsuite/forge-cli/src/main.rs
index 1b219b55b3474..8401b9316c4c9 100644
--- a/testsuite/forge-cli/src/main.rs
+++ b/testsuite/forge-cli/src/main.rs
@@ -362,7 +362,7 @@ fn main() -> Result<()> {
 
 pub fn run_forge(
     global_duration: Duration,
-    tests: ForgeConfig<'_>,
+    tests: ForgeConfig,
     factory: F,
     options: &Options,
     logs: Option>,
@@ -443,7 +443,7 @@ fn get_changelog(prev_commit: Option<&String>, upstream_commit: &str) -> String
     }
 }
 
-fn get_test_suite(suite_name: &str, duration: Duration) -> Result> {
+fn get_test_suite(suite_name: &str, duration: Duration) -> Result {
     match suite_name {
         "local_test_suite" => Ok(local_test_suite()),
         "pre_release" => Ok(pre_release_suite()),
@@ -456,71 +456,68 @@ fn get_test_suite(suite_name: &str, duration: Duration) -> Result ForgeConfig<'static> {
+fn run_forever() -> ForgeConfig {
     ForgeConfig::default()
-        .with_admin_tests(vec![&GetMetadata])
+        .add_admin_test(GetMetadata)
         .with_genesis_module_bundle(aptos_cached_packages::head_release_bundle().clone())
-        .with_aptos_tests(vec![&RunForever])
+        .add_aptos_test(RunForever)
 }
 
-fn local_test_suite() -> ForgeConfig<'static> {
+fn local_test_suite() -> ForgeConfig {
     ForgeConfig::default()
-        .with_aptos_tests(vec![&FundAccount, &TransferCoins])
-        .with_admin_tests(vec![&GetMetadata])
-        .with_network_tests(vec![&RestartValidator, &EmitTransaction])
+        .add_aptos_test(FundAccount)
+        .add_aptos_test(TransferCoins)
+        .add_admin_test(GetMetadata)
+        .add_network_test(RestartValidator)
+        .add_network_test(EmitTransaction)
         .with_genesis_module_bundle(aptos_cached_packages::head_release_bundle().clone())
 }
 
-fn k8s_test_suite() -> ForgeConfig<'static> {
+fn k8s_test_suite() -> ForgeConfig {
     ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(30).unwrap())
-        .with_aptos_tests(vec![&FundAccount, &TransferCoins])
-        .with_admin_tests(vec![&GetMetadata])
-        .with_network_tests(vec![
-            &EmitTransaction,
-            &SimpleValidatorUpgrade,
-            &PerformanceBenchmark,
-        ])
-}
-
-fn single_test_suite(test_name: &str, duration: Duration) -> Result> {
-    let config =
-        ForgeConfig::default().with_initial_validator_count(NonZeroUsize::new(30).unwrap());
+        .add_aptos_test(FundAccount)
+        .add_aptos_test(TransferCoins)
+        .add_admin_test(GetMetadata)
+        .add_network_test(EmitTransaction)
+        .add_network_test(SimpleValidatorUpgrade)
+        .add_network_test(PerformanceBenchmark)
+}
+
+fn single_test_suite(test_name: &str, duration: Duration) -> Result {
     let single_test_suite = match test_name {
         // Land-blocking tests to be run on every PR:
         "land_blocking" => land_blocking_test_suite(duration), // to remove land_blocking, superseeded by the below
         "realistic_env_max_throughput" => realistic_env_max_throughput_test_suite(duration),
-        "compat" => compat(config),
-        "framework_upgrade" => upgrade(config),
+        "compat" => compat(),
+        "framework_upgrade" => upgrade(),
         // Rest of the tests:
-        "epoch_changer_performance" => epoch_changer_performance(config),
-        "state_sync_perf_fullnodes_apply_outputs" => {
-            state_sync_perf_fullnodes_apply_outputs(config)
-        },
+        "epoch_changer_performance" => epoch_changer_performance(),
+        "state_sync_perf_fullnodes_apply_outputs" => state_sync_perf_fullnodes_apply_outputs(),
         "state_sync_perf_fullnodes_execute_transactions" => {
-            state_sync_perf_fullnodes_execute_transactions(config)
+            state_sync_perf_fullnodes_execute_transactions()
         },
-        "state_sync_perf_fullnodes_fast_sync" => state_sync_perf_fullnodes_fast_sync(config),
-        "state_sync_perf_validators" => state_sync_perf_validators(config),
-        "validators_join_and_leave" => validators_join_and_leave(config),
-        "config" => config.with_network_tests(vec![&ReconfigurationTest]),
-        "network_partition" => network_partition(config),
-        "three_region_simulation" => three_region_simulation(config),
+        "state_sync_perf_fullnodes_fast_sync" => state_sync_perf_fullnodes_fast_sync(),
+        "state_sync_perf_validators" => state_sync_perf_validators(),
+        "validators_join_and_leave" => validators_join_and_leave(),
+        "config" => ForgeConfig::default().add_network_test(ReconfigurationTest),
+        "network_partition" => network_partition(),
+        "three_region_simulation" => three_region_simulation(),
         "three_region_simulation_with_different_node_speed" => {
-            three_region_simulation_with_different_node_speed(config)
+            three_region_simulation_with_different_node_speed()
         },
-        "network_bandwidth" => network_bandwidth(config),
-        "setup_test" => setup_test(config),
-        "single_vfn_perf" => single_vfn_perf(config),
-        "validator_reboot_stress_test" => validator_reboot_stress_test(config),
-        "fullnode_reboot_stress_test" => fullnode_reboot_stress_test(config),
+        "network_bandwidth" => network_bandwidth(),
+        "setup_test" => setup_test(),
+        "single_vfn_perf" => single_vfn_perf(),
+        "validator_reboot_stress_test" => validator_reboot_stress_test(),
+        "fullnode_reboot_stress_test" => fullnode_reboot_stress_test(),
         "account_creation" | "nft_mint" | "publishing" | "module_loading"
-        | "write_new_resource" => individual_workload_tests(test_name.into(), config),
-        "graceful_overload" => graceful_overload(config),
-        "three_region_simulation_graceful_overload" => three_region_sim_graceful_overload(config),
+        | "write_new_resource" => individual_workload_tests(test_name.into()),
+        "graceful_overload" => graceful_overload(),
+        "three_region_simulation_graceful_overload" => three_region_sim_graceful_overload(),
         // not scheduled on continuous
-        "load_vs_perf_benchmark" => load_vs_perf_benchmark(config),
-        "workload_vs_perf_benchmark" => workload_vs_perf_benchmark(config),
+        "load_vs_perf_benchmark" => load_vs_perf_benchmark(),
+        "workload_vs_perf_benchmark" => workload_vs_perf_benchmark(),
         // maximizing number of rounds and epochs within a given time, to stress test consensus
         // so using small constant traffic, small blocks and fast rounds, and short epochs.
         // reusing changing_working_quorum_test just for invariants/asserts, but with max_down_nodes = 0.
@@ -532,29 +529,27 @@ fn single_test_suite(test_name: &str, duration: Duration) -> Result different_node_speed_and_reliability_test(),
         "state_sync_slow_processing_catching_up" => state_sync_slow_processing_catching_up(),
         "state_sync_failures_catching_up" => state_sync_failures_catching_up(),
-        "twin_validator_test" => twin_validator_test(config),
+        "twin_validator_test" => twin_validator_test(),
         "large_db_simple_test" => large_db_simple_test(),
-        "consensus_only_perf_benchmark" => run_consensus_only_perf_test(config),
-        "consensus_only_three_region_simulation" => {
-            run_consensus_only_three_region_simulation(config)
-        },
-        "quorum_store_reconfig_enable_test" => quorum_store_reconfig_enable_test(config),
-        "mainnet_like_simulation_test" => mainnet_like_simulation_test(config),
-        "multiregion_benchmark_test" => multiregion_benchmark_test(config),
+        "consensus_only_perf_benchmark" => run_consensus_only_perf_test(),
+        "consensus_only_three_region_simulation" => run_consensus_only_three_region_simulation(),
+        "quorum_store_reconfig_enable_test" => quorum_store_reconfig_enable_test(),
+        "mainnet_like_simulation_test" => mainnet_like_simulation_test(),
+        "multiregion_benchmark_test" => multiregion_benchmark_test(),
         _ => return Err(format_err!("Invalid --suite given: {:?}", test_name)),
     };
     Ok(single_test_suite)
 }
 
-fn run_consensus_only_three_region_simulation(config: ForgeConfig) -> ForgeConfig {
-    config
+fn run_consensus_only_three_region_simulation() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
         .with_emit_job(
             EmitJobRequest::default()
                 .mode(EmitJobMode::ConstTps { tps: 30000 })
                 .txn_expiration_time_secs(5 * 60),
         )
-        .with_network_tests(vec![&ThreeRegionSameCloudSimulationTest])
+        .add_network_test(ThreeRegionSameCloudSimulationTest)
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             // no epoch change.
             helm_values["chain"]["epoch_duration_secs"] = (24 * 3600).into();
@@ -590,14 +585,15 @@ fn run_consensus_only_three_region_simulation(config: ForgeConfig) -> ForgeConfi
         )
 }
 
-fn run_consensus_only_perf_test(config: ForgeConfig) -> ForgeConfig {
+fn run_consensus_only_perf_test() -> ForgeConfig {
+    let config = ForgeConfig::default();
     let emit_job = config.get_emit_job().clone();
     config
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
-        .with_network_tests(vec![&LoadVsPerfBenchmark {
+        .add_network_test(LoadVsPerfBenchmark {
             test: &PerformanceBenchmark,
             workloads: Workloads::TPS(&[30000]),
-        }])
+        })
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             // no epoch change.
             helm_values["chain"]["epoch_duration_secs"] = (24 * 3600).into();
@@ -635,15 +631,15 @@ fn run_consensus_only_perf_test(config: ForgeConfig) -> ForgeConfig {
         )
 }
 
-fn large_db_simple_test() -> ForgeConfig<'static> {
+fn large_db_simple_test() -> ForgeConfig {
     large_db_test(10, 500, 300, "10-validators".to_string())
 }
 
-fn twin_validator_test(config: ForgeConfig) -> ForgeConfig {
-    config
-        .with_network_tests(vec![&TwinValidatorTest])
+fn twin_validator_test() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
         .with_initial_fullnode_count(5)
+        .add_network_test(TwinValidatorTest)
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             helm_values["chain"]["epoch_duration_secs"] = 300.into();
         }))
@@ -664,7 +660,7 @@ fn twin_validator_test(config: ForgeConfig) -> ForgeConfig {
         )
 }
 
-fn state_sync_failures_catching_up() -> ForgeConfig<'static> {
+fn state_sync_failures_catching_up() -> ForgeConfig {
     changing_working_quorum_test_helper(
         10,
         300,
@@ -672,7 +668,7 @@ fn state_sync_failures_catching_up() -> ForgeConfig<'static> {
         2500,
         true,
         false,
-        &ChangingWorkingQuorumTest {
+        ChangingWorkingQuorumTest {
             min_tps: 1500,
             always_healthy_nodes: 2,
             max_down_nodes: 1,
@@ -683,7 +679,7 @@ fn state_sync_failures_catching_up() -> ForgeConfig<'static> {
     )
 }
 
-fn state_sync_slow_processing_catching_up() -> ForgeConfig<'static> {
+fn state_sync_slow_processing_catching_up() -> ForgeConfig {
     changing_working_quorum_test_helper(
         10,
         300,
@@ -691,7 +687,7 @@ fn state_sync_slow_processing_catching_up() -> ForgeConfig<'static> {
         2500,
         true,
         true,
-        &ChangingWorkingQuorumTest {
+        ChangingWorkingQuorumTest {
             min_tps: 750,
             always_healthy_nodes: 2,
             max_down_nodes: 0,
@@ -702,8 +698,8 @@ fn state_sync_slow_processing_catching_up() -> ForgeConfig<'static> {
     )
 }
 
-fn different_node_speed_and_reliability_test() -> ForgeConfig<'static> {
-    changing_working_quorum_test_helper(20, 120, 70, 50, true, false, &ChangingWorkingQuorumTest {
+fn different_node_speed_and_reliability_test() -> ForgeConfig {
+    changing_working_quorum_test_helper(20, 120, 70, 50, true, false, ChangingWorkingQuorumTest {
         min_tps: 30,
         always_healthy_nodes: 6,
         max_down_nodes: 5,
@@ -713,27 +709,19 @@ fn different_node_speed_and_reliability_test() -> ForgeConfig<'static> {
     })
 }
 
-fn large_test_only_few_nodes_down() -> ForgeConfig<'static> {
-    changing_working_quorum_test_helper(
-        60,
-        120,
-        100,
-        70,
-        false,
-        false,
-        &ChangingWorkingQuorumTest {
-            min_tps: 50,
-            always_healthy_nodes: 40,
-            max_down_nodes: 10,
-            num_large_validators: 0,
-            add_execution_delay: false,
-            check_period_s: 27,
-        },
-    )
+fn large_test_only_few_nodes_down() -> ForgeConfig {
+    changing_working_quorum_test_helper(60, 120, 100, 70, false, false, ChangingWorkingQuorumTest {
+        min_tps: 50,
+        always_healthy_nodes: 40,
+        max_down_nodes: 10,
+        num_large_validators: 0,
+        add_execution_delay: false,
+        check_period_s: 27,
+    })
 }
 
-fn changing_working_quorum_test_high_load() -> ForgeConfig<'static> {
-    changing_working_quorum_test_helper(20, 120, 500, 300, true, true, &ChangingWorkingQuorumTest {
+fn changing_working_quorum_test_high_load() -> ForgeConfig {
+    changing_working_quorum_test_helper(20, 120, 500, 300, true, true, ChangingWorkingQuorumTest {
         min_tps: 50,
         always_healthy_nodes: 0,
         max_down_nodes: 20,
@@ -745,8 +733,8 @@ fn changing_working_quorum_test_high_load() -> ForgeConfig<'static> {
     })
 }
 
-fn changing_working_quorum_test() -> ForgeConfig<'static> {
-    changing_working_quorum_test_helper(20, 120, 100, 70, true, true, &ChangingWorkingQuorumTest {
+fn changing_working_quorum_test() -> ForgeConfig {
+    changing_working_quorum_test_helper(20, 120, 100, 70, true, true, ChangingWorkingQuorumTest {
         min_tps: 15,
         always_healthy_nodes: 0,
         max_down_nodes: 20,
@@ -758,8 +746,8 @@ fn changing_working_quorum_test() -> ForgeConfig<'static> {
     })
 }
 
-fn consensus_stress_test() -> ForgeConfig<'static> {
-    changing_working_quorum_test_helper(10, 60, 100, 80, true, false, &ChangingWorkingQuorumTest {
+fn consensus_stress_test() -> ForgeConfig {
+    changing_working_quorum_test_helper(10, 60, 100, 80, true, false, ChangingWorkingQuorumTest {
         min_tps: 50,
         always_healthy_nodes: 10,
         max_down_nodes: 0,
@@ -769,16 +757,16 @@ fn consensus_stress_test() -> ForgeConfig<'static> {
     })
 }
 
-fn load_vs_perf_benchmark(config: ForgeConfig) -> ForgeConfig {
-    config
+fn load_vs_perf_benchmark() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
         .with_initial_fullnode_count(10)
-        .with_network_tests(vec![&LoadVsPerfBenchmark {
+        .add_network_test(LoadVsPerfBenchmark {
             test: &PerformanceBenchmark,
             workloads: Workloads::TPS(&[
                 200, 1000, 3000, 5000, 7000, 7500, 8000, 9000, 10000, 12000, 15000,
             ]),
-        }])
+        })
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             // no epoch change.
             helm_values["chain"]["epoch_duration_secs"] = (24 * 3600).into();
@@ -794,8 +782,8 @@ fn load_vs_perf_benchmark(config: ForgeConfig) -> ForgeConfig {
         )
 }
 
-fn workload_vs_perf_benchmark(config: ForgeConfig) -> ForgeConfig {
-    config
+fn workload_vs_perf_benchmark() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(7).unwrap())
         .with_initial_fullnode_count(7)
         .with_node_helm_config_fn(Arc::new(move |helm_values| {
@@ -805,7 +793,7 @@ fn workload_vs_perf_benchmark(config: ForgeConfig) -> ForgeConfig {
         // .with_emit_job(EmitJobRequest::default().mode(EmitJobMode::MaxLoad {
         //     mempool_backlog: 10000,
         // }))
-        .with_network_tests(vec![&LoadVsPerfBenchmark {
+        .add_network_test(LoadVsPerfBenchmark {
             test: &PerformanceBenchmark,
             workloads: Workloads::TRANSACTIONS(&[
                 TransactionWorkload {
@@ -849,7 +837,7 @@ fn workload_vs_perf_benchmark(config: ForgeConfig) -> ForgeConfig {
                     unique_senders: true,
                 },
             ]),
-        }])
+        })
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             // no epoch change.
             helm_values["chain"]["epoch_duration_secs"] = (24 * 3600).into();
@@ -865,8 +853,8 @@ fn workload_vs_perf_benchmark(config: ForgeConfig) -> ForgeConfig {
         )
 }
 
-fn graceful_overload(config: ForgeConfig) -> ForgeConfig {
-    config
+fn graceful_overload() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(10).unwrap())
         // if we have full nodes for subset of validators, TPS drops.
         // Validators without VFN are proposing almost empty blocks,
@@ -874,21 +862,17 @@ fn graceful_overload(config: ForgeConfig) -> ForgeConfig {
         // something to potentially improve upon.
         // So having VFNs for all validators
         .with_initial_fullnode_count(10)
-        .with_network_tests(vec![&TwoTrafficsTest {
+        .add_network_test(TwoTrafficsTest {
             inner_mode: EmitJobMode::ConstTps { tps: 15000 },
             inner_gas_price: aptos_global_constants::GAS_UNIT_PRICE,
             inner_init_gas_price_multiplier: 20,
-            // because it is static, cannot use TransactionTypeArg::materialize method
-            inner_transaction_type: TransactionType::CoinTransfer {
-                invalid_transaction_ratio: 0,
-                sender_use_account_pool: false,
-            },
+            inner_transaction_type: TransactionTypeArg::CoinTransfer.materialize_default(),
             // Additionally - we are not really gracefully handling overlaods,
             // setting limits based on current reality, to make sure they
             // don't regress, but something to investigate
             avg_tps: 3400,
             latency_thresholds: &[],
-        }])
+        })
         // First start higher gas-fee traffic, to not cause issues with TxnEmitter setup - account creation
         .with_emit_job(
             EmitJobRequest::default()
@@ -917,8 +901,8 @@ fn graceful_overload(config: ForgeConfig) -> ForgeConfig {
         )
 }
 
-fn three_region_sim_graceful_overload(config: ForgeConfig) -> ForgeConfig {
-    config
+fn three_region_sim_graceful_overload() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
         // if we have full nodes for subset of validators, TPS drops.
         // Validators without VFN are proposing almost empty blocks,
@@ -926,9 +910,9 @@ fn three_region_sim_graceful_overload(config: ForgeConfig) -> ForgeConfig {
         // something to potentially improve upon.
         // So having VFNs for all validators
         .with_initial_fullnode_count(20)
-        .with_network_tests(vec![&CompositeNetworkTest {
-            wrapper: &ThreeRegionSameCloudSimulationTest,
-            test: &TwoTrafficsTest {
+        .add_network_test(CompositeNetworkTest::new(
+            ThreeRegionSameCloudSimulationTest,
+            TwoTrafficsTest {
                 inner_mode: EmitJobMode::ConstTps { tps: 15000 },
                 inner_gas_price: aptos_global_constants::GAS_UNIT_PRICE,
                 inner_init_gas_price_multiplier: 20,
@@ -943,7 +927,7 @@ fn three_region_sim_graceful_overload(config: ForgeConfig) -> ForgeConfig {
                 avg_tps: 1200,
                 latency_thresholds: &[],
             },
-        }])
+        ))
         // First start higher gas-fee traffic, to not cause issues with TxnEmitter setup - account creation
         .with_emit_job(
             EmitJobRequest::default()
@@ -972,14 +956,14 @@ fn three_region_sim_graceful_overload(config: ForgeConfig) -> ForgeConfig {
         )
 }
 
-fn individual_workload_tests(test_name: String, config: ForgeConfig) -> ForgeConfig {
+fn individual_workload_tests(test_name: String) -> ForgeConfig {
     let job = EmitJobRequest::default().mode(EmitJobMode::MaxLoad {
         mempool_backlog: 30000,
     });
-    config
-        .with_network_tests(vec![&PerformanceBenchmark])
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(5).unwrap())
         .with_initial_fullnode_count(3)
+        .add_network_test(PerformanceBenchmark)
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             helm_values["chain"]["epoch_duration_secs"] = 600.into();
         }))
@@ -1037,24 +1021,24 @@ fn individual_workload_tests(test_name: String, config: ForgeConfig) -> ForgeCon
         )
 }
 
-fn fullnode_reboot_stress_test(config: ForgeConfig) -> ForgeConfig {
-    config
+fn fullnode_reboot_stress_test() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(10).unwrap())
         .with_initial_fullnode_count(10)
-        .with_network_tests(vec![&FullNodeRebootStressTest])
+        .add_network_test(FullNodeRebootStressTest)
         .with_emit_job(EmitJobRequest::default().mode(EmitJobMode::ConstTps { tps: 5000 }))
         .with_success_criteria(SuccessCriteria::new(2000).add_wait_for_catchup_s(600))
 }
 
-fn validator_reboot_stress_test(config: ForgeConfig) -> ForgeConfig {
-    config
+fn validator_reboot_stress_test() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(15).unwrap())
         .with_initial_fullnode_count(1)
-        .with_network_tests(vec![&ValidatorRebootStressTest {
+        .add_network_test(ValidatorRebootStressTest {
             num_simultaneously: 3,
             down_time_secs: 5.0,
             pause_secs: 5.0,
-        }])
+        })
         .with_success_criteria(SuccessCriteria::new(2000).add_wait_for_catchup_s(600))
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             helm_values["chain"]["epoch_duration_secs"] = 120.into();
@@ -1066,11 +1050,11 @@ fn apply_quorum_store_configs_for_single_node(helm_values: &mut serde_yaml::Valu
         ["dynamic_max_txn_per_s"] = 5500.into();
 }
 
-fn single_vfn_perf(config: ForgeConfig) -> ForgeConfig {
-    config
+fn single_vfn_perf() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(1).unwrap())
         .with_initial_fullnode_count(1)
-        .with_network_tests(vec![&PerformanceBenchmark])
+        .add_network_test(PerformanceBenchmark)
         .with_success_criteria(
             SuccessCriteria::new(5000)
                 .add_no_restarts()
@@ -1081,33 +1065,34 @@ fn single_vfn_perf(config: ForgeConfig) -> ForgeConfig {
         }))
 }
 
-fn setup_test(config: ForgeConfig) -> ForgeConfig {
-    config
+fn setup_test() -> ForgeConfig {
+    ForgeConfig::default()
+        .with_initial_validator_count(NonZeroUsize::new(1).unwrap())
         .with_initial_fullnode_count(1)
-        .with_network_tests(vec![&ForgeSetupTest])
+        .add_network_test(ForgeSetupTest)
 }
 
-fn network_bandwidth(config: ForgeConfig) -> ForgeConfig {
-    config
+fn network_bandwidth() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(8).unwrap())
-        .with_network_tests(vec![&NetworkBandwidthTest])
+        .add_network_test(NetworkBandwidthTest)
 }
 
-fn three_region_simulation_with_different_node_speed(config: ForgeConfig) -> ForgeConfig {
-    config
+fn three_region_simulation_with_different_node_speed() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(30).unwrap())
         .with_initial_fullnode_count(30)
         .with_emit_job(EmitJobRequest::default().mode(EmitJobMode::ConstTps { tps: 5000 }))
-        .with_network_tests(vec![&CompositeNetworkTest {
-            wrapper: &ExecutionDelayTest {
+        .add_network_test(CompositeNetworkTest::new(
+            ExecutionDelayTest {
                 add_execution_delay: ExecutionDelayConfig {
                     inject_delay_node_fraction: 0.5,
                     inject_delay_max_transaction_percentage: 40,
                     inject_delay_per_transaction_ms: 2,
                 },
             },
-            test: &ThreeRegionSameCloudSimulationTest,
-        }])
+            ThreeRegionSameCloudSimulationTest,
+        ))
         .with_node_helm_config_fn(Arc::new(move |helm_values| {
             helm_values["validator"]["config"]["api"]["failpoints_enabled"] = true.into();
             // helm_values["validator"]["config"]["consensus"]["max_sending_block_txns"] =
@@ -1130,12 +1115,12 @@ fn three_region_simulation_with_different_node_speed(config: ForgeConfig) -> For
         )
 }
 
-fn three_region_simulation(config: ForgeConfig) -> ForgeConfig {
-    config
+fn three_region_simulation() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(12).unwrap())
         .with_initial_fullnode_count(12)
         .with_emit_job(EmitJobRequest::default().mode(EmitJobMode::ConstTps { tps: 5000 }))
-        .with_network_tests(vec![&ThreeRegionSameCloudSimulationTest])
+        .add_network_test(ThreeRegionSameCloudSimulationTest)
         // TODO(rustielin): tune these success criteria after we have a better idea of the test behavior
         .with_success_criteria(
             SuccessCriteria::new(3000)
@@ -1148,10 +1133,10 @@ fn three_region_simulation(config: ForgeConfig) -> ForgeConfig {
         )
 }
 
-fn network_partition(config: ForgeConfig) -> ForgeConfig {
-    config
+fn network_partition() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(10).unwrap())
-        .with_network_tests(vec![&NetworkPartitionTest])
+        .add_network_test(NetworkPartitionTest)
         .with_success_criteria(
             SuccessCriteria::new(2500)
                 .add_no_restarts()
@@ -1162,50 +1147,48 @@ fn network_partition(config: ForgeConfig) -> ForgeConfig {
         }))
 }
 
-fn compat(config: ForgeConfig) -> ForgeConfig {
-    config
+fn compat() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(5).unwrap())
-        .with_network_tests(vec![&SimpleValidatorUpgrade])
+        .add_network_test(SimpleValidatorUpgrade)
         .with_success_criteria(SuccessCriteria::new(5000).add_wait_for_catchup_s(240))
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             helm_values["chain"]["epoch_duration_secs"] = 30.into();
         }))
 }
 
-fn upgrade(config: ForgeConfig) -> ForgeConfig {
-    config
+fn upgrade() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(5).unwrap())
-        .with_network_tests(vec![&FrameworkUpgrade])
+        .add_network_test(FrameworkUpgrade)
         .with_success_criteria(SuccessCriteria::new(5000).add_wait_for_catchup_s(240))
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             helm_values["chain"]["epoch_duration_secs"] = 30.into();
         }))
 }
 
-fn epoch_changer_performance(config: ForgeConfig) -> ForgeConfig {
-    config
-        .with_network_tests(vec![&PerformanceBenchmark])
+fn epoch_changer_performance() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(5).unwrap())
         .with_initial_fullnode_count(2)
+        .add_network_test(PerformanceBenchmark)
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             helm_values["chain"]["epoch_duration_secs"] = 60.into();
         }))
 }
 
 /// A default config for running various state sync performance tests
-fn state_sync_perf_fullnodes_config(forge_config: ForgeConfig<'static>) -> ForgeConfig<'static> {
-    forge_config
+fn state_sync_perf_fullnodes_config() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(4).unwrap())
         .with_initial_fullnode_count(4)
 }
 
 /// The config for running a state sync performance test when applying
 /// transaction outputs in fullnodes.
-fn state_sync_perf_fullnodes_apply_outputs(
-    forge_config: ForgeConfig<'static>,
-) -> ForgeConfig<'static> {
-    state_sync_perf_fullnodes_config(forge_config)
-        .with_network_tests(vec![&StateSyncFullnodePerformance])
+fn state_sync_perf_fullnodes_apply_outputs() -> ForgeConfig {
+    state_sync_perf_fullnodes_config()
+        .add_network_test(StateSyncFullnodePerformance)
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             helm_values["chain"]["epoch_duration_secs"] = 600.into();
         }))
@@ -1220,11 +1203,9 @@ fn state_sync_perf_fullnodes_apply_outputs(
 
 /// The config for running a state sync performance test when executing
 /// transactions in fullnodes.
-fn state_sync_perf_fullnodes_execute_transactions(
-    forge_config: ForgeConfig<'static>,
-) -> ForgeConfig<'static> {
-    state_sync_perf_fullnodes_config(forge_config)
-        .with_network_tests(vec![&StateSyncFullnodePerformance])
+fn state_sync_perf_fullnodes_execute_transactions() -> ForgeConfig {
+    state_sync_perf_fullnodes_config()
+        .add_network_test(StateSyncFullnodePerformance)
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             helm_values["chain"]["epoch_duration_secs"] = 600.into();
         }))
@@ -1239,9 +1220,9 @@ fn state_sync_perf_fullnodes_execute_transactions(
 
 /// The config for running a state sync performance test when fast syncing
 /// to the latest epoch.
-fn state_sync_perf_fullnodes_fast_sync(forge_config: ForgeConfig<'static>) -> ForgeConfig<'static> {
-    state_sync_perf_fullnodes_config(forge_config)
-        .with_network_tests(vec![&StateSyncFullnodeFastSyncPerformance])
+fn state_sync_perf_fullnodes_fast_sync() -> ForgeConfig {
+    state_sync_perf_fullnodes_config()
+        .add_network_test(StateSyncFullnodeFastSyncPerformance)
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             helm_values["chain"]["epoch_duration_secs"] = 180.into(); // Frequent epochs
         }))
@@ -1262,8 +1243,8 @@ fn state_sync_perf_fullnodes_fast_sync(forge_config: ForgeConfig<'static>) -> Fo
 
 /// The config for running a state sync performance test when applying
 /// transaction outputs in failed validators.
-fn state_sync_perf_validators(forge_config: ForgeConfig<'static>) -> ForgeConfig<'static> {
-    forge_config
+fn state_sync_perf_validators() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(7).unwrap())
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             helm_values["chain"]["epoch_duration_secs"] = 600.into();
@@ -1274,19 +1255,19 @@ fn state_sync_perf_validators(forge_config: ForgeConfig<'static>) -> ForgeConfig
             helm_values["validator"]["config"]["state_sync"]["state_sync_driver"]
                 ["continuous_syncing_mode"] = "ApplyTransactionOutputs".into();
         }))
-        .with_network_tests(vec![&StateSyncValidatorPerformance])
+        .add_network_test(StateSyncValidatorPerformance)
         .with_success_criteria(SuccessCriteria::new(5000))
 }
 
 /// The config for running a validator join and leave test.
-fn validators_join_and_leave(forge_config: ForgeConfig<'static>) -> ForgeConfig<'static> {
-    forge_config
+fn validators_join_and_leave() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             helm_values["chain"]["epoch_duration_secs"] = 60.into();
             helm_values["chain"]["allow_new_validators"] = true.into();
         }))
-        .with_network_tests(vec![&ValidatorJoinLeaveTest])
+        .add_network_test(ValidatorJoinLeaveTest)
         .with_success_criteria(
             SuccessCriteria::new(5000)
                 .add_no_restarts()
@@ -1304,11 +1285,11 @@ fn validators_join_and_leave(forge_config: ForgeConfig<'static>) -> ForgeConfig<
         )
 }
 
-fn land_blocking_test_suite(duration: Duration) -> ForgeConfig<'static> {
+fn land_blocking_test_suite(duration: Duration) -> ForgeConfig {
     ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
         .with_initial_fullnode_count(10)
-        .with_network_tests(vec![&PerformanceBenchmark])
+        .add_network_test(PerformanceBenchmark)
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             // Have single epoch change in land blocking
             helm_values["chain"]["epoch_duration_secs"] = 300.into();
@@ -1339,34 +1320,29 @@ fn land_blocking_test_suite(duration: Duration) -> ForgeConfig<'static> {
         )
 }
 
-fn realistic_env_max_throughput_test_suite(duration: Duration) -> ForgeConfig<'static> {
+// TODO: Replace land_blocking when performance reaches on par with current land_blocking
+fn realistic_env_max_throughput_test_suite(duration: Duration) -> ForgeConfig {
     ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
         .with_initial_fullnode_count(10)
-        .with_network_tests(vec![&CompositeNetworkTest {
-            wrapper: &MultiRegionNetworkEmulationTest {
+        .add_network_test(CompositeNetworkTest::new_with_two_wrappers(
+            MultiRegionNetworkEmulationTest {
                 override_config: None,
             },
-            test: &CompositeNetworkTest {
-                wrapper: &CpuChaosTest {
-                    override_config: None,
-                },
-                test: &TwoTrafficsTest {
-                    inner_mode: EmitJobMode::MaxLoad {
-                        mempool_backlog: 40000,
-                    },
-                    inner_gas_price: aptos_global_constants::GAS_UNIT_PRICE,
-                    inner_init_gas_price_multiplier: 20,
-                    // because it is static, cannot use TransactionTypeArg::materialize method
-                    inner_transaction_type: TransactionType::CoinTransfer {
-                        invalid_transaction_ratio: 0,
-                        sender_use_account_pool: false,
-                    },
-                    avg_tps: 5000,
-                    latency_thresholds: &[],
+            CpuChaosTest {
+                override_config: None,
+            },
+            TwoTrafficsTest {
+                inner_mode: EmitJobMode::MaxLoad {
+                    mempool_backlog: 40000,
                 },
+                inner_gas_price: aptos_global_constants::GAS_UNIT_PRICE,
+                inner_init_gas_price_multiplier: 20,
+                inner_transaction_type: TransactionTypeArg::CoinTransfer.materialize_default(),
+                avg_tps: 5000,
+                latency_thresholds: &[],
             },
-        }])
+        ))
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             // Have single epoch change in land blocking
             helm_values["chain"]["epoch_duration_secs"] = 300.into();
@@ -1399,20 +1375,18 @@ fn realistic_env_max_throughput_test_suite(duration: Duration) -> ForgeConfig<'s
         )
 }
 
-fn pre_release_suite() -> ForgeConfig<'static> {
+fn pre_release_suite() -> ForgeConfig {
     ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(30).unwrap())
-        .with_network_tests(vec![&NetworkBandwidthTest])
+        .add_network_test(NetworkBandwidthTest)
 }
 
-fn chaos_test_suite(duration: Duration) -> ForgeConfig<'static> {
+fn chaos_test_suite(duration: Duration) -> ForgeConfig {
     ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(30).unwrap())
-        .with_network_tests(vec![
-            &NetworkBandwidthTest,
-            &ThreeRegionSameCloudSimulationTest,
-            &NetworkLossTest,
-        ])
+        .add_network_test(NetworkBandwidthTest)
+        .add_network_test(ThreeRegionSameCloudSimulationTest)
+        .add_network_test(NetworkLossTest)
         .with_success_criteria(
             SuccessCriteria::new(
                 if duration > Duration::from_secs(1200) {
@@ -1438,20 +1412,21 @@ fn changing_working_quorum_test_helper(
     min_avg_tps: usize,
     apply_txn_outputs: bool,
     use_chain_backoff: bool,
-    test: &'static ChangingWorkingQuorumTest,
-) -> ForgeConfig<'static> {
+    test: ChangingWorkingQuorumTest,
+) -> ForgeConfig {
     let config = ForgeConfig::default();
     let num_large_validators = test.num_large_validators;
+    let max_down_nodes = test.max_down_nodes;
     config
         .with_initial_validator_count(NonZeroUsize::new(num_validators).unwrap())
         .with_initial_fullnode_count(
-            if test.max_down_nodes == 0 {
+            if max_down_nodes == 0 {
                 0
             } else {
                 std::cmp::max(2, target_tps / 1000)
             },
         )
-        .with_network_tests(vec![test])
+        .add_network_test(test)
         .with_genesis_helm_config_fn(Arc::new(move |helm_values| {
             helm_values["chain"]["epoch_duration_secs"] = epoch_duration.into();
             helm_values["genesis"]["validator"]["num_validators_with_larger_stake"] =
@@ -1526,10 +1501,10 @@ fn changing_working_quorum_test_helper(
                 .add_no_restarts()
                 .add_wait_for_catchup_s(30)
                 .add_chain_progress(StateProgressThreshold {
-                    max_no_progress_secs: if test.max_down_nodes == 0 {
+                    max_no_progress_secs: if max_down_nodes == 0 {
                         // very aggressive if no nodes are expected to be down
                         3.0
-                    } else if test.max_down_nodes * 3 + 1 + 2 < num_validators {
+                    } else if max_down_nodes * 3 + 1 + 2 < num_validators {
                         // number of down nodes is at least 2 below the quorum limit, so
                         // we can still be reasonably aggressive
                         15.0
@@ -1549,12 +1524,12 @@ fn large_db_test(
     target_tps: usize,
     min_avg_tps: usize,
     existing_db_tag: String,
-) -> ForgeConfig<'static> {
+) -> ForgeConfig {
     let config = ForgeConfig::default();
     config
         .with_initial_validator_count(NonZeroUsize::new(num_validators).unwrap())
         .with_initial_fullnode_count(std::cmp::max(2, target_tps / 1000))
-        .with_network_tests(vec![&PerformanceBenchmark])
+        .add_network_test(PerformanceBenchmark)
         .with_existing_db(existing_db_tag.clone())
         .with_node_helm_config_fn(Arc::new(move |helm_values| {
             helm_values["validator"]["storage"]["labels"]["tag"] = existing_db_tag.clone().into();
@@ -1591,11 +1566,11 @@ fn large_db_test(
         )
 }
 
-fn quorum_store_reconfig_enable_test(forge_config: ForgeConfig<'static>) -> ForgeConfig<'static> {
-    forge_config
+fn quorum_store_reconfig_enable_test() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
         .with_initial_fullnode_count(20)
-        .with_network_tests(vec![&QuorumStoreOnChainEnableTest {}])
+        .add_network_test(QuorumStoreOnChainEnableTest {})
         .with_success_criteria(
             SuccessCriteria::new(5000)
                 .add_no_restarts()
@@ -1613,8 +1588,8 @@ fn quorum_store_reconfig_enable_test(forge_config: ForgeConfig<'static>) -> Forg
         )
 }
 
-fn mainnet_like_simulation_test(config: ForgeConfig<'static>) -> ForgeConfig<'static> {
-    config
+fn mainnet_like_simulation_test() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
         .with_emit_job(
             EmitJobRequest::default()
@@ -1623,14 +1598,14 @@ fn mainnet_like_simulation_test(config: ForgeConfig<'static>) -> ForgeConfig<'st
                 })
                 .txn_expiration_time_secs(5 * 60),
         )
-        .with_network_tests(vec![&CompositeNetworkTest {
-            wrapper: &MultiRegionNetworkEmulationTest {
+        .add_network_test(CompositeNetworkTest::new(
+            MultiRegionNetworkEmulationTest {
                 override_config: None,
             },
-            test: &CpuChaosTest {
+            CpuChaosTest {
                 override_config: None,
             },
-        }])
+        ))
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             // no epoch change.
             helm_values["chain"]["epoch_duration_secs"] = (24 * 3600).into();
@@ -1647,10 +1622,10 @@ fn mainnet_like_simulation_test(config: ForgeConfig<'static>) -> ForgeConfig<'st
         )
 }
 
-fn multiregion_benchmark_test(config: ForgeConfig<'static>) -> ForgeConfig<'static> {
-    config
+fn multiregion_benchmark_test() -> ForgeConfig {
+    ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
-        .with_network_tests(vec![&PerformanceBenchmark])
+        .add_network_test(PerformanceBenchmark)
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             // Have single epoch change in land blocking
             helm_values["chain"]["epoch_duration_secs"] = 300.into();
diff --git a/testsuite/forge/src/runner.rs b/testsuite/forge/src/runner.rs
index ab0f91234fefd..cb3b38daac5c9 100644
--- a/testsuite/forge/src/runner.rs
+++ b/testsuite/forge/src/runner.rs
@@ -98,7 +98,7 @@ impl Default for Format {
     }
 }
 
-pub fn forge_main(tests: ForgeConfig<'_>, factory: F, options: &Options) -> Result<()> {
+pub fn forge_main(tests: ForgeConfig, factory: F, options: &Options) -> Result<()> {
     let forge = Forge::new(options, tests, Duration::from_secs(30), factory);
 
     if options.list {
@@ -125,10 +125,10 @@ pub enum InitialVersion {
 pub type NodeConfigFn = Arc;
 pub type GenesisConfigFn = Arc;
 
-pub struct ForgeConfig<'cfg> {
-    aptos_tests: Vec<&'cfg dyn AptosTest>,
-    admin_tests: Vec<&'cfg dyn AdminTest>,
-    network_tests: Vec<&'cfg dyn NetworkTest>,
+pub struct ForgeConfig {
+    aptos_tests: Vec>,
+    admin_tests: Vec>,
+    network_tests: Vec>,
 
     /// The initial number of validators to spawn when the test harness creates a swarm
     initial_validator_count: NonZeroUsize,
@@ -158,22 +158,37 @@ pub struct ForgeConfig<'cfg> {
     existing_db_tag: Option,
 }
 
-impl<'cfg> ForgeConfig<'cfg> {
+impl ForgeConfig {
     pub fn new() -> Self {
         Self::default()
     }
 
-    pub fn with_aptos_tests(mut self, aptos_tests: Vec<&'cfg dyn AptosTest>) -> Self {
+    pub fn add_aptos_test(mut self, aptos_test: T) -> Self {
+        self.aptos_tests.push(Box::new(aptos_test));
+        self
+    }
+
+    pub fn with_aptos_tests(mut self, aptos_tests: Vec>) -> Self {
         self.aptos_tests = aptos_tests;
         self
     }
 
-    pub fn with_admin_tests(mut self, admin_tests: Vec<&'cfg dyn AdminTest>) -> Self {
+    pub fn add_admin_test(mut self, admin_test: T) -> Self {
+        self.admin_tests.push(Box::new(admin_test));
+        self
+    }
+
+    pub fn with_admin_tests(mut self, admin_tests: Vec>) -> Self {
         self.admin_tests = admin_tests;
         self
     }
 
-    pub fn with_network_tests(mut self, network_tests: Vec<&'cfg dyn NetworkTest>) -> Self {
+    pub fn add_network_test(mut self, network_test: T) -> Self {
+        self.network_tests.push(Box::new(network_test));
+        self
+    }
+
+    pub fn with_network_tests(mut self, network_tests: Vec>) -> Self {
         self.network_tests = network_tests;
         self
     }
@@ -240,12 +255,55 @@ impl<'cfg> ForgeConfig<'cfg> {
         self.admin_tests.len() + self.network_tests.len() + self.aptos_tests.len()
     }
 
-    pub fn all_tests(&self) -> impl Iterator {
+    pub fn all_tests(&self) -> Vec>> {
         self.admin_tests
             .iter()
-            .map(|t| t as &dyn Test)
-            .chain(self.network_tests.iter().map(|t| t as &dyn Test))
-            .chain(self.aptos_tests.iter().map(|t| t as &dyn Test))
+            .map(|t| Box::new(AnyTestRef::Admin(t.as_ref())))
+            .chain(
+                self.network_tests
+                    .iter()
+                    .map(|t| Box::new(AnyTestRef::Network(t.as_ref()))),
+            )
+            .chain(
+                self.aptos_tests
+                    .iter()
+                    .map(|t| Box::new(AnyTestRef::Aptos(t.as_ref()))),
+            )
+            .collect()
+    }
+}
+
+// Workaround way to implement all_tests, for:
+// error[E0658]: cannot cast `dyn interface::admin::AdminTest` to `dyn interface::test::Test`, trait upcasting coercion is experimental
+pub enum AnyTestRef<'a> {
+    Aptos(&'a dyn AptosTest),
+    Admin(&'a dyn AdminTest),
+    Network(&'a dyn NetworkTest),
+}
+
+impl<'a> Test for AnyTestRef<'a> {
+    fn name(&self) -> &'static str {
+        match self {
+            AnyTestRef::Aptos(t) => t.name(),
+            AnyTestRef::Admin(t) => t.name(),
+            AnyTestRef::Network(t) => t.name(),
+        }
+    }
+
+    fn ignored(&self) -> bool {
+        match self {
+            AnyTestRef::Aptos(t) => t.ignored(),
+            AnyTestRef::Admin(t) => t.ignored(),
+            AnyTestRef::Network(t) => t.ignored(),
+        }
+    }
+
+    fn should_fail(&self) -> ShouldFail {
+        match self {
+            AnyTestRef::Aptos(t) => t.should_fail(),
+            AnyTestRef::Admin(t) => t.should_fail(),
+            AnyTestRef::Network(t) => t.should_fail(),
+        }
     }
 }
 
@@ -279,7 +337,7 @@ impl ForgeRunnerMode {
     }
 }
 
-impl<'cfg> Default for ForgeConfig<'cfg> {
+impl Default for ForgeConfig {
     fn default() -> Self {
         let forge_run_mode = ForgeRunnerMode::try_from_env().unwrap_or(ForgeRunnerMode::K8s);
         let success_criteria = if forge_run_mode == ForgeRunnerMode::Local {
@@ -315,7 +373,7 @@ impl<'cfg> Default for ForgeConfig<'cfg> {
 
 pub struct Forge<'cfg, F> {
     options: &'cfg Options,
-    tests: ForgeConfig<'cfg>,
+    tests: ForgeConfig,
     global_duration: Duration,
     factory: F,
 }
@@ -323,7 +381,7 @@ pub struct Forge<'cfg, F> {
 impl<'cfg, F: Factory> Forge<'cfg, F> {
     pub fn new(
         options: &'cfg Options,
-        tests: ForgeConfig<'cfg>,
+        tests: ForgeConfig,
         global_duration: Duration,
         factory: F,
     ) -> Self {
@@ -336,7 +394,7 @@ impl<'cfg, F: Factory> Forge<'cfg, F> {
     }
 
     pub fn list(&self) -> Result<()> {
-        for test in self.filter_tests(self.tests.all_tests()) {
+        for test in self.filter_tests(&self.tests.all_tests()) {
             println!("{}: test", test.name());
         }
 
@@ -344,7 +402,7 @@ impl<'cfg, F: Factory> Forge<'cfg, F> {
             println!();
             println!(
                 "{} tests",
-                self.filter_tests(self.tests.all_tests()).count()
+                self.filter_tests(&self.tests.all_tests()).count()
             );
         }
 
@@ -362,8 +420,8 @@ impl<'cfg, F: Factory> Forge<'cfg, F> {
     }
 
     pub fn run(&self) -> Result {
-        let test_count = self.filter_tests(self.tests.all_tests()).count();
-        let filtered_out = test_count.saturating_sub(self.tests.all_tests().count());
+        let test_count = self.filter_tests(&self.tests.all_tests()).count();
+        let filtered_out = test_count.saturating_sub(self.tests.all_tests().len());
 
         let mut report = TestReport::new();
         let mut summary = TestSummary::new(test_count, filtered_out);
@@ -396,7 +454,7 @@ impl<'cfg, F: Factory> Forge<'cfg, F> {
             ))?;
 
             // Run AptosTests
-            for test in self.filter_tests(self.tests.aptos_tests.iter()) {
+            for test in self.filter_tests(&self.tests.aptos_tests) {
                 let mut aptos_ctx = AptosContext::new(
                     CoreContext::from_rng(&mut rng),
                     swarm.chain_info().into_aptos_public_info(),
@@ -408,7 +466,7 @@ impl<'cfg, F: Factory> Forge<'cfg, F> {
             }
 
             // Run AdminTests
-            for test in self.filter_tests(self.tests.admin_tests.iter()) {
+            for test in self.filter_tests(&self.tests.admin_tests) {
                 let mut admin_ctx = AdminContext::new(
                     CoreContext::from_rng(&mut rng),
                     swarm.chain_info(),
@@ -419,7 +477,7 @@ impl<'cfg, F: Factory> Forge<'cfg, F> {
                 summary.handle_result(test.name().to_owned(), result)?;
             }
 
-            for test in self.filter_tests(self.tests.network_tests.iter()) {
+            for test in self.filter_tests(&self.tests.network_tests) {
                 let mut network_ctx = NetworkContext::new(
                     CoreContext::from_rng(&mut rng),
                     &mut *swarm,
@@ -452,11 +510,12 @@ impl<'cfg, F: Factory> Forge<'cfg, F> {
         }
     }
 
-    fn filter_tests<'a, T: Test, I: Iterator + 'a>(
+    fn filter_tests<'a, T: Test + ?Sized>(
         &'a self,
-        tests: I,
-    ) -> impl Iterator + 'a {
+        tests: &'a [Box],
+    ) -> impl Iterator> {
         tests
+            .iter()
             // Filter by ignored
             .filter(
                 move |test| match (self.options.include_ignored, self.options.ignored) {
diff --git a/testsuite/testcases/src/lib.rs b/testsuite/testcases/src/lib.rs
index 9a184c887f2ed..9d98d766d3054 100644
--- a/testsuite/testcases/src/lib.rs
+++ b/testsuite/testcases/src/lib.rs
@@ -351,17 +351,48 @@ impl dyn NetworkLoadTest {
 pub struct CompositeNetworkTest {
     // Wrapper tests - their setup and finish methods are called, before the test ones.
     // TODO don't know how to make this array, and have forge/main.rs work
-    pub wrapper: &'static dyn NetworkLoadTest,
+    pub wrappers: Vec>,
     // This is the main test, return values from this test are used in setup, and
     // only it's test function is called.
-    pub test: &'static dyn NetworkTest,
+    pub test: Box,
+}
+
+impl CompositeNetworkTest {
+    pub fn new(
+        wrapper: W,
+        test: T,
+    ) -> CompositeNetworkTest {
+        CompositeNetworkTest {
+            wrappers: vec![Box::new(wrapper)],
+            test: Box::new(test),
+        }
+    }
+
+    pub fn new_with_two_wrappers<
+        T1: NetworkLoadTest + 'static,
+        T2: NetworkLoadTest + 'static,
+        W: NetworkTest + 'static,
+    >(
+        wrapper1: T1,
+        wrapper2: T2,
+        test: W,
+    ) -> CompositeNetworkTest {
+        CompositeNetworkTest {
+            wrappers: vec![Box::new(wrapper1), Box::new(wrapper2)],
+            test: Box::new(test),
+        }
+    }
 }
 
 impl NetworkTest for CompositeNetworkTest {
     fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> anyhow::Result<()> {
-        self.wrapper.setup(ctx)?;
+        for wrapper in &self.wrappers {
+            wrapper.setup(ctx)?;
+        }
         self.test.run(ctx)?;
-        self.wrapper.finish(ctx.swarm())?;
+        for wrapper in &self.wrappers {
+            wrapper.finish(ctx.swarm())?;
+        }
         Ok(())
     }
 }
diff --git a/testsuite/testcases/tests/forge-local-compatibility.rs b/testsuite/testcases/tests/forge-local-compatibility.rs
index e7c75fcebec7b..636b121676cca 100644
--- a/testsuite/testcases/tests/forge-local-compatibility.rs
+++ b/testsuite/testcases/tests/forge-local-compatibility.rs
@@ -12,7 +12,7 @@ fn main() -> Result<()> {
     let tests = ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(4).unwrap())
         .with_initial_version(InitialVersion::Oldest)
-        .with_network_tests(vec![&SimpleValidatorUpgrade]);
+        .add_network_test(SimpleValidatorUpgrade);
 
     let options = Options::from_args();
     forge_main(
diff --git a/testsuite/testcases/tests/forge-local-performance.rs b/testsuite/testcases/tests/forge-local-performance.rs
index 8d0f21aa54bae..5516c270c3b2b 100644
--- a/testsuite/testcases/tests/forge-local-performance.rs
+++ b/testsuite/testcases/tests/forge-local-performance.rs
@@ -16,7 +16,7 @@ fn main() -> Result<()> {
     let tests = ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(2).unwrap())
         .with_initial_version(InitialVersion::Newest)
-        .with_network_tests(vec![&PerformanceBenchmark])
+        .add_network_test(PerformanceBenchmark)
         .with_emit_job(
             EmitJobRequest::default()
                 .mode(EmitJobMode::ConstTps { tps: 30 })

From 7d155043857acef9cc3ec8d4da49e13a9440f515 Mon Sep 17 00:00:00 2001
From: Zekun Li 
Date: Mon, 5 Jun 2023 14:21:04 -0700
Subject: [PATCH 101/200] [dag] reliable broadcast

This commit introduces an abstracted reliable broadcast concept, it's responsible to keep trying sending message until
either it aggregates enough ack or it's cancelled.
---
 Cargo.lock                                    |   9 +-
 consensus/src/dag/mod.rs                      |   8 +
 consensus/src/dag/reliable_broadcast.rs       |  98 +++++++++++
 consensus/src/dag/tests/mod.rs                |   4 +
 .../src/dag/tests/reliable_broadcast_tests.rs | 153 ++++++++++++++++++
 consensus/src/lib.rs                          |   1 +
 consensus/src/network_interface.rs            |   4 +
 7 files changed, 273 insertions(+), 4 deletions(-)
 create mode 100644 consensus/src/dag/mod.rs
 create mode 100644 consensus/src/dag/reliable_broadcast.rs
 create mode 100644 consensus/src/dag/tests/mod.rs
 create mode 100644 consensus/src/dag/tests/reliable_broadcast_tests.rs

diff --git a/Cargo.lock b/Cargo.lock
index d7db13a198390..658dd89aed005 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -9178,9 +9178,9 @@ dependencies = [
 
 [[package]]
 name = "once_cell"
-version = "1.13.1"
+version = "1.18.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "074864da206b4973b84eb91683020dbefd6a8c3f0f38e054d93954e891935e4e"
+checksum = "dd8b5dd2ae5ed71462c540258bedcb51965123ad7e7ccf4b9a8cafaa4a63576d"
 
 [[package]]
 name = "oorandom"
@@ -10362,10 +10362,11 @@ dependencies = [
 
 [[package]]
 name = "random_word"
-version = "0.3.0"
+version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "97b2bb830d03b36582fd6723a57d2451b9db74574d21c34db9d7122c96b24fa0"
+checksum = "1d0f7171155590e912ab907550240a5764c665388ab0a1e46d783a493e816ff3"
 dependencies = [
+ "once_cell",
  "rand 0.8.5",
 ]
 
diff --git a/consensus/src/dag/mod.rs b/consensus/src/dag/mod.rs
new file mode 100644
index 0000000000000..1184204db0b9a
--- /dev/null
+++ b/consensus/src/dag/mod.rs
@@ -0,0 +1,8 @@
+// Copyright © Aptos Foundation
+// Parts of the project are originally copyright © Meta Platforms, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+#[allow(dead_code)]
+mod reliable_broadcast;
+#[cfg(test)]
+mod tests;
diff --git a/consensus/src/dag/reliable_broadcast.rs b/consensus/src/dag/reliable_broadcast.rs
new file mode 100644
index 0000000000000..91f56d4cc4de4
--- /dev/null
+++ b/consensus/src/dag/reliable_broadcast.rs
@@ -0,0 +1,98 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::network_interface::ConsensusMsg;
+use aptos_consensus_types::common::Author;
+use async_trait::async_trait;
+use futures::{stream::FuturesUnordered, StreamExt};
+use std::{future::Future, sync::Arc, time::Duration};
+use tokio::sync::oneshot;
+
+pub trait DAGMessage: Sized + Clone {
+    fn from_network_message(msg: ConsensusMsg) -> anyhow::Result;
+
+    fn into_network_message(self) -> ConsensusMsg;
+}
+
+pub trait BroadcastStatus {
+    type Message: DAGMessage;
+    type Ack: DAGMessage;
+    type Aggregated;
+
+    fn empty(validators: Vec) -> Self;
+
+    fn add(&mut self, peer: Author, ack: Self::Ack) -> anyhow::Result>;
+}
+
+#[async_trait]
+pub trait DAGNetworkSender: Send + Sync {
+    async fn send_rpc(
+        &self,
+        receiver: Author,
+        message: ConsensusMsg,
+        timeout: Duration,
+    ) -> anyhow::Result;
+}
+
+pub struct ReliableBroadcast {
+    validators: Vec,
+    network_sender: Arc,
+}
+
+impl ReliableBroadcast {
+    pub fn new(validators: Vec, network_sender: Arc) -> Self {
+        Self {
+            validators,
+            network_sender,
+        }
+    }
+
+    pub fn broadcast(
+        &self,
+        message: S::Message,
+        return_tx: oneshot::Sender,
+        mut cancel_rx: oneshot::Receiver<()>,
+    ) -> impl Future {
+        let receivers: Vec<_> = self.validators.clone();
+        let network_message = message.into_network_message();
+        let network_sender = self.network_sender.clone();
+        async move {
+            let mut aggregating = S::empty(receivers.clone());
+            let mut fut = FuturesUnordered::new();
+            let send_message = |receiver, message| {
+                let network_sender = network_sender.clone();
+                async move {
+                    (
+                        receiver,
+                        network_sender
+                            .send_rpc(receiver, message, Duration::from_millis(500))
+                            .await,
+                    )
+                }
+            };
+            for receiver in receivers {
+                fut.push(send_message(receiver, network_message.clone()));
+            }
+            loop {
+                tokio::select! {
+                    Some((receiver, result)) = fut.next() => {
+                        match result {
+                            Ok(msg) =>  {
+                                if let Ok(ack) = S::Ack::from_network_message(msg) {
+                                    if let Ok(Some(aggregated)) = aggregating.add(receiver, ack) {
+                                        let _ = return_tx.send(aggregated);
+                                        return;
+                                    }
+                                }
+                            },
+                            Err(_) => fut.push(send_message(receiver, network_message.clone())),
+                        }
+                    }
+                    _ = &mut cancel_rx => {
+                        return;
+                    }
+                }
+            }
+        }
+    }
+}
diff --git a/consensus/src/dag/tests/mod.rs b/consensus/src/dag/tests/mod.rs
new file mode 100644
index 0000000000000..2ab720ad81960
--- /dev/null
+++ b/consensus/src/dag/tests/mod.rs
@@ -0,0 +1,4 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+mod reliable_broadcast_tests;
diff --git a/consensus/src/dag/tests/reliable_broadcast_tests.rs b/consensus/src/dag/tests/reliable_broadcast_tests.rs
new file mode 100644
index 0000000000000..a606a86579bd1
--- /dev/null
+++ b/consensus/src/dag/tests/reliable_broadcast_tests.rs
@@ -0,0 +1,153 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::{
+    dag::reliable_broadcast::{BroadcastStatus, DAGMessage, DAGNetworkSender, ReliableBroadcast},
+    network_interface::ConsensusMsg,
+};
+use anyhow::bail;
+use aptos_consensus_types::common::Author;
+use aptos_infallible::Mutex;
+use aptos_types::validator_verifier::random_validator_verifier;
+use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
+use std::{
+    collections::{hash_map::Entry, HashMap, HashSet},
+    sync::Arc,
+    time::Duration,
+};
+use tokio::sync::oneshot;
+
+#[derive(Serialize, Deserialize, Clone)]
+struct TestMessage(Vec);
+
+impl DAGMessage for TestMessage {
+    fn from_network_message(msg: ConsensusMsg) -> anyhow::Result {
+        match msg {
+            ConsensusMsg::DAGTestMessage(payload) => Ok(Self(payload)),
+            _ => bail!("wrong message"),
+        }
+    }
+
+    fn into_network_message(self) -> ConsensusMsg {
+        ConsensusMsg::DAGTestMessage(self.0)
+    }
+}
+
+#[derive(Serialize, Deserialize, Clone)]
+struct TestAck;
+
+impl DAGMessage for TestAck {
+    fn from_network_message(_: ConsensusMsg) -> anyhow::Result {
+        Ok(TestAck)
+    }
+
+    fn into_network_message(self) -> ConsensusMsg {
+        ConsensusMsg::DAGTestMessage(vec![])
+    }
+}
+
+struct TestBroadcastStatus {
+    threshold: usize,
+    received: HashSet,
+}
+
+impl BroadcastStatus for TestBroadcastStatus {
+    type Ack = TestAck;
+    type Aggregated = HashSet;
+    type Message = TestMessage;
+
+    fn empty(receivers: Vec) -> Self {
+        Self {
+            threshold: receivers.len(),
+            received: HashSet::new(),
+        }
+    }
+
+    fn add(&mut self, peer: Author, _ack: Self::Ack) -> anyhow::Result> {
+        self.received.insert(peer);
+        if self.received.len() == self.threshold {
+            Ok(Some(self.received.clone()))
+        } else {
+            Ok(None)
+        }
+    }
+}
+
+struct TestDAGSender {
+    failures: Mutex>,
+    received: Mutex>,
+}
+
+impl TestDAGSender {
+    fn new(failures: HashMap) -> Self {
+        Self {
+            failures: Mutex::new(failures),
+            received: Mutex::new(HashMap::new()),
+        }
+    }
+}
+
+#[async_trait]
+impl DAGNetworkSender for TestDAGSender {
+    async fn send_rpc(
+        &self,
+        receiver: Author,
+        message: ConsensusMsg,
+        _timeout: Duration,
+    ) -> anyhow::Result {
+        match self.failures.lock().entry(receiver) {
+            Entry::Occupied(mut entry) => {
+                let count = entry.get_mut();
+                *count -= 1;
+                if *count == 0 {
+                    entry.remove();
+                }
+                bail!("simulated failure");
+            },
+            Entry::Vacant(_) => (),
+        };
+        self.received
+            .lock()
+            .insert(receiver, TestMessage::from_network_message(message)?);
+        Ok(ConsensusMsg::DAGTestMessage(vec![]))
+    }
+}
+
+#[tokio::test]
+async fn test_reliable_broadcast() {
+    let (_, validator_verifier) = random_validator_verifier(5, None, false);
+    let validators = validator_verifier.get_ordered_account_addresses();
+    let failures = HashMap::from([(validators[0], 1), (validators[2], 3)]);
+    let sender = Arc::new(TestDAGSender::new(failures));
+    let rb = ReliableBroadcast::new(validators.clone(), sender);
+    let message = TestMessage(vec![1, 2, 3]);
+    let (tx, rx) = oneshot::channel();
+    let (_cancel_tx, cancel_rx) = oneshot::channel();
+    tokio::spawn(rb.broadcast::(message, tx, cancel_rx));
+    assert_eq!(rx.await.unwrap(), validators.into_iter().collect());
+}
+
+#[tokio::test]
+async fn test_reliable_broadcast_cancel() {
+    let (_, validator_verifier) = random_validator_verifier(5, None, false);
+    let validators = validator_verifier.get_ordered_account_addresses();
+    let failures = HashMap::from([(validators[0], 1), (validators[2], 3)]);
+    let sender = Arc::new(TestDAGSender::new(failures));
+    let rb = ReliableBroadcast::new(validators.clone(), sender);
+    let message = TestMessage(vec![1, 2, 3]);
+
+    // explicit send cancel
+    let (tx, rx) = oneshot::channel();
+    let (cancel_tx, cancel_rx) = oneshot::channel();
+    cancel_tx.send(()).unwrap();
+    tokio::spawn(rb.broadcast::(message.clone(), tx, cancel_rx));
+    assert!(rx.await.is_err());
+
+    // implicit drop cancel
+    let (tx, rx) = oneshot::channel();
+    let (cancel_tx, cancel_rx) = oneshot::channel();
+    drop(cancel_tx);
+    tokio::spawn(rb.broadcast::(message, tx, cancel_rx));
+    assert!(rx.await.is_err());
+}
diff --git a/consensus/src/lib.rs b/consensus/src/lib.rs
index 88e735374cb09..51c0ccc45610d 100644
--- a/consensus/src/lib.rs
+++ b/consensus/src/lib.rs
@@ -17,6 +17,7 @@ extern crate core;
 
 mod block_storage;
 mod consensusdb;
+mod dag;
 mod epoch_manager;
 mod error;
 mod experimental;
diff --git a/consensus/src/network_interface.rs b/consensus/src/network_interface.rs
index 68b38adb28db1..ec1b26695b27f 100644
--- a/consensus/src/network_interface.rs
+++ b/consensus/src/network_interface.rs
@@ -61,6 +61,8 @@ pub enum ConsensusMsg {
     SignedBatchInfo(Box),
     /// Quorum Store: Broadcast a certified proof of store (a digest that received 2f+1 votes).
     ProofOfStoreMsg(Box),
+    #[cfg(test)]
+    DAGTestMessage(Vec),
 }
 
 /// Network type for consensus
@@ -83,6 +85,8 @@ impl ConsensusMsg {
             ConsensusMsg::BatchResponse(_) => "BatchResponse",
             ConsensusMsg::SignedBatchInfo(_) => "SignedBatchInfo",
             ConsensusMsg::ProofOfStoreMsg(_) => "ProofOfStoreMsg",
+            #[cfg(test)]
+            ConsensusMsg::DAGTestMessage(_) => "DAGTestMessage",
         }
     }
 }

From 9b104f3b1c456cb49aacea8468b43911ffa941df Mon Sep 17 00:00:00 2001
From: Balaji Arun 
Date: Wed, 7 Jun 2023 17:12:14 -0700
Subject: [PATCH 102/200] [terraform][gcp] ability to specify maintenance
 window (#8491)

---
 terraform/aptos-node-testnet/gcp/main.tf      |  2 ++
 terraform/aptos-node-testnet/gcp/variables.tf | 12 ++++++++++++
 terraform/aptos-node/gcp/cluster.tf           | 11 +++++++++++
 terraform/aptos-node/gcp/variables.tf         | 12 ++++++++++++
 4 files changed, 37 insertions(+)

diff --git a/terraform/aptos-node-testnet/gcp/main.tf b/terraform/aptos-node-testnet/gcp/main.tf
index 00b5de61353a6..2dd2c99b6b1b1 100644
--- a/terraform/aptos-node-testnet/gcp/main.tf
+++ b/terraform/aptos-node-testnet/gcp/main.tf
@@ -68,6 +68,8 @@ module "validator" {
   enable_monitoring      = var.enable_monitoring
   enable_node_exporter   = var.enable_prometheus_node_exporter
   monitoring_helm_values = var.monitoring_helm_values
+
+  gke_maintenance_policy = var.gke_maintenance_policy
 }
 
 locals {
diff --git a/terraform/aptos-node-testnet/gcp/variables.tf b/terraform/aptos-node-testnet/gcp/variables.tf
index 4ab008b1328dc..4e2a30cd30cae 100644
--- a/terraform/aptos-node-testnet/gcp/variables.tf
+++ b/terraform/aptos-node-testnet/gcp/variables.tf
@@ -201,3 +201,15 @@ variable "cluster_ipv4_cidr_block" {
   description = "The IP address range of the container pods in this cluster, in CIDR notation. See https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/container_cluster#cluster_ipv4_cidr_block"
   default     = ""
 }
+
+variable "gke_maintenance_policy" {
+  description = "The maintenance policy to use for the cluster. See https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/container_cluster#maintenance_policy"
+  type = object({
+    recurring_window = object({
+      start_time = string
+      end_time   = string
+      recurrence = string
+    })
+  })
+  default = null
+}
diff --git a/terraform/aptos-node/gcp/cluster.tf b/terraform/aptos-node/gcp/cluster.tf
index d36a71d781af6..66275bcf8eb0f 100644
--- a/terraform/aptos-node/gcp/cluster.tf
+++ b/terraform/aptos-node/gcp/cluster.tf
@@ -72,6 +72,17 @@ resource "google_container_cluster" "aptos" {
       }
     }
   }
+
+  maintenance_policy {
+    dynamic "recurring_window" {
+      for_each = var.gke_maintenance_policy.recurring_window != null ? [1] : []
+      content {
+        start_time = var.gke_maintenance_policy.recurring_window.start_time
+        end_time   = var.gke_maintenance_policy.recurring_window.end_time
+        recurrence = var.gke_maintenance_policy.recurring_window.recurrence
+      }
+    }
+  }
 }
 
 resource "google_container_node_pool" "utilities" {
diff --git a/terraform/aptos-node/gcp/variables.tf b/terraform/aptos-node/gcp/variables.tf
index 96b3911cc66d5..26c66d278939e 100644
--- a/terraform/aptos-node/gcp/variables.tf
+++ b/terraform/aptos-node/gcp/variables.tf
@@ -240,3 +240,15 @@ variable "num_fullnode_groups" {
   description = "The number of fullnode groups to create"
   default     = 1
 }
+
+variable "gke_maintenance_policy" {
+  description = "The maintenance policy to use for the cluster. See https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/container_cluster#maintenance_policy"
+  type = object({
+    recurring_window = object({
+      start_time = string
+      end_time   = string
+      recurrence = string
+    })
+  })
+  default = null
+}

From 2a063b56528a132d2bf81d4db6f65433b43ef074 Mon Sep 17 00:00:00 2001
From: Jin <128556004+0xjinn@users.noreply.github.com>
Date: Wed, 7 Jun 2023 18:02:07 -0700
Subject: [PATCH 103/200] [CLI] add account lookup by authentication key
 (#7820)

* add account lookup by authentication key

* fixed test and linting

* add e2e test for --auth-key option

* fix format and linting

* Require permission check before running determine-docker-build-metadata

* fix trigger condition for build jobs

* update changelog and run linter

---------

Co-authored-by: Stelian Ionescu 
Co-authored-by: geekflyer 
---
 crates/aptos/CHANGELOG.md                |  5 +++
 crates/aptos/e2e/cases/account.py        | 20 ++++++++++++
 crates/aptos/e2e/main.py                 |  7 ++++-
 crates/aptos/src/account/key_rotation.rs | 21 +++++++++++--
 crates/aptos/src/common/types.rs         | 39 ++++++++++++++++++++++++
 crates/aptos/src/test/mod.rs             | 13 ++++----
 6 files changed, 95 insertions(+), 10 deletions(-)

diff --git a/crates/aptos/CHANGELOG.md b/crates/aptos/CHANGELOG.md
index 1d77339eaf0aa..ba6df3898eadc 100644
--- a/crates/aptos/CHANGELOG.md
+++ b/crates/aptos/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 All notable changes to the Aptos CLI will be captured in this file. This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and the format set out by [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## In Progress
+### Added
+- Added account lookup by authentication key
+  - Example: `account lookup-address --auth-key {your_auth_key}`
+
 ## [2.0.1] - 2023/06/05
 ### Fixed
 - Updated txn expiration configuration for the faucet built into the CLI to make local testnet startup more reliable.
diff --git a/crates/aptos/e2e/cases/account.py b/crates/aptos/e2e/cases/account.py
index 5359c83ee8edd..1a4c91ec05d7e 100644
--- a/crates/aptos/e2e/cases/account.py
+++ b/crates/aptos/e2e/cases/account.py
@@ -60,3 +60,23 @@ def test_account_create(run_helper: RunHelper, test_name=None):
         raise TestError(
             f"Account {OTHER_ACCOUNT_ONE.account_address} has balance {balance}, expected 0"
         )
+
+
+@test_case
+def test_account_lookup_address(run_helper: RunHelper, test_name=None):
+    # Create the new account.
+    result_addr = run_helper.run_command(
+        test_name,
+        [
+            "aptos",
+            "account",
+            "lookup-address",
+            "--auth-key",
+            run_helper.get_account_info().account_address,  # initially the account address is the auth key
+        ],
+    )
+
+    if run_helper.get_account_info().account_address not in result_addr.stdout:
+        raise TestError(
+            f"lookup-address result does not match {run_helper.get_account_info().account_address}"
+        )
diff --git a/crates/aptos/e2e/main.py b/crates/aptos/e2e/main.py
index 04778b57710ca..040262871efc1 100644
--- a/crates/aptos/e2e/main.py
+++ b/crates/aptos/e2e/main.py
@@ -29,7 +29,11 @@
 import shutil
 import sys
 
-from cases.account import test_account_create, test_account_fund_with_faucet
+from cases.account import (
+    test_account_create,
+    test_account_fund_with_faucet,
+    test_account_lookup_address,
+)
 from cases.init import test_init, test_metrics_accessible
 from common import Network
 from local_testnet import run_node, stop_node, wait_for_startup
@@ -105,6 +109,7 @@ def run_tests(run_helper):
     # Run account tests.
     test_account_fund_with_faucet(run_helper)
     test_account_create(run_helper)
+    test_account_lookup_address(run_helper)
 
 
 def main():
diff --git a/crates/aptos/src/account/key_rotation.rs b/crates/aptos/src/account/key_rotation.rs
index c330c4ac9b6da..9937307ad3d78 100644
--- a/crates/aptos/src/account/key_rotation.rs
+++ b/crates/aptos/src/account/key_rotation.rs
@@ -3,7 +3,8 @@
 
 use crate::common::{
     types::{
-        account_address_from_public_key, CliCommand, CliConfig, CliError, CliTypedResult,
+        account_address_from_auth_key, account_address_from_public_key,
+        AuthenticationKeyInputOptions, CliCommand, CliConfig, CliError, CliTypedResult,
         ConfigSearchMode, EncodingOptions, EncodingType, ExtractPublicKey, ParsePrivateKey,
         ProfileConfig, ProfileOptions, PublicKeyInputOptions, RestOptions, RotationProofChallenge,
         TransactionOptions, TransactionSummary,
@@ -20,7 +21,10 @@ use aptos_rest_client::{
     error::{AptosErrorResponse, RestError},
     Client,
 };
-use aptos_types::{account_address::AccountAddress, account_config::CORE_CODE_ADDRESS};
+use aptos_types::{
+    account_address::AccountAddress, account_config::CORE_CODE_ADDRESS,
+    transaction::authenticator::AuthenticationKey,
+};
 use async_trait::async_trait;
 use clap::Parser;
 use serde::{Deserialize, Serialize};
@@ -260,6 +264,9 @@ pub struct LookupAddress {
 
     #[clap(flatten)]
     pub(crate) rest_options: RestOptions,
+
+    #[clap(flatten)]
+    pub(crate) authentication_key_options: AuthenticationKeyInputOptions,
 }
 
 impl LookupAddress {
@@ -268,6 +275,11 @@ impl LookupAddress {
             .extract_public_key(self.encoding_options.encoding, &self.profile_options)
     }
 
+    pub(crate) fn auth_key(&self) -> CliTypedResult> {
+        self.authentication_key_options
+            .extract_auth_key(self.encoding_options.encoding)
+    }
+
     /// Builds a rest client
     fn rest_client(&self) -> CliTypedResult {
         self.rest_options.client(&self.profile_options)
@@ -284,7 +296,10 @@ impl CliCommand for LookupAddress {
         let rest_client = self.rest_client()?;
 
         // TODO: Support arbitrary auth key to support other types like multie25519
-        let address = account_address_from_public_key(&self.public_key()?);
+        let address = match self.auth_key()? {
+            Some(key) => account_address_from_auth_key(&key),
+            None => account_address_from_public_key(&self.public_key()?),
+        };
         Ok(lookup_address(&rest_client, address, true).await?)
     }
 }
diff --git a/crates/aptos/src/common/types.rs b/crates/aptos/src/common/types.rs
index f9dec4dc79c06..dcd1fe85adfed 100644
--- a/crates/aptos/src/common/types.rs
+++ b/crates/aptos/src/common/types.rs
@@ -621,6 +621,41 @@ pub struct EncodingOptions {
     pub encoding: EncodingType,
 }
 
+#[derive(Debug, Parser)]
+pub struct AuthenticationKeyInputOptions {
+    /// Authentication Key file input
+    #[clap(long, group = "authentication_key_input", parse(from_os_str))]
+    auth_key_file: Option,
+
+    /// Authentication key input
+    #[clap(long, group = "authentication_key_input")]
+    auth_key: Option,
+}
+
+impl AuthenticationKeyInputOptions {
+    pub fn extract_auth_key(
+        &self,
+        encoding: EncodingType,
+    ) -> CliTypedResult> {
+        if let Some(ref file) = self.auth_key_file {
+            Ok(Some(encoding.load_key("--auth-key-file", file.as_path())?))
+        } else if let Some(ref key) = self.auth_key {
+            let key = key.as_bytes().to_vec();
+            Ok(Some(encoding.decode_key("--auth-key", key)?))
+        } else {
+            Ok(None)
+        }
+    }
+
+    pub fn from_public_key(key: &Ed25519PublicKey) -> AuthenticationKeyInputOptions {
+        let auth_key = AuthenticationKey::ed25519(key);
+        AuthenticationKeyInputOptions {
+            auth_key: Some(auth_key.to_encoded_string().unwrap()),
+            auth_key_file: None,
+        }
+    }
+}
+
 #[derive(Debug, Parser)]
 pub struct PublicKeyInputOptions {
     /// Ed25519 Public key input file name
@@ -835,6 +870,10 @@ pub trait ExtractPublicKey {
 
 pub fn account_address_from_public_key(public_key: &Ed25519PublicKey) -> AccountAddress {
     let auth_key = AuthenticationKey::ed25519(public_key);
+    account_address_from_auth_key(&auth_key)
+}
+
+pub fn account_address_from_auth_key(auth_key: &AuthenticationKey) -> AccountAddress {
     AccountAddress::new(*auth_key.derived_address())
 }
 
diff --git a/crates/aptos/src/test/mod.rs b/crates/aptos/src/test/mod.rs
index d2d97cf7ad352..41751b6c1334a 100644
--- a/crates/aptos/src/test/mod.rs
+++ b/crates/aptos/src/test/mod.rs
@@ -12,12 +12,12 @@ use crate::{
     common::{
         init::{InitTool, Network},
         types::{
-            account_address_from_public_key, AccountAddressWrapper, ArgWithTypeVec, CliError,
-            CliTypedResult, EncodingOptions, EntryFunctionArguments, FaucetOptions, GasOptions,
-            KeyType, MoveManifestAccountWrapper, MovePackageDir, OptionalPoolAddressArgs,
-            PoolAddressArgs, PrivateKeyInputOptions, PromptOptions, PublicKeyInputOptions,
-            RestOptions, RngArgs, SaveFile, ScriptFunctionArguments, TransactionOptions,
-            TransactionSummary, TypeArgVec,
+            account_address_from_public_key, AccountAddressWrapper, ArgWithTypeVec,
+            AuthenticationKeyInputOptions, CliError, CliTypedResult, EncodingOptions,
+            EntryFunctionArguments, FaucetOptions, GasOptions, KeyType, MoveManifestAccountWrapper,
+            MovePackageDir, OptionalPoolAddressArgs, PoolAddressArgs, PrivateKeyInputOptions,
+            PromptOptions, PublicKeyInputOptions, RestOptions, RngArgs, SaveFile,
+            ScriptFunctionArguments, TransactionOptions, TransactionSummary, TypeArgVec,
         },
         utils::write_to_file,
     },
@@ -242,6 +242,7 @@ impl CliTestFramework {
             rest_options: self.rest_options(),
             encoding_options: Default::default(),
             profile_options: Default::default(),
+            authentication_key_options: AuthenticationKeyInputOptions::from_public_key(public_key),
         }
         .execute()
         .await

From 86fa3d7800d6c81f5727566b514c44af847bbf48 Mon Sep 17 00:00:00 2001
From: Stelian Ionescu 
Date: Wed, 7 Jun 2023 22:55:31 -0400
Subject: [PATCH 104/200] [TF] Add default for GKE maintenance window (#8585)

---
 terraform/aptos-node/gcp/variables.tf | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/terraform/aptos-node/gcp/variables.tf b/terraform/aptos-node/gcp/variables.tf
index 26c66d278939e..3028a1f7e2f77 100644
--- a/terraform/aptos-node/gcp/variables.tf
+++ b/terraform/aptos-node/gcp/variables.tf
@@ -250,5 +250,11 @@ variable "gke_maintenance_policy" {
       recurrence = string
     })
   })
-  default = null
+  default = {
+    recurring_window = {
+      start_time = "2023-06-01T14:00:00Z"
+      end_time   = "2023-06-01T18:00:00Z"
+      recurrence = "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"
+    }
+  }
 }

From 3e6ca81f6a93d71ea0f0b8f01f9d1daccbd19b7d Mon Sep 17 00:00:00 2001
From: David Wolinsky 
Date: Sat, 29 Apr 2023 20:03:53 -0700
Subject: [PATCH 105/200] [python] return int balance of coins

---
 ecosystem/python/sdk/aptos_sdk/async_client.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ecosystem/python/sdk/aptos_sdk/async_client.py b/ecosystem/python/sdk/aptos_sdk/async_client.py
index 0d413f477d351..a96464a969c55 100644
--- a/ecosystem/python/sdk/aptos_sdk/async_client.py
+++ b/ecosystem/python/sdk/aptos_sdk/async_client.py
@@ -95,7 +95,7 @@ async def account_balance(
             "0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>",
             ledger_version,
         )
-        return resource["data"]["coin"]["value"]
+        return int(resource["data"]["coin"]["value"])
 
     async def account_sequence_number(
         self, account_address: AccountAddress, ledger_version: int = None

From 4a6caffdd7f4f35af1d0014267d863986f37cbc9 Mon Sep 17 00:00:00 2001
From: David Wolinsky 
Date: Sat, 29 Apr 2023 20:04:32 -0700
Subject: [PATCH 106/200] [python] async sleep for async calls

---
 ecosystem/python/sdk/aptos_sdk/async_client.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/ecosystem/python/sdk/aptos_sdk/async_client.py b/ecosystem/python/sdk/aptos_sdk/async_client.py
index a96464a969c55..8238f6c708f8a 100644
--- a/ecosystem/python/sdk/aptos_sdk/async_client.py
+++ b/ecosystem/python/sdk/aptos_sdk/async_client.py
@@ -1,6 +1,7 @@
 # Copyright © Aptos Foundation
 # SPDX-License-Identifier: Apache-2.0
 
+import asyncio
 import time
 from typing import Any, Dict, List, Optional
 
@@ -323,7 +324,7 @@ async def wait_for_transaction(self, txn_hash: str) -> None:
             assert (
                 count < self.client_config.transaction_wait_in_seconds
             ), f"transaction {txn_hash} timed out"
-            time.sleep(1)
+            await asyncio.sleep(1)
             count += 1
         response = await self.client.get(
             f"{self.base_url}/transactions/by_hash/{txn_hash}"

From 7328c7b3b91beb162013cca9a0f6511a8aae86a4 Mon Sep 17 00:00:00 2001
From: David Wolinsky 
Date: Sat, 29 Apr 2023 20:06:02 -0700
Subject: [PATCH 107/200] [python] use aptos_account::transfer instead of
 coin::transfer

---
 ecosystem/python/sdk/aptos_sdk/async_client.py | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/ecosystem/python/sdk/aptos_sdk/async_client.py b/ecosystem/python/sdk/aptos_sdk/async_client.py
index 8238f6c708f8a..3b0b0460365ca 100644
--- a/ecosystem/python/sdk/aptos_sdk/async_client.py
+++ b/ecosystem/python/sdk/aptos_sdk/async_client.py
@@ -21,7 +21,6 @@
     TransactionArgument,
     TransactionPayload,
 )
-from .type_tag import StructTag, TypeTag
 
 U64_MAX = 18446744073709551615
 
@@ -412,8 +411,8 @@ async def transfer(
 
         payload = {
             "type": "entry_function_payload",
-            "function": "0x1::coin::transfer",
-            "type_arguments": ["0x1::aptos_coin::AptosCoin"],
+            "function": "0x1::aptos_account::transfer",
+            "type_arguments": [],
             "arguments": [
                 f"{recipient}",
                 str(amount),
@@ -431,9 +430,9 @@ async def bcs_transfer(
         ]
 
         payload = EntryFunction.natural(
-            "0x1::coin",
+            "0x1::aptos_account",
             "transfer",
-            [TypeTag(StructTag.from_str("0x1::aptos_coin::AptosCoin"))],
+            [],
             transaction_arguments,
         )
 

From 5361c1b86005ce82b1e926ecdd728229e55849e8 Mon Sep 17 00:00:00 2001
From: David Wolinsky 
Date: Wed, 17 May 2023 23:34:48 -0700
Subject: [PATCH 108/200] [python] expose payload generators for token client

---
 .../sdk/aptos_sdk/aptos_token_client.py       | 66 ++++++++++++++++---
 1 file changed, 56 insertions(+), 10 deletions(-)

diff --git a/ecosystem/python/sdk/aptos_sdk/aptos_token_client.py b/ecosystem/python/sdk/aptos_sdk/aptos_token_client.py
index 330e0591783f3..777eef2f51b68 100644
--- a/ecosystem/python/sdk/aptos_sdk/aptos_token_client.py
+++ b/ecosystem/python/sdk/aptos_sdk/aptos_token_client.py
@@ -338,9 +338,7 @@ async def read_object(self, address: AccountAddress) -> ReadObject:
                 resources[resource_obj] = resource_obj.parse(resource["data"])
         return ReadObject(resources)
 
-    async def create_collection(
-        self,
-        creator: Account,
+    def create_collection_payload(
         description: str,
         max_supply: int,
         name: str,
@@ -356,7 +354,7 @@ async def create_collection(
         tokens_freezable_by_creator: bool,
         royalty_numerator: int,
         royalty_denominator: int,
-    ) -> str:
+    ) -> TransactionPayload:
         transaction_arguments = [
             TransactionArgument(description, Serializer.str),
             TransactionArgument(max_supply, Serializer.u64),
@@ -382,20 +380,56 @@ async def create_collection(
             transaction_arguments,
         )
 
+        return TransactionPayload(payload)
+
+    async def create_collection(
+        self,
+        creator: Account,
+        description: str,
+        max_supply: int,
+        name: str,
+        uri: str,
+        mutable_description: bool,
+        mutable_royalty: bool,
+        mutable_uri: bool,
+        mutable_token_description: bool,
+        mutable_token_name: bool,
+        mutable_token_properties: bool,
+        mutable_token_uri: bool,
+        tokens_burnable_by_creator: bool,
+        tokens_freezable_by_creator: bool,
+        royalty_numerator: int,
+        royalty_denominator: int,
+    ) -> str:
+        payload = create_collection_payload(
+            description,
+            max_supply,
+            name,
+            uri,
+            mutable_description,
+            mutable_royalty,
+            mutable_uri,
+            mutable_token_description,
+            mutable_token_name,
+            mutable_token_properties,
+            mutable_token_uri,
+            tokens_burnable_by_creator,
+            tokens_freezable_by_creator,
+            royalty_numerator,
+            royalty_denominator,
+        )
         signed_transaction = await self.client.create_bcs_signed_transaction(
-            creator, TransactionPayload(payload)
+            creator, payload
         )
         return await self.client.submit_bcs_transaction(signed_transaction)
 
-    async def mint_token(
-        self,
-        creator: Account,
+    def mint_token_payload(
         collection: str,
         description: str,
         name: str,
         uri: str,
         properties: PropertyMap,
-    ) -> str:
+    ) -> TransactionPayload:
         (property_names, property_types, property_values) = properties.to_tuple()
         transaction_arguments = [
             TransactionArgument(collection, Serializer.str),
@@ -420,8 +454,20 @@ async def mint_token(
             transaction_arguments,
         )
 
+        return TransactionPayload(payload)
+
+    async def mint_token(
+        self,
+        creator: Account,
+        collection: str,
+        description: str,
+        name: str,
+        uri: str,
+        properties: PropertyMap,
+    ) -> str:
+        payload = mint_token_payload(collection, description, name, uri, properties)
         signed_transaction = await self.client.create_bcs_signed_transaction(
-            creator, TransactionPayload(payload)
+            creator, payload
         )
         return await self.client.submit_bcs_transaction(signed_transaction)
 

From 1919e2d2dfd315bafaaf4ad4b5aa447235ebddc0 Mon Sep 17 00:00:00 2001
From: David Wolinsky 
Date: Sat, 29 Apr 2023 20:07:55 -0700
Subject: [PATCH 109/200] [python] support inserting sequence numbers in
 transaction helpers

---
 .../python/sdk/aptos_sdk/async_client.py      |  29 +-
 ecosystem/python/sdk/examples/common.py       |   6 +
 .../sdk/examples/transaction-batching.py      | 422 +++++++++++-------
 3 files changed, 284 insertions(+), 173 deletions(-)

diff --git a/ecosystem/python/sdk/aptos_sdk/async_client.py b/ecosystem/python/sdk/aptos_sdk/async_client.py
index 3b0b0460365ca..15e3d4284b962 100644
--- a/ecosystem/python/sdk/aptos_sdk/async_client.py
+++ b/ecosystem/python/sdk/aptos_sdk/async_client.py
@@ -377,11 +377,19 @@ async def create_multi_agent_bcs_transaction(
         return SignedTransaction(raw_transaction.inner(), authenticator)
 
     async def create_bcs_transaction(
-        self, sender: Account, payload: TransactionPayload
+        self,
+        sender: Account,
+        payload: TransactionPayload,
+        sequence_number: Optional[int] = None,
     ) -> RawTransaction:
+        sequence_number = (
+            sequence_number
+            if sequence_number is not None
+            else await self.account_sequence_number(sender.address())
+        )
         return RawTransaction(
             sender.address(),
-            await self.account_sequence_number(sender.address()),
+            sequence_number,
             payload,
             self.client_config.max_gas_amount,
             self.client_config.gas_unit_price,
@@ -390,9 +398,14 @@ async def create_bcs_transaction(
         )
 
     async def create_bcs_signed_transaction(
-        self, sender: Account, payload: TransactionPayload
+        self,
+        sender: Account,
+        payload: TransactionPayload,
+        sequence_number: Optional[int] = None,
     ) -> SignedTransaction:
-        raw_transaction = await self.create_bcs_transaction(sender, payload)
+        raw_transaction = await self.create_bcs_transaction(
+            sender, payload, sequence_number
+        )
         signature = sender.sign(raw_transaction.keyed())
         authenticator = Authenticator(
             Ed25519Authenticator(sender.public_key(), signature)
@@ -422,7 +435,11 @@ async def transfer(
 
     # :!:>bcs_transfer
     async def bcs_transfer(
-        self, sender: Account, recipient: AccountAddress, amount: int
+        self,
+        sender: Account,
+        recipient: AccountAddress,
+        amount: int,
+        sequence_number: Optional[int] = None,
     ) -> str:
         transaction_arguments = [
             TransactionArgument(recipient, Serializer.struct),
@@ -437,7 +454,7 @@ async def bcs_transfer(
         )
 
         signed_transaction = await self.create_bcs_signed_transaction(
-            sender, TransactionPayload(payload)
+            sender, TransactionPayload(payload), sequence_number=sequence_number
         )
         return await self.submit_bcs_transaction(signed_transaction)
 
diff --git a/ecosystem/python/sdk/examples/common.py b/ecosystem/python/sdk/examples/common.py
index b81711d057ecf..8272f249de443 100644
--- a/ecosystem/python/sdk/examples/common.py
+++ b/ecosystem/python/sdk/examples/common.py
@@ -9,3 +9,9 @@
     "APTOS_FAUCET_URL",
     "https://faucet.devnet.aptoslabs.com",
 )  # <:!:section_1
+
+NODE_URL = os.getenv("APTOS_NODE_URL", "http://127.0.0.1:8080/v1")
+FAUCET_URL = os.getenv(
+    "APTOS_FAUCET_URL",
+    "http://127.0.0.1:8081",
+)  # <:!:section_1
diff --git a/ecosystem/python/sdk/examples/transaction-batching.py b/ecosystem/python/sdk/examples/transaction-batching.py
index 4e5d02cfb9fbc..714707d2f19ff 100644
--- a/ecosystem/python/sdk/examples/transaction-batching.py
+++ b/ecosystem/python/sdk/examples/transaction-batching.py
@@ -2,26 +2,203 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import asyncio
-import logging
+import sys
 import time
+import typing
+from multiprocessing import Pipe, Process
+from multiprocessing.connection import Connection
 
 from aptos_sdk.account import Account
 from aptos_sdk.account_address import AccountAddress
+from aptos_sdk.account_sequence_number import AccountSequenceNumber
 from aptos_sdk.async_client import ClientConfig, FaucetClient, RestClient
-from aptos_sdk.authenticator import Authenticator, Ed25519Authenticator
 from aptos_sdk.bcs import Serializer
+from aptos_sdk.transaction_worker import TransactionWorker
 from aptos_sdk.transactions import (
     EntryFunction,
-    RawTransaction,
     SignedTransaction,
     TransactionArgument,
     TransactionPayload,
 )
-from aptos_sdk.type_tag import StructTag, TypeTag
 
 from .common import FAUCET_URL, NODE_URL
 
 
+class TransactionGenerator:
+    """
+    Demonstrate how one might make a harness for submitting transactions. This class just keeps
+    submitting the same transaction payload. In practice, this could be a queue, where new payloads
+    accumulate and are consumed by the call to next_transaction.
+
+    Todo: add tracking of transaction status to this and come up with some general logic to retry
+    or exit upon failure.
+    """
+
+    _client: RestClient
+    _recipient: AccountAddress
+    _offset: int
+    _remaining_transactions: int
+    _waiting_for_more = asyncio.Event
+    _complete = asyncio.Event
+    _lock = asyncio.Lock
+
+    def __init__(self, client: RestClient, recipient: AccountAddress):
+        self._client = client
+        self._recipient = recipient
+        self._waiting_for_more = asyncio.Event()
+        self._waiting_for_more.clear()
+        self._complete = asyncio.Event()
+        self._complete.set()
+        self._lock = asyncio.Lock()
+        self._remaining_transactions = 0
+
+    async def next_transaction(
+        self, sender: Account, sequence_number: int
+    ) -> SignedTransaction:
+        while self._remaining_transactions == 0:
+            await self._waiting_for_more.wait()
+
+        async with self._lock:
+            self._remaining_transactions -= 1
+            if self._remaining_transactions == 0:
+                self._waiting_for_more.clear()
+                self._complete.set()
+
+        return await transfer_transaction(
+            self._client, sender, sequence_number, self._recipient, 0
+        )
+
+    async def increase_transaction_count(self, number: int):
+        if number <= 0:
+            return
+
+        async with self._lock:
+            self._remaining_transactions += number
+            self._waiting_for_more.set()
+            self._complete.clear()
+
+    async def wait(self):
+        await self._complete.wait()
+
+
+class WorkerContainer:
+    _conn: Connection
+    _process: Process
+
+    def __init__(self, node_url: str, account: Account, recipient: AccountAddress):
+        (self._conn, conn) = Pipe()
+        self._process = Process(
+            target=Worker.run, args=(conn, node_url, account, recipient)
+        )
+
+    def get(self) -> typing.Any:
+        self._conn.recv()
+
+    def join(self):
+        self._process.join()
+
+    def put(self, value: typing.Any):
+        self._conn.send(value)
+
+    def start(self):
+        self._process.start()
+
+
+class Worker:
+    _conn: Connection
+    _rest_client: RestClient
+    _account: Account
+    _recipient: AccountAddress
+    _txn_generator: TransactionGenerator
+    _txn_worker: TransactionWorker
+
+    def __init__(
+        self,
+        conn: Connection,
+        node_url: str,
+        account: Account,
+        recipient: AccountAddress,
+    ):
+        self._conn = conn
+        self._rest_client = RestClient(node_url)
+        self._account = account
+        self._recipient = recipient
+        self._txn_generator = TransactionGenerator(self._rest_client, self._recipient)
+        self._txn_worker = TransactionWorker(
+            self._account, self._rest_client, self._txn_generator.next_transaction
+        )
+
+    def run(queue: Pipe, node_url: str, account: Account, recipient: AccountAddress):
+        worker = Worker(queue, node_url, account, recipient)
+        asyncio.run(worker.arun())
+
+    async def arun(self):
+        print(f"hello from {self._account.address()}", flush=True)
+        try:
+            self._txn_worker.start()
+
+            self._conn.send(True)
+            num_txns = self._conn.recv()
+
+            await self._txn_generator.increase_transaction_count(num_txns)
+
+            print(f"Increase txns from {self._account.address()}", flush=True)
+            self._conn.send(True)
+            self._conn.recv()
+
+            txn_hashes = []
+            while num_txns != 0:
+                num_txns -= 1
+                (
+                    sequence_number,
+                    txn_hash,
+                    exception,
+                ) = await self._txn_worker.next_processed_transaction()
+                if exception:
+                    print(
+                        f"Account {self._txn_worker.account()}, transaction {sequence_number} submission failed: {exception}"
+                    )
+                else:
+                    txn_hashes.append(txn_hash)
+
+            print(f"Submit txns from {self._account.address()}", flush=True)
+            self._conn.send(True)
+            self._conn.recv()
+
+            for txn_hash in txn_hashes:
+                await self._rest_client.wait_for_transaction(txn_hash)
+
+            await self._rest_client.close()
+            print(f"Verified txns from {self._account.address()}", flush=True)
+            self._conn.send(True)
+        except Exception as e:
+            print(e)
+            sys.stdout.flush()
+
+
+async def transfer_transaction(
+    client: RestClient,
+    sender: Account,
+    sequence_number: int,
+    recipient: AccountAddress,
+    amount: int,
+) -> str:
+    transaction_arguments = [
+        TransactionArgument(recipient, Serializer.struct),
+        TransactionArgument(amount, Serializer.u64),
+    ]
+    payload = EntryFunction.natural(
+        "0x1::aptos_account",
+        "transfer",
+        [],
+        transaction_arguments,
+    )
+
+    return await client.create_bcs_signed_transaction(
+        sender, TransactionPayload(payload), sequence_number
+    )
+
+
 async def main():
     client_config = ClientConfig()
     # Toggle to benchmark
@@ -30,202 +207,113 @@ async def main():
     rest_client = RestClient(NODE_URL, client_config)
     faucet_client = FaucetClient(FAUCET_URL, rest_client)
 
-    num_accounts = 5
-    read_amplification = 1000
-    first_pass = 100
+    num_accounts = 8
+    transactions = 1000
     start = time.time()
 
     print("Starting...")
 
     accounts = []
-    recipient_accounts = []
-    for _ in range(num_accounts):
+    recipients = []
+
+    for account in range(num_accounts):
+        recipients.append(Account.generate())
         accounts.append(Account.generate())
-        recipient_accounts.append(Account.generate())
 
     last = time.time()
     print(f"Accounts generated at {last - start}")
 
-    funds = []
-    for account in accounts:
-        funds.append(faucet_client.fund_account(account.address(), 100_000_000))
-    for account in recipient_accounts:
-        funds.append(faucet_client.fund_account(account.address(), 0))
-    await asyncio.gather(*funds)
+    source = Account.generate()
+    await faucet_client.fund_account(source.address(), 100_000_000 * num_accounts)
+    balance = int(await rest_client.account_balance(source.address()))
 
-    print(f"Funded accounts at {time.time() - start} {time.time() - last}")
+    per_node_balance = balance // (num_accounts + 1)
+    account_sequence_number = AccountSequenceNumber(rest_client, source.address())
+
+    print(f"Initial account funded at {time.time() - start} {time.time() - last}")
     last = time.time()
 
-    balances = []
-    for _ in range(read_amplification):
-        for account in accounts:
-            balances.append(rest_client.account_balance(account.address()))
-    await asyncio.gather(*balances)
+    all_accounts = list(map(lambda account: (account.address(), True), accounts))
+    all_accounts.extend(map(lambda account: (account.address(), False), recipients))
 
-    print(f"Accounts checked at {time.time() - start} {time.time() - last}")
-    last = time.time()
+    txns = []
+    txn_hashes = []
 
-    account_sequence_numbers = []
-    await_account_sequence_numbers = []
-    for account in accounts:
-        account_sequence_number = AccountSequenceNumber(rest_client, account.address())
-        await_account_sequence_numbers.append(account_sequence_number.initialize())
-        account_sequence_numbers.append(account_sequence_number)
-    await asyncio.gather(*await_account_sequence_numbers)
+    for (account, fund) in all_accounts:
+        sequence_number = await account_sequence_number.next_sequence_number(
+            block=False
+        )
+        if sequence_number is None:
+            txn_hashes.extend(await asyncio.gather(*txns))
+            txns = []
+            sequence_number = await account_sequence_number.next_sequence_number()
+        amount = per_node_balance if fund else 0
+        txn = await transfer_transaction(
+            rest_client, source, sequence_number, account, amount
+        )
+        txns.append(rest_client.submit_bcs_transaction(txn))
+
+    txn_hashes.extend(await asyncio.gather(*txns))
+    for txn_hash in txn_hashes:
+        await rest_client.wait_for_transaction(txn_hash)
+    await account_sequence_number.synchronize()
 
-    print(f"Accounts initialized at {time.time() - start} {time.time() - last}")
+    print(f"Funded all accounts at {time.time() - start} {time.time() - last}")
     last = time.time()
 
-    txn_hashes = []
-    for _ in range(first_pass):
-        for idx in range(num_accounts):
-            sender = accounts[idx]
-            recipient = recipient_accounts[idx].address()
-            sequence_number = await account_sequence_numbers[idx].next_sequence_number()
-            txn_hash = transfer(rest_client, sender, recipient, sequence_number, 1)
-            txn_hashes.append(txn_hash)
-    txn_hashes = await asyncio.gather(*txn_hashes)
+    balances = []
+    for account in accounts:
+        balances.append(rest_client.account_balance(account.address()))
+    await asyncio.gather(*balances)
 
-    print(f"Transactions submitted at {time.time() - start} {time.time() - last}")
+    print(f"Accounts checked at {time.time() - start} {time.time() - last}")
     last = time.time()
 
-    wait_for = []
-    for txn_hash in txn_hashes:
-        wait_for.append(account_sequence_number.synchronize())
-    await asyncio.gather(*wait_for)
+    workers = []
+    for (account, recipient) in zip(accounts, recipients):
+        workers.append(WorkerContainer(NODE_URL, account, recipient.address()))
+        workers[-1].start()
 
-    print(f"Transactions committed at {time.time() - start} {time.time() - last}")
-    last = time.time()
+    for worker in workers:
+        worker.get()
 
-    await rest_client.close()
+    print(f"Workers started at {time.time() - start} {time.time() - last}")
+    last = time.time()
 
+    to_take = (transactions // num_accounts) + (
+        1 if transactions % num_accounts != 0 else 0
+    )
+    remaining_transactions = transactions
+    for worker in workers:
+        taking = min(to_take, remaining_transactions)
+        remaining_transactions -= taking
+        worker.put(taking)
 
-class AccountSequenceNumber:
-    """
-    A managed wrapper around sequence numbers that implements the trivial flow control used by the
-    Aptos faucet:
-    * Submit up to 50 transactions per account in parallel with a timeout of 20 seconds
-    * If local assumes 50 are in flight, determine the actual committed state from the network
-    * If there are less than 50 due to some being committed, adjust the window
-    * If 50 are in flight Wait .1 seconds before re-evaluating
-    * If ever waiting more than 30 seconds restart the sequence number to the current on-chain state
-
-    Assumptions:
-    * Accounts are expected to be managed by a single AccountSequenceNumber and not used otherwise.
-    * They are initialized to the current on-chain state, so if there are already transactions in flight, they make take some time to reset.
-    * Accounts are automatically initialized if not explicitly
-    *
-    """
+    for worker in workers:
+        worker.get()
 
-    client: RestClient
-    account: AccountAddress
-    last_committed_number: int
-    current_number: int
-    maximum_in_flight: int = 50
-    lock = asyncio.Lock
-    sleep_time = 0.01
-    maximum_wait_time = 30
-
-    def __init__(self, client: RestClient, account: AccountAddress):
-        self.client = client
-        self.account = account
-        self.last_uncommitted_number = None
-        self.current_number = None
-        self.lock = asyncio.Lock()
-
-    async def next_sequence_number(self) -> int:
-        await self.lock.acquire()
-        try:
-            if self.last_uncommitted_number is None or self.current_number is None:
-                await self.initialize()
-
-            if (
-                self.current_number - self.last_uncommitted_number
-                >= self.maximum_in_flight
-            ):
-                await self.__update()
-
-                start_time = time.time()
-                while (
-                    self.last_uncommitted_number - self.current_number
-                    >= self.maximum_in_flight
-                ):
-                    asyncio.sleep(self.sleep_time)
-                    if time.time() - start_time > self.maximum_wait_time:
-                        logging.warn(
-                            f"Waited over 30 seconds for a transaction to commit, resyncing {self.account.address()}"
-                        )
-                        await self.__initialize()
-                    else:
-                        await self.__update()
-
-            next_number = self.current_number
-            self.current_number += 1
-        finally:
-            self.lock.release()
-
-        return next_number
-
-    async def initialize(self):
-        self.current_number = await self.__current_sequence_number()
-        self.last_uncommitted_number = self.current_number
-
-    async def synchronize(self):
-        if self.last_uncommitted_number == self.current_number:
-            return
+    print(f"Transactions submitted at {time.time() - start} {time.time() - last}")
+    last = time.time()
 
-        await self.__update()
-        start_time = time.time()
-        while self.last_uncommitted_number != self.current_number:
-            if time.time() - start_time > self.maximum_wait_time:
-                logging.warn(
-                    f"Waited over 30 seconds for a transaction to commit, resyncing {self.account.address()}"
-                )
-                await self.__initialize()
-            else:
-                await asyncio.sleep(self.sleep_time)
-                await self.__update()
+    for worker in workers:
+        worker.put(True)
 
-    async def __update(self):
-        self.last_uncommitted_number = await self.__current_sequence_number()
-        return self.last_uncommitted_number
+    for worker in workers:
+        worker.get()
 
-    async def __current_sequence_number(self) -> int:
-        return await self.client.account_sequence_number(self.account)
+    print(f"Transactions processed at {time.time() - start} {time.time() - last}")
+    last = time.time()
 
+    for worker in workers:
+        worker.put(True)
 
-async def transfer(
-    client: RestClient,
-    sender: Account,
-    recipient: AccountAddress,
-    sequence_number: int,
-    amount: int,
-):
-    transaction_arguments = [
-        TransactionArgument(recipient, Serializer.struct),
-        TransactionArgument(amount, Serializer.u64),
-    ]
-    payload = EntryFunction.natural(
-        "0x1::coin",
-        "transfer",
-        [TypeTag(StructTag.from_str("0x1::aptos_coin::AptosCoin"))],
-        transaction_arguments,
-    )
+    for worker in workers:
+        worker.get()
 
-    raw_transaction = RawTransaction(
-        sender.address(),
-        sequence_number,
-        TransactionPayload(payload),
-        client.client_config.max_gas_amount,
-        client.client_config.gas_unit_price,
-        int(time.time()) + client.client_config.expiration_ttl,
-        await client.chain_id(),
-    )
+    print(f"Transactions verified at {time.time() - start} {time.time() - last}")
+    last = time.time()
 
-    signature = sender.sign(raw_transaction.keyed())
-    authenticator = Authenticator(Ed25519Authenticator(sender.public_key(), signature))
-    signed_transaction = SignedTransaction(raw_transaction, authenticator)
-    return await client.submit_bcs_transaction(signed_transaction)
+    await rest_client.close()
 
 
 if __name__ == "__main__":

From 7a914c8f776263f3980c10bcff475d6af8ae139d Mon Sep 17 00:00:00 2001
From: David Wolinsky 
Date: Sat, 29 Apr 2023 20:10:53 -0700
Subject: [PATCH 110/200] [python] add a transaction management layer

This provides a framework for managing as many transactions from a
single account at once
* The AccountSequenceNumber allocates up to 100 outstanding sequence numbers to maximize the number of concurrent transactions in the happy path.
* The transaction manager provides async workers that push a transaction from submission through to validating completion
Together they provide the basic harness for scaling transaction
submission on the Aptos blockchain from a single account.
---
 .../sdk/aptos_sdk/account_sequence_number.py  | 178 ++++++++++++++
 .../sdk/aptos_sdk/transaction_worker.py       | 225 ++++++++++++++++++
 2 files changed, 403 insertions(+)
 create mode 100644 ecosystem/python/sdk/aptos_sdk/account_sequence_number.py
 create mode 100644 ecosystem/python/sdk/aptos_sdk/transaction_worker.py

diff --git a/ecosystem/python/sdk/aptos_sdk/account_sequence_number.py b/ecosystem/python/sdk/aptos_sdk/account_sequence_number.py
new file mode 100644
index 0000000000000..266a25047d708
--- /dev/null
+++ b/ecosystem/python/sdk/aptos_sdk/account_sequence_number.py
@@ -0,0 +1,178 @@
+# Copyright © Aptos Foundation
+# SPDX-License-Identifier: Apache-2.0
+import asyncio
+import logging
+import time
+from typing import Optional
+
+from aptos_sdk.account_address import AccountAddress
+from aptos_sdk.async_client import RestClient
+
+
+class AccountSequenceNumber:
+    """
+    A managed wrapper around sequence numbers that implements the trivial flow control used by the
+    Aptos faucet:
+    * Submit up to 50 transactions per account in parallel with a timeout of 20 seconds
+    * If local assumes 50 are in flight, determine the actual committed state from the network
+    * If there are less than 50 due to some being committed, adjust the window
+    * If 50 are in flight Wait .1 seconds before re-evaluating
+    * If ever waiting more than 30 seconds restart the sequence number to the current on-chain state
+    Assumptions:
+    * Accounts are expected to be managed by a single AccountSequenceNumber and not used otherwise.
+    * They are initialized to the current on-chain state, so if there are already transactions in
+      flight, they make take some time to reset.
+    * Accounts are automatically initialized if not explicitly
+
+    Notes:
+    * This is co-routine safe, that is many async tasks can be reading from this concurrently.
+    * The synchronize method will create a barrier that prevents additional next_sequence_number
+      calls until it is complete.
+    * This only manages the distribution of sequence numbers it does not help handle transaction
+      failures.
+    """
+
+    client: RestClient
+    account: AccountAddress
+    lock = asyncio.Lock
+
+    maximum_in_flight: int = 100
+    maximum_wait_time = 30
+    sleep_time = 0.01
+
+    last_committed_number: Optional[int]
+    current_number: Optional[int]
+
+    def __init__(self, client: RestClient, account: AccountAddress):
+        self.client = client
+        self.account = account
+        self.lock = asyncio.Lock()
+
+        self.last_uncommitted_number = None
+        self.current_number = None
+
+    async def next_sequence_number(self, block: bool = True) -> Optional[int]:
+        """
+        Returns the next sequence number available on this account. This leverages a lock to
+        guarantee first-in, first-out ordering of requests.
+        """
+        await self.lock.acquire()
+        try:
+            if self.last_uncommitted_number is None or self.current_number is None:
+                await self.initialize()
+            if (
+                self.current_number - self.last_uncommitted_number
+                >= self.maximum_in_flight
+            ):
+                await self.__update()
+                start_time = time.time()
+                while (
+                    self.current_number - self.last_uncommitted_number
+                    >= self.maximum_in_flight
+                ):
+                    if not block:
+                        return None
+                    await asyncio.sleep(self.sleep_time)
+                    if time.time() - start_time > self.maximum_wait_time:
+                        logging.warn(
+                            f"Waited over 30 seconds for a transaction to commit, resyncing {self.account.address().hex()}"
+                        )
+                        await self.initialize()
+                    else:
+                        await self.__update()
+            next_number = self.current_number
+            self.current_number += 1
+        finally:
+            self.lock.release()
+        return next_number
+
+    async def initialize(self):
+        """Optional initializer. called by next_sequence_number if not called prior."""
+        self.current_number = await self.__current_sequence_number()
+        self.last_uncommitted_number = self.current_number
+
+    async def synchronize(self):
+        """
+        Poll the network until all submitted transactions have either been committed or until
+        the maximum wait time has elapsed. This will prevent any calls to next_sequence_number
+        until this called has returned.
+        """
+        if self.last_uncommitted_number == self.current_number:
+            return
+
+        await self.lock.acquire()
+        try:
+            await self.__update()
+            start_time = time.time()
+            while self.last_uncommitted_number != self.current_number:
+                print(f"{self.last_uncommitted_number} {self.current_number}")
+                if time.time() - start_time > self.maximum_wait_time:
+                    logging.warn(
+                        f"Waited over 30 seconds for a transaction to commit, resyncing {self.account.address}"
+                    )
+                    await self.initialize()
+                else:
+                    await asyncio.sleep(self.sleep_time)
+                    await self.__update()
+        finally:
+            self.lock.release()
+
+    async def __update(self):
+        self.last_uncommitted_number = await self.__current_sequence_number()
+        return self.last_uncommitted_number
+
+    async def __current_sequence_number(self) -> int:
+        return await self.client.account_sequence_number(self.account)
+
+
+import unittest
+import unittest.mock
+
+
+class Test(unittest.IsolatedAsyncioTestCase):
+    async def test_common_path(self):
+        """
+        Verifies that:
+        * AccountSequenceNumber returns sequential numbers starting from 0
+        * When the account has been updated on-chain include that in computations 100 -> 105
+        * Ensure that none is returned if the call for next_sequence_number would block
+        * Ensure that synchronize completes if the value matches on-chain
+        """
+        patcher = unittest.mock.patch(
+            "aptos_sdk.async_client.RestClient.account_sequence_number", return_value=0
+        )
+        patcher.start()
+
+        rest_client = RestClient("https://fullnode.devnet.aptoslabs.com/v1")
+        account_sequence_number = AccountSequenceNumber(
+            rest_client, AccountAddress.from_hex("b0b")
+        )
+        last_seq_num = 0
+        for seq_num in range(5):
+            last_seq_num = await account_sequence_number.next_sequence_number()
+            self.assertEqual(last_seq_num, seq_num)
+
+        patcher.stop()
+        patcher = unittest.mock.patch(
+            "aptos_sdk.async_client.RestClient.account_sequence_number", return_value=5
+        )
+        patcher.start()
+
+        for seq_num in range(AccountSequenceNumber.maximum_in_flight):
+            last_seq_num = await account_sequence_number.next_sequence_number()
+            self.assertEqual(last_seq_num, seq_num + 5)
+
+        self.assertEqual(
+            await account_sequence_number.next_sequence_number(block=False), None
+        )
+        next_sequence_number = last_seq_num + 1
+        patcher.stop()
+        patcher = unittest.mock.patch(
+            "aptos_sdk.async_client.RestClient.account_sequence_number",
+            return_value=next_sequence_number,
+        )
+        patcher.start()
+
+        self.assertNotEqual(account_sequence_number.current_number, last_seq_num)
+        await account_sequence_number.synchronize()
+        self.assertEqual(account_sequence_number.current_number, next_sequence_number)
diff --git a/ecosystem/python/sdk/aptos_sdk/transaction_worker.py b/ecosystem/python/sdk/aptos_sdk/transaction_worker.py
new file mode 100644
index 0000000000000..ce0a7648a22d2
--- /dev/null
+++ b/ecosystem/python/sdk/aptos_sdk/transaction_worker.py
@@ -0,0 +1,225 @@
+# Copyright © Aptos Foundation
+# SPDX-License-Identifier: Apache-2.0
+
+import asyncio
+import logging
+import typing
+
+from aptos_sdk.account import Account
+from aptos_sdk.account_address import AccountAddress
+from aptos_sdk.account_sequence_number import AccountSequenceNumber
+from aptos_sdk.async_client import RestClient
+from aptos_sdk.transactions import SignedTransaction, TransactionPayload
+
+
+class TransactionWorker:
+    """
+    The TransactionWorker provides a simple framework for receiving payloads to be processed. It
+    acquires new sequence numbers and calls into the callback to produce a signed transaction, and
+    then submits the transaction. In another task, it waits for resolution of the submission
+    process or get pre-execution validation error.
+
+    Note: This is not a particularly robust solution, as it lacks any framework to handle failed
+    transactions with functionality like retries or checking whether the framework is online.
+    This is the responsibility of a higher-level framework.
+    """
+
+    _account: Account
+    _account_sequence_number: AccountSequenceNumber
+    _rest_client: RestClient
+    _transaction_generator: typing.Callable[
+        [Account, int], typing.Awaitable[SignedTransaction]
+    ]
+    _started: bool
+    _stopped: bool
+    _outstanding_transactions: asyncio.Queue
+    _outstanding_transactions_task: typing.Optional[asyncio.Task]
+    _processed_transactions: asyncio.Queue
+    _process_transactions_task: typing.Optional[asyncio.Task]
+
+    def __init__(
+        self,
+        account: Account,
+        rest_client: RestClient,
+        transaction_generator: typing.Callable[
+            [Account, int], typing.Awaitable[SignedTransaction]
+        ],
+    ):
+        self._account = account
+        self._account_sequence_number = AccountSequenceNumber(
+            rest_client, account.address()
+        )
+        self._rest_client = rest_client
+        self._transaction_generator = transaction_generator
+
+        self._started = False
+        self._stopped = False
+        self._outstanding_transactions = asyncio.Queue()
+        self._processed_transactions = asyncio.Queue()
+
+    def account(self) -> AccountAddress:
+        return self._account.address()
+
+    async def _submit_transactions_task(self):
+        try:
+            while True:
+                sequence_number = (
+                    await self._account_sequence_number.next_sequence_number()
+                )
+                transaction = await self._transaction_generator(
+                    self._account, sequence_number
+                )
+                txn_hash_awaitable = self._rest_client.submit_bcs_transaction(
+                    transaction
+                )
+                await self._outstanding_transactions.put(
+                    (txn_hash_awaitable, sequence_number)
+                )
+        except asyncio.CancelledError:
+            return
+        except Exception as e:
+            # This is insufficient, if we hit this we either need to bail or resolve the potential errors
+            logging.error(e, exc_info=True)
+
+    async def _process_transactions_task(self):
+        try:
+            while True:
+                # Always start waiting for one
+                (
+                    txn_awaitable,
+                    sequence_number,
+                ) = await self._outstanding_transactions.get()
+                awaitables = [txn_awaitable]
+                sequence_numbers = [sequence_number]
+
+                # Only acquire if there are more
+                while not self._outstanding_transactions.empty():
+                    (
+                        txn_awaitable,
+                        sequence_number,
+                    ) = await self._outstanding_transactions.get()
+                    awaitables.append(txn_awaitable)
+                    sequence_numbers.append(sequence_number)
+                outputs = await asyncio.gather(*awaitables, return_exceptions=True)
+
+                for (output, sequence_number) in zip(outputs, sequence_numbers):
+                    if isinstance(output, BaseException):
+                        await self._processed_transactions.put(
+                            (sequence_number, None, output)
+                        )
+                    else:
+                        await self._processed_transactions.put(
+                            (sequence_number, output, None)
+                        )
+        except asyncio.CancelledError:
+            return
+        except Exception as e:
+            # This is insufficient, if we hit this we either need to bail or resolve the potential errors
+            logging.error(e, exc_info=True)
+
+    async def next_processed_transaction(
+        self,
+    ) -> (int, typing.Optional[str], typing.Optional[Exception]):
+        return await self._processed_transactions.get()
+
+    def stop(self):
+        """Stop the tasks for managing transactions"""
+        if not self._started:
+            raise Exception("Start not yet called")
+        if self._stopped:
+            raise Exception("Already stopped")
+        self._stopped = True
+
+        self._submit_transactions_task.cancel()
+        self._process_transactions_task.cancel()
+
+    def start(self):
+        """Begin the tasks for managing transactions"""
+        if self._started:
+            raise Exception("Already started")
+        self._started = True
+
+        self._submit_transactions_task = asyncio.create_task(
+            self._submit_transactions_task()
+        )
+        self._process_transactions_task = asyncio.create_task(
+            self._process_transactions_task()
+        )
+
+
+class TransactionQueue:
+    """Provides a queue model for pushing transactions into the TransactionWorker."""
+
+    _client: RestClient
+    _outstanding_transactions: asyncio.Queue
+
+    def __init__(self, client: RestClient):
+        self._client = client
+        self._outstanding_transactions = asyncio.Queue()
+
+    async def push(self, payload: TransactionPayload):
+        await self._outstanding_transactions.put(payload)
+
+    async def next(self, sender: Account, sequence_number: int) -> SignedTransaction:
+        payload = await self._outstanding_transactions.get()
+        return await self._client.create_bcs_signed_transaction(
+            sender, payload, sequence_number=sequence_number
+        )
+
+
+import unittest
+import unittest.mock
+
+from aptos_sdk.bcs import Serializer
+from aptos_sdk.transactions import EntryFunction, TransactionArgument
+
+
+class Test(unittest.IsolatedAsyncioTestCase):
+    async def test_common_path(self):
+        transaction_arguments = [
+            TransactionArgument(AccountAddress.from_hex("b0b"), Serializer.struct),
+            TransactionArgument(100, Serializer.u64),
+        ]
+        payload = EntryFunction.natural(
+            "0x1::aptos_accounts",
+            "transfer",
+            [],
+            transaction_arguments,
+        )
+
+        seq_num_patcher = unittest.mock.patch(
+            "aptos_sdk.async_client.RestClient.account_sequence_number", return_value=0
+        )
+        seq_num_patcher.start()
+        submit_txn_patcher = unittest.mock.patch(
+            "aptos_sdk.async_client.RestClient.submit_bcs_transaction",
+            return_value="0xff",
+        )
+        submit_txn_patcher.start()
+
+        rest_client = RestClient("https://fullnode.devnet.aptoslabs.com/v1")
+        txn_queue = TransactionQueue(rest_client)
+        txn_worker = TransactionWorker(Account.generate(), rest_client, txn_queue.next)
+        txn_worker.start()
+
+        await txn_queue.push(payload)
+        processed_txn = await txn_worker.next_processed_transaction()
+        self.assertEqual(processed_txn[0], 0)
+        self.assertEqual(processed_txn[1], "0xff")
+        self.assertEqual(processed_txn[2], None)
+
+        submit_txn_patcher.stop()
+        exception = Exception("Power overwhelming")
+        submit_txn_patcher = unittest.mock.patch(
+            "aptos_sdk.async_client.RestClient.submit_bcs_transaction",
+            side_effect=exception,
+        )
+        submit_txn_patcher.start()
+
+        await txn_queue.push(payload)
+        processed_txn = await txn_worker.next_processed_transaction()
+        self.assertEqual(processed_txn[0], 1)
+        self.assertEqual(processed_txn[1], None)
+        self.assertEqual(processed_txn[2], exception)
+
+        txn_worker.stop()

From bec6393b3877f6fccefb0d1b242850818c53b968 Mon Sep 17 00:00:00 2001
From: David Wolinsky 
Date: Sat, 29 Apr 2023 19:55:44 -0700
Subject: [PATCH 111/200] [python] Add testing coverage

---
 ecosystem/python/sdk/Makefile       |  4 ++
 ecosystem/python/sdk/poetry.lock    | 80 ++++++++++++++++++++++++-----
 ecosystem/python/sdk/pyproject.toml |  1 +
 3 files changed, 73 insertions(+), 12 deletions(-)

diff --git a/ecosystem/python/sdk/Makefile b/ecosystem/python/sdk/Makefile
index 4096c287621ba..8131281ef3f38 100644
--- a/ecosystem/python/sdk/Makefile
+++ b/ecosystem/python/sdk/Makefile
@@ -4,6 +4,10 @@
 test:
 	poetry run python -m unittest discover -s aptos_sdk/ -p '*.py' -t ..
 
+test-coverage:
+	poetry run python -m coverage run -m unittest discover -s aptos_sdk/ -p '*.py' -t ..
+	poetry run python -m coverage report
+
 fmt:
 	find ./examples ./aptos_sdk *.py -type f -name "*.py" | xargs poetry run autoflake -i -r --remove-all-unused-imports --remove-unused-variables --ignore-init-module-imports
 	poetry run isort aptos_sdk examples setup.py
diff --git a/ecosystem/python/sdk/poetry.lock b/ecosystem/python/sdk/poetry.lock
index 19379e917cf03..34cad1d1642ad 100644
--- a/ecosystem/python/sdk/poetry.lock
+++ b/ecosystem/python/sdk/poetry.lock
@@ -190,6 +190,73 @@ files = [
     {file = "colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44"},
 ]
 
+[[package]]
+name = "coverage"
+version = "7.2.4"
+description = "Code coverage measurement for Python"
+category = "dev"
+optional = false
+python-versions = ">=3.7"
+files = [
+    {file = "coverage-7.2.4-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:9e5eedde6e6e241ec3816f05767cc77e7456bf5ec6b373fb29917f0990e2078f"},
+    {file = "coverage-7.2.4-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:5c6c6e3b8fb6411a2035da78d86516bfcfd450571d167304911814407697fb7a"},
+    {file = "coverage-7.2.4-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f7668a621afc52db29f6867e0e9c72a1eec9f02c94a7c36599119d557cf6e471"},
+    {file = "coverage-7.2.4-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:cdfb53bef4b2739ff747ebbd76d6ac5384371fd3c7a8af08899074eba034d483"},
+    {file = "coverage-7.2.4-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:a5c4f2e44a2ae15fa6883898e756552db5105ca4bd918634cbd5b7c00e19e8a1"},
+    {file = "coverage-7.2.4-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:700bc9fb1074e0c67c09fe96a803de66663830420781df8dc9fb90d7421d4ccb"},
+    {file = "coverage-7.2.4-cp310-cp310-musllinux_1_1_i686.whl", hash = "sha256:ac4861241e693e21b280f07844ae0e0707665e1dfcbf9466b793584984ae45c4"},
+    {file = "coverage-7.2.4-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:3d6f3c5b6738a494f17c73b4aa3aa899865cc33a74aa85e3b5695943b79ad3ce"},
+    {file = "coverage-7.2.4-cp310-cp310-win32.whl", hash = "sha256:437da7d2fcc35bf45e04b7e9cfecb7c459ec6f6dc17a8558ed52e8d666c2d9ab"},
+    {file = "coverage-7.2.4-cp310-cp310-win_amd64.whl", hash = "sha256:1d3893f285fd76f56651f04d1efd3bdce251c32992a64c51e5d6ec3ba9e3f9c9"},
+    {file = "coverage-7.2.4-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:6a17bf32e9e3333d78606ac1073dd20655dc0752d5b923fa76afd3bc91674ab4"},
+    {file = "coverage-7.2.4-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:f7ffdb3af2a01ce91577f84fc0faa056029fe457f3183007cffe7b11ea78b23c"},
+    {file = "coverage-7.2.4-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:89e63b38c7b888e00fd42ce458f838dccb66de06baea2da71801b0fc9070bfa0"},
+    {file = "coverage-7.2.4-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:4522dd9aeb9cc2c4c54ce23933beb37a4e106ec2ba94f69138c159024c8a906a"},
+    {file = "coverage-7.2.4-cp311-cp311-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:29c7d88468f01a75231797173b52dc66d20a8d91b8bb75c88fc5861268578f52"},
+    {file = "coverage-7.2.4-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:bc47015fc0455753e8aba1f38b81b731aaf7f004a0c390b404e0fcf1d6c1d72f"},
+    {file = "coverage-7.2.4-cp311-cp311-musllinux_1_1_i686.whl", hash = "sha256:5c122d120c11a236558c339a59b4b60947b38ac9e3ad30a0e0e02540b37bf536"},
+    {file = "coverage-7.2.4-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:50fda3d33b705b9c01e3b772cfa7d14de8aec2ec2870e4320992c26d057fde12"},
+    {file = "coverage-7.2.4-cp311-cp311-win32.whl", hash = "sha256:ab08af91cf4d847a6e15d7d5eeae5fead1487caf16ff3a2056dbe64d058fd246"},
+    {file = "coverage-7.2.4-cp311-cp311-win_amd64.whl", hash = "sha256:876e4ef3eff00b50787867c5bae84857a9af4c369a9d5b266cd9b19f61e48ef7"},
+    {file = "coverage-7.2.4-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:3fc9cde48de956bfbacea026936fbd4974ff1dc2f83397c6f1968f0142c9d50b"},
+    {file = "coverage-7.2.4-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:12bc9127c8aca2f7c25c9acca53da3db6799b2999b40f28c2546237b7ea28459"},
+    {file = "coverage-7.2.4-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:2857894c22833d3da6e113623a9b7440159b2295280b4e0d954cadbfa724b85a"},
+    {file = "coverage-7.2.4-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:d4db4e6c115d869cd5397d3d21fd99e4c7053205c33a4ae725c90d19dcd178af"},
+    {file = "coverage-7.2.4-cp37-cp37m-musllinux_1_1_aarch64.whl", hash = "sha256:f37ae1804596f13d811e0247ffc8219f5261b3565bdf45fcbb4fc091b8e9ff35"},
+    {file = "coverage-7.2.4-cp37-cp37m-musllinux_1_1_i686.whl", hash = "sha256:cdee9a77fd0ce000781680b6a1f4b721c567f66f2f73a49be1843ff439d634f3"},
+    {file = "coverage-7.2.4-cp37-cp37m-musllinux_1_1_x86_64.whl", hash = "sha256:0b65a6a5484b7f2970393d6250553c05b2ede069e0e18abe907fdc7f3528252e"},
+    {file = "coverage-7.2.4-cp37-cp37m-win32.whl", hash = "sha256:1a3e8697cb40f28e5bcfb6f4bda7852d96dbb6f6fd7cc306aba4ae690c9905ab"},
+    {file = "coverage-7.2.4-cp37-cp37m-win_amd64.whl", hash = "sha256:4078939c4b7053e14e87c65aa68dbed7867e326e450f94038bfe1a1b22078ff9"},
+    {file = "coverage-7.2.4-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:603a2b172126e3b08c11ca34200143089a088cd0297d4cfc4922d2c1c3a892f9"},
+    {file = "coverage-7.2.4-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:72751d117ceaad3b1ea3bcb9e85f5409bbe9fb8a40086e17333b994dbccc0718"},
+    {file = "coverage-7.2.4-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f19ba9301e6fb0b94ba71fda9a1b02d11f0aab7f8e2455122a4e2921b6703c2f"},
+    {file = "coverage-7.2.4-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:2d784177a7fb9d0f58d24d3e60638c8b729c3693963bf67fa919120f750db237"},
+    {file = "coverage-7.2.4-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:1d2a9180beff1922b09bd7389e23454928e108449e646c26da5c62e29b0bf4e3"},
+    {file = "coverage-7.2.4-cp38-cp38-musllinux_1_1_aarch64.whl", hash = "sha256:39747afc854a7ee14e5e132da7db179d6281faf97dc51e6d7806651811c47538"},
+    {file = "coverage-7.2.4-cp38-cp38-musllinux_1_1_i686.whl", hash = "sha256:60feb703abc8d78e9427d873bcf924c9e30cf540a21971ef5a17154da763b60f"},
+    {file = "coverage-7.2.4-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:c2becddfcbf3d994a8f4f9dd2b6015cae3a3eff50dedc6e4a17c3cccbe8f93d4"},
+    {file = "coverage-7.2.4-cp38-cp38-win32.whl", hash = "sha256:56a674ad18d6b04008283ca03c012be913bf89d91c0803c54c24600b300d9e51"},
+    {file = "coverage-7.2.4-cp38-cp38-win_amd64.whl", hash = "sha256:ab08e03add2cf5793e66ac1bbbb24acfa90c125476f5724f5d44c56eeec1d635"},
+    {file = "coverage-7.2.4-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:92b565c51732ea2e7e541709ccce76391b39f4254260e5922e08e00971e88e33"},
+    {file = "coverage-7.2.4-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:8769a67e8816c7e94d5bf446fc0501641fde78fdff362feb28c2c64d45d0e9b1"},
+    {file = "coverage-7.2.4-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:56d74d6fbd5a98a5629e8467b719b0abea9ca01a6b13555d125c84f8bf4ea23d"},
+    {file = "coverage-7.2.4-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:d9f770c6052d9b5c9b0e824fd8c003fe33276473b65b4f10ece9565ceb62438e"},
+    {file = "coverage-7.2.4-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b3023ce23e41a6f006c09f7e6d62b6c069c36bdc9f7de16a5ef823acc02e6c63"},
+    {file = "coverage-7.2.4-cp39-cp39-musllinux_1_1_aarch64.whl", hash = "sha256:fabd1f4d12dfd6b4f309208c2f31b116dc5900e0b42dbafe4ee1bc7c998ffbb0"},
+    {file = "coverage-7.2.4-cp39-cp39-musllinux_1_1_i686.whl", hash = "sha256:e41a7f44e73b37c6f0132ecfdc1c8b67722f42a3d9b979e6ebc150c8e80cf13a"},
+    {file = "coverage-7.2.4-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:864e36947289be05abd83267c4bade35e772526d3e9653444a9dc891faf0d698"},
+    {file = "coverage-7.2.4-cp39-cp39-win32.whl", hash = "sha256:ea534200efbf600e60130c48552f99f351cae2906898a9cd924c1c7f2fb02853"},
+    {file = "coverage-7.2.4-cp39-cp39-win_amd64.whl", hash = "sha256:00f8fd8a5fe1ffc3aef78ea2dbf553e5c0f4664324e878995e38d41f037eb2b3"},
+    {file = "coverage-7.2.4-pp37.pp38.pp39-none-any.whl", hash = "sha256:856bcb837e96adede31018a0854ce7711a5d6174db1a84e629134970676c54fa"},
+    {file = "coverage-7.2.4.tar.gz", hash = "sha256:7283f78d07a201ac7d9dc2ac2e4faaea99c4d302f243ee5b4e359f3e170dc008"},
+]
+
+[package.dependencies]
+tomli = {version = "*", optional = true, markers = "python_full_version <= \"3.11.0a6\" and extra == \"toml\""}
+
+[package.extras]
+toml = ["tomli"]
+
 [[package]]
 name = "flake8"
 version = "5.0.4"
@@ -321,17 +388,6 @@ files = [
     {file = "idna-3.4.tar.gz", hash = "sha256:814f528e8dead7d329833b91c5faa87d60bf71824cd12a7530b5526063d02cb4"},
 ]
 
-[[package]]
-name = "importlib"
-version = "1.0.4"
-description = "Backport of importlib.import_module() from Python 2.7"
-category = "main"
-optional = false
-python-versions = "*"
-files = [
-    {file = "importlib-1.0.4.zip", hash = "sha256:b6ee7066fea66e35f8d0acee24d98006de1a0a8a94a8ce6efe73a9a23c8d9826"},
-]
-
 [[package]]
 name = "importlib-metadata"
 version = "4.2.0"
@@ -639,4 +695,4 @@ testing = ["big-O", "flake8 (<5)", "jaraco.functools", "jaraco.itertools", "more
 [metadata]
 lock-version = "2.0"
 python-versions = ">=3.7,<4.0"
-content-hash = "bdd9b43bbb77709433347a184874a91816d07bcac6e4b843beeebf44acd9a92f"
+content-hash = "d9a288e06237d103a93b496c7e77b124cc4ac79580e4ac6b48842e300c6648a4"
diff --git a/ecosystem/python/sdk/pyproject.toml b/ecosystem/python/sdk/pyproject.toml
index b4bf7467961c3..854ff38819ba0 100644
--- a/ecosystem/python/sdk/pyproject.toml
+++ b/ecosystem/python/sdk/pyproject.toml
@@ -19,6 +19,7 @@ importlib = "^1.0.4"
 [tool.poetry.dev-dependencies]
 autoflake = "1.4.0"
 black = "^22.6.0"
+coverage = "^7.2.4"
 flake8 = ">=3.8.3,<6.0.0"
 isort = "^5.10.1"
 mypy = "^0.982"

From 7276640145ae2c61646f4a55c616d7c66df7157b Mon Sep 17 00:00:00 2001
From: David Wolinsky 
Date: Tue, 2 May 2023 23:07:41 -0700
Subject: [PATCH 112/200] [python] cleaning up with feedback

---
 .../sdk/aptos_sdk/account_sequence_number.py  | 121 ++++++-----
 .../sdk/aptos_sdk/transaction_worker.py       |  15 +-
 ecosystem/python/sdk/examples/common.py       |   6 -
 .../sdk/examples/transaction-batching.py      | 193 ++++++++++++++----
 4 files changed, 217 insertions(+), 118 deletions(-)

diff --git a/ecosystem/python/sdk/aptos_sdk/account_sequence_number.py b/ecosystem/python/sdk/aptos_sdk/account_sequence_number.py
index 266a25047d708..72f8a9c15e191 100644
--- a/ecosystem/python/sdk/aptos_sdk/account_sequence_number.py
+++ b/ecosystem/python/sdk/aptos_sdk/account_sequence_number.py
@@ -13,83 +13,87 @@ class AccountSequenceNumber:
     """
     A managed wrapper around sequence numbers that implements the trivial flow control used by the
     Aptos faucet:
-    * Submit up to 50 transactions per account in parallel with a timeout of 20 seconds
-    * If local assumes 50 are in flight, determine the actual committed state from the network
-    * If there are less than 50 due to some being committed, adjust the window
-    * If 50 are in flight Wait .1 seconds before re-evaluating
+    * Submit up to 100 transactions per account in parallel with a timeout of 20 seconds
+    * If local assumes 100 are in flight, determine the actual committed state from the network
+    * If there are less than 100 due to some being committed, adjust the window
+    * If 100 are in flight Wait .1 seconds before re-evaluating
     * If ever waiting more than 30 seconds restart the sequence number to the current on-chain state
     Assumptions:
     * Accounts are expected to be managed by a single AccountSequenceNumber and not used otherwise.
     * They are initialized to the current on-chain state, so if there are already transactions in
-      flight, they make take some time to reset.
+      flight, they may take some time to reset.
     * Accounts are automatically initialized if not explicitly
 
     Notes:
     * This is co-routine safe, that is many async tasks can be reading from this concurrently.
+    * The state of an account cannot be used across multiple AccountSequenceNumber services.
     * The synchronize method will create a barrier that prevents additional next_sequence_number
       calls until it is complete.
     * This only manages the distribution of sequence numbers it does not help handle transaction
       failures.
+    * If a transaction fails, you should call synchronize and wait for timeouts.
+    * Mempool limits the number of transactions per account to 100, hence why we chose 100.
     """
 
-    client: RestClient
-    account: AccountAddress
-    lock = asyncio.Lock
+    _client: RestClient
+    _account: AccountAddress
+    _lock: asyncio.Lock
 
-    maximum_in_flight: int = 100
-    maximum_wait_time = 30
-    sleep_time = 0.01
+    _maximum_in_flight: int = 100
+    _maximum_wait_time: int = 30
+    _sleep_time: float = 0.01
 
-    last_committed_number: Optional[int]
-    current_number: Optional[int]
+    _last_committed_number: Optional[int]
+    _current_number: Optional[int]
 
     def __init__(self, client: RestClient, account: AccountAddress):
-        self.client = client
-        self.account = account
-        self.lock = asyncio.Lock()
+        self._client = client
+        self._account = account
+        self._lock = asyncio.Lock()
 
-        self.last_uncommitted_number = None
-        self.current_number = None
+        self._last_uncommitted_number = None
+        self._current_number = None
 
     async def next_sequence_number(self, block: bool = True) -> Optional[int]:
         """
         Returns the next sequence number available on this account. This leverages a lock to
         guarantee first-in, first-out ordering of requests.
         """
-        await self.lock.acquire()
-        try:
-            if self.last_uncommitted_number is None or self.current_number is None:
-                await self.initialize()
+        async with self._lock:
+            if self._last_uncommitted_number is None or self._current_number is None:
+                await self._initialize()
+            # If there are more than self._maximum_in_flight in flight, wait for a slot.
+            # Or at least check to see if there is a slot and exit if in non-blocking mode.
             if (
-                self.current_number - self.last_uncommitted_number
-                >= self.maximum_in_flight
+                self._current_number - self._last_uncommitted_number
+                >= self._maximum_in_flight
             ):
-                await self.__update()
+                await self._update()
                 start_time = time.time()
                 while (
-                    self.current_number - self.last_uncommitted_number
-                    >= self.maximum_in_flight
+                    self._current_number - self._last_uncommitted_number
+                    >= self._maximum_in_flight
                 ):
                     if not block:
                         return None
-                    await asyncio.sleep(self.sleep_time)
-                    if time.time() - start_time > self.maximum_wait_time:
+
+                    await asyncio.sleep(self._sleep_time)
+                    if time.time() - start_time > self._maximum_wait_time:
                         logging.warn(
-                            f"Waited over 30 seconds for a transaction to commit, resyncing {self.account.address().hex()}"
+                            f"Waited over {self._maximum_wait_time} seconds for a transaction to commit, resyncing {self._account}"
                         )
-                        await self.initialize()
+                        await self._initialize()
                     else:
-                        await self.__update()
-            next_number = self.current_number
-            self.current_number += 1
-        finally:
-            self.lock.release()
+                        await self._update()
+
+            next_number = self._current_number
+            self._current_number += 1
         return next_number
 
-    async def initialize(self):
+    async def _initialize(self):
         """Optional initializer. called by next_sequence_number if not called prior."""
-        self.current_number = await self.__current_sequence_number()
-        self.last_uncommitted_number = self.current_number
+        self._current_number = await self._current_sequence_number()
+        self._last_uncommitted_number = self._current_number
 
     async def synchronize(self):
         """
@@ -97,32 +101,25 @@ async def synchronize(self):
         the maximum wait time has elapsed. This will prevent any calls to next_sequence_number
         until this called has returned.
         """
-        if self.last_uncommitted_number == self.current_number:
-            return
-
-        await self.lock.acquire()
-        try:
-            await self.__update()
+        async with self._lock:
+            await self._update()
             start_time = time.time()
-            while self.last_uncommitted_number != self.current_number:
-                print(f"{self.last_uncommitted_number} {self.current_number}")
-                if time.time() - start_time > self.maximum_wait_time:
+            while self._last_uncommitted_number != self._current_number:
+                if time.time() - start_time > self._maximum_wait_time:
                     logging.warn(
-                        f"Waited over 30 seconds for a transaction to commit, resyncing {self.account.address}"
+                        f"Waited over {self._maximum_wait_time} seconds for a transaction to commit, resyncing {self._account}"
                     )
-                    await self.initialize()
+                    await self._initialize()
                 else:
-                    await asyncio.sleep(self.sleep_time)
-                    await self.__update()
-        finally:
-            self.lock.release()
+                    await asyncio.sleep(self._sleep_time)
+                    await self._update()
 
-    async def __update(self):
-        self.last_uncommitted_number = await self.__current_sequence_number()
-        return self.last_uncommitted_number
+    async def _update(self):
+        self._last_uncommitted_number = await self._current_sequence_number()
+        return self._last_uncommitted_number
 
-    async def __current_sequence_number(self) -> int:
-        return await self.client.account_sequence_number(self.account)
+    async def _current_sequence_number(self) -> int:
+        return await self._client.account_sequence_number(self._account)
 
 
 import unittest
@@ -158,7 +155,7 @@ async def test_common_path(self):
         )
         patcher.start()
 
-        for seq_num in range(AccountSequenceNumber.maximum_in_flight):
+        for seq_num in range(AccountSequenceNumber._maximum_in_flight):
             last_seq_num = await account_sequence_number.next_sequence_number()
             self.assertEqual(last_seq_num, seq_num + 5)
 
@@ -173,6 +170,6 @@ async def test_common_path(self):
         )
         patcher.start()
 
-        self.assertNotEqual(account_sequence_number.current_number, last_seq_num)
+        self.assertNotEqual(account_sequence_number._current_number, last_seq_num)
         await account_sequence_number.synchronize()
-        self.assertEqual(account_sequence_number.current_number, next_sequence_number)
+        self.assertEqual(account_sequence_number._current_number, next_sequence_number)
diff --git a/ecosystem/python/sdk/aptos_sdk/transaction_worker.py b/ecosystem/python/sdk/aptos_sdk/transaction_worker.py
index ce0a7648a22d2..22ec9ca87ac72 100644
--- a/ecosystem/python/sdk/aptos_sdk/transaction_worker.py
+++ b/ecosystem/python/sdk/aptos_sdk/transaction_worker.py
@@ -57,7 +57,7 @@ def __init__(
         self._outstanding_transactions = asyncio.Queue()
         self._processed_transactions = asyncio.Queue()
 
-    def account(self) -> AccountAddress:
+    def address(self) -> AccountAddress:
         return self._account.address()
 
     async def _submit_transactions_task(self):
@@ -84,22 +84,23 @@ async def _submit_transactions_task(self):
     async def _process_transactions_task(self):
         try:
             while True:
-                # Always start waiting for one
+                # Always start waiting for one, that way we can acquire a batch in the loop below.
                 (
-                    txn_awaitable,
+                    txn_hash_awaitable,
                     sequence_number,
                 ) = await self._outstanding_transactions.get()
-                awaitables = [txn_awaitable]
+                awaitables = [txn_hash_awaitable]
                 sequence_numbers = [sequence_number]
 
-                # Only acquire if there are more
+                # Now acquire our batch.
                 while not self._outstanding_transactions.empty():
                     (
-                        txn_awaitable,
+                        txn_hash_awaitable,
                         sequence_number,
                     ) = await self._outstanding_transactions.get()
-                    awaitables.append(txn_awaitable)
+                    awaitables.append(txn_hash_awaitable)
                     sequence_numbers.append(sequence_number)
+
                 outputs = await asyncio.gather(*awaitables, return_exceptions=True)
 
                 for (output, sequence_number) in zip(outputs, sequence_numbers):
diff --git a/ecosystem/python/sdk/examples/common.py b/ecosystem/python/sdk/examples/common.py
index 8272f249de443..b81711d057ecf 100644
--- a/ecosystem/python/sdk/examples/common.py
+++ b/ecosystem/python/sdk/examples/common.py
@@ -9,9 +9,3 @@
     "APTOS_FAUCET_URL",
     "https://faucet.devnet.aptoslabs.com",
 )  # <:!:section_1
-
-NODE_URL = os.getenv("APTOS_NODE_URL", "http://127.0.0.1:8080/v1")
-FAUCET_URL = os.getenv(
-    "APTOS_FAUCET_URL",
-    "http://127.0.0.1:8081",
-)  # <:!:section_1
diff --git a/ecosystem/python/sdk/examples/transaction-batching.py b/ecosystem/python/sdk/examples/transaction-batching.py
index 714707d2f19ff..3f9472e271bff 100644
--- a/ecosystem/python/sdk/examples/transaction-batching.py
+++ b/ecosystem/python/sdk/examples/transaction-batching.py
@@ -1,16 +1,19 @@
 # Copyright © Aptos Foundation
 # SPDX-License-Identifier: Apache-2.0
 
+from __future__ import annotations
+
 import asyncio
-import sys
+import logging
 import time
-import typing
 from multiprocessing import Pipe, Process
 from multiprocessing.connection import Connection
+from typing import Any, List
 
 from aptos_sdk.account import Account
 from aptos_sdk.account_address import AccountAddress
 from aptos_sdk.account_sequence_number import AccountSequenceNumber
+from aptos_sdk.aptos_token_client import AptosTokenClient, Property, PropertyMap
 from aptos_sdk.async_client import ClientConfig, FaucetClient, RestClient
 from aptos_sdk.bcs import Serializer
 from aptos_sdk.transaction_worker import TransactionWorker
@@ -91,13 +94,13 @@ def __init__(self, node_url: str, account: Account, recipient: AccountAddress):
             target=Worker.run, args=(conn, node_url, account, recipient)
         )
 
-    def get(self) -> typing.Any:
+    def get(self) -> Any:
         self._conn.recv()
 
     def join(self):
         self._process.join()
 
-    def put(self, value: typing.Any):
+    def put(self, value: Any):
         self._conn.send(value)
 
     def start(self):
@@ -130,10 +133,10 @@ def __init__(
 
     def run(queue: Pipe, node_url: str, account: Account, recipient: AccountAddress):
         worker = Worker(queue, node_url, account, recipient)
-        asyncio.run(worker.arun())
+        asyncio.run(worker.async_run())
 
-    async def arun(self):
-        print(f"hello from {self._account.address()}", flush=True)
+    async def async_run(self):
+        print(f"hello from {self._account.address()}")
         try:
             self._txn_worker.start()
 
@@ -142,7 +145,7 @@ async def arun(self):
 
             await self._txn_generator.increase_transaction_count(num_txns)
 
-            print(f"Increase txns from {self._account.address()}", flush=True)
+            print(f"Increase txns from {self._account.address()}")
             self._conn.send(True)
             self._conn.recv()
 
@@ -155,13 +158,14 @@ async def arun(self):
                     exception,
                 ) = await self._txn_worker.next_processed_transaction()
                 if exception:
-                    print(
-                        f"Account {self._txn_worker.account()}, transaction {sequence_number} submission failed: {exception}"
+                    logging.error(
+                        f"Account {self._txn_worker.address()}, transaction {sequence_number} submission failed.",
+                        exc_info=exception,
                     )
                 else:
                     txn_hashes.append(txn_hash)
 
-            print(f"Submit txns from {self._account.address()}", flush=True)
+            print(f"Submitted txns from {self._account.address()}", flush=True)
             self._conn.send(True)
             self._conn.recv()
 
@@ -172,10 +176,13 @@ async def arun(self):
             print(f"Verified txns from {self._account.address()}", flush=True)
             self._conn.send(True)
         except Exception as e:
-            print(e)
-            sys.stdout.flush()
+            logging.error(
+                "Failed during run.",
+                exc_info=e,
+            )
 
 
+# This performs a simple p2p transaction
 async def transfer_transaction(
     client: RestClient,
     sender: Account,
@@ -199,42 +206,109 @@ async def transfer_transaction(
     )
 
 
-async def main():
-    client_config = ClientConfig()
-    # Toggle to benchmark
-    client_config.http2 = False
-    client_config.http2 = True
-    rest_client = RestClient(NODE_URL, client_config)
+# This will create a collection in the first transaction and then create NFTs thereafter.
+# Note: Please adjust the sequence number and the name of the collection if run on the same set of
+# accounts, otherwise you may end up not creating a collection and failing all transactions.
+async def token_transaction(
+    client: RestClient,
+    sender: Account,
+    sequence_number: int,
+    recipient: AccountAddress,
+    amount: int,
+) -> str:
+    collection_name = "Funky Alice's"
+    if sequence_number == 8351:
+        payload = AptosTokenClient.create_collection_payload(
+            "Alice's simple collection",
+            20000000000,
+            collection_name,
+            "https://aptos.dev",
+            True,
+            True,
+            True,
+            True,
+            True,
+            True,
+            True,
+            True,
+            True,
+            0,
+            1,
+        )
+    else:
+        payload = AptosTokenClient.mint_token_payload(
+            collection_name,
+            "Alice's simple token",
+            f"token {sequence_number}",
+            "https://aptos.dev/img/nyan.jpeg",
+            PropertyMap([Property.string("string", "string value")]),
+        )
+    return await client.create_bcs_signed_transaction(sender, payload, sequence_number)
+
+
+class Accounts:
+    source: Account
+    senders: List[Account]
+    receivers: List[Account]
+
+    def __init__(self, source, senders, receivers):
+        self.source = source
+        self.senders = senders
+        self.receivers = receivers
+
+    def generate(path: str, num_accounts: int) -> Accounts:
+        source = Account.generate()
+        source.store(f"{path}/source.txt")
+        senders = []
+        receivers = []
+        for idx in range(num_accounts):
+            senders.append(Account.generate())
+            receivers.append(Account.generate())
+            senders[-1].store(f"{path}/sender_{idx}.txt")
+            receivers[-1].store(f"{path}/receiver_{idx}.txt")
+        return Accounts(source, senders, receivers)
+
+    def load(path: str, num_accounts: int) -> Accounts:
+        source = Account.load(f"{path}/source.txt")
+        senders = []
+        receivers = []
+        for idx in range(num_accounts):
+            senders.append(Account.load(f"{path}/sender_{idx}.txt"))
+            receivers.append(Account.load(f"{path}/receiver_{idx}.txt"))
+        return Accounts(source, senders, receivers)
+
+
+async def fund_from_faucet(rest_client: RestClient, source: Account):
     faucet_client = FaucetClient(FAUCET_URL, rest_client)
 
-    num_accounts = 8
-    transactions = 1000
-    start = time.time()
-
-    print("Starting...")
-
-    accounts = []
-    recipients = []
-
-    for account in range(num_accounts):
-        recipients.append(Account.generate())
-        accounts.append(Account.generate())
+    fund_txns = []
+    for _ in range(40):
+        fund_txns.append(faucet_client.fund_account(source.address(), 100_000_000_000))
+    await asyncio.gather(*fund_txns)
 
-    last = time.time()
-    print(f"Accounts generated at {last - start}")
 
-    source = Account.generate()
-    await faucet_client.fund_account(source.address(), 100_000_000 * num_accounts)
+async def distribute_portionally(
+    rest_client: RestClient,
+    source: Account,
+    senders: List[Account],
+    receivers: List[Account],
+):
     balance = int(await rest_client.account_balance(source.address()))
+    per_node_balance = balance // (len(senders) + 1)
+    await distribute(rest_client, source, senders, receivers, per_node_balance)
 
-    per_node_balance = balance // (num_accounts + 1)
-    account_sequence_number = AccountSequenceNumber(rest_client, source.address())
 
-    print(f"Initial account funded at {time.time() - start} {time.time() - last}")
-    last = time.time()
+async def distribute(
+    rest_client: RestClient,
+    source: Account,
+    senders: List[Account],
+    receivers: List[Account],
+    per_node_amount: int,
+):
+    all_accounts = list(map(lambda account: (account.address(), True), senders))
+    all_accounts.extend(map(lambda account: (account.address(), False), receivers))
 
-    all_accounts = list(map(lambda account: (account.address(), True), accounts))
-    all_accounts.extend(map(lambda account: (account.address(), False), recipients))
+    account_sequence_number = AccountSequenceNumber(rest_client, source.address())
 
     txns = []
     txn_hashes = []
@@ -247,7 +321,7 @@ async def main():
             txn_hashes.extend(await asyncio.gather(*txns))
             txns = []
             sequence_number = await account_sequence_number.next_sequence_number()
-        amount = per_node_balance if fund else 0
+        amount = per_node_amount if fund else 0
         txn = await transfer_transaction(
             rest_client, source, sequence_number, account, amount
         )
@@ -258,6 +332,39 @@ async def main():
         await rest_client.wait_for_transaction(txn_hash)
     await account_sequence_number.synchronize()
 
+
+async def main():
+    client_config = ClientConfig()
+    client_config.http2 = True
+    rest_client = RestClient(NODE_URL, client_config)
+
+    num_accounts = 16
+    transactions = 10000
+    start = time.time()
+
+    print("Starting...")
+
+    # Generate will create new accounts, load will load existing accounts
+    all_accounts = Accounts.generate("nodes", num_accounts)
+    # all_accounts = Accounts.load("nodes", num_accounts)
+    accounts = all_accounts.senders
+    receivers = all_accounts.receivers
+    source = all_accounts.source
+
+    print(f"source: {source.address()}")
+
+    last = time.time()
+    print(f"Accounts generated / loaded at {last - start}")
+
+    await fund_from_faucet(rest_client, source)
+
+    print(f"Initial account funded at {time.time() - start} {time.time() - last}")
+    last = time.time()
+
+    balance = await rest_client.account_balance(source.address())
+    amount = int(balance * 0.9 / num_accounts)
+    await distribute(rest_client, source, accounts, receivers, amount)
+
     print(f"Funded all accounts at {time.time() - start} {time.time() - last}")
     last = time.time()
 
@@ -270,7 +377,7 @@ async def main():
     last = time.time()
 
     workers = []
-    for (account, recipient) in zip(accounts, recipients):
+    for (account, recipient) in zip(accounts, receivers):
         workers.append(WorkerContainer(NODE_URL, account, recipient.address()))
         workers[-1].start()
 

From e238c032b8943f7abddf2ed9a84f2928caae0dff Mon Sep 17 00:00:00 2001
From: David Wolinsky 
Date: Thu, 8 Jun 2023 14:47:12 -0700
Subject: [PATCH 113/200] [docs] update transaction management

---
 developer-docs-site/docs/guides/transaction-management.md | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/developer-docs-site/docs/guides/transaction-management.md b/developer-docs-site/docs/guides/transaction-management.md
index 172bcece2b0ef..cf4b882590d0f 100644
--- a/developer-docs-site/docs/guides/transaction-management.md
+++ b/developer-docs-site/docs/guides/transaction-management.md
@@ -38,7 +38,12 @@ Each transaction requires a distinct sequence number that is sequential to previ
 
 In parallel, monitor new transactions submitted. Once the earliest transaction expiration time has expired synchronize up to that transaction. Then repeat the process for the next transaction.
 
-If there is any failure, wait until all outstanding transactions have timed out and leave it to the application to decide how to proceed, e.g., replay failed transactions.
+If there is any failure, wait until all outstanding transactions have timed out and leave it to the application to decide how to proceed, e.g., replay failed transactions. The best method for waiting for outstanded transactions is first to query the ledger timestamp and ensure it is at least elapsed the maximum timeout from the last transactions submit time. From there, validate with mempool that all transactions since the last known committed transaction are either committed or no longer exist within the mmempool. This can be done by querying the REST API for transactions of a specific account, specifying the currently being evaluated sequence number and setting a limit to 1. Once these checks are complete, the local transaction number can be resynchronized.
+
+These failure handling steps are critical for the following reasons:
+* Mempool does not immediate evict expired transactions.
+* A new transaction cannot overwrite an existing transaction, even if it is expired.
+* Consensus, i.e., the ledger timestamp, dictates expirations, the local node will only expire after it sees a committed timestamp after the transactions expiration time and a garbage collection has happened.
 
 ### Managing Transactions
 

From b19441ac14858ed7f521cf53ec4e7e34c0d84b18 Mon Sep 17 00:00:00 2001
From: David Wolinsky 
Date: Thu, 8 Jun 2023 16:46:27 -0700
Subject: [PATCH 114/200] [python] add a modest reliablity layer to transaction
 management

this handles all the failures associated with network congestion,
meaning this is ready to ship for now... need more testing on other
failure cases.... such as intermittent network connectivity, lost
connections, bad upstreams.
---
 .../sdk/aptos_sdk/account_sequence_number.py  | 87 ++++++++++++++-----
 .../python/sdk/aptos_sdk/async_client.py      | 24 ++++-
 .../sdk/examples/transaction-batching.py      | 17 ++--
 3 files changed, 97 insertions(+), 31 deletions(-)

diff --git a/ecosystem/python/sdk/aptos_sdk/account_sequence_number.py b/ecosystem/python/sdk/aptos_sdk/account_sequence_number.py
index 72f8a9c15e191..be6343428426c 100644
--- a/ecosystem/python/sdk/aptos_sdk/account_sequence_number.py
+++ b/ecosystem/python/sdk/aptos_sdk/account_sequence_number.py
@@ -1,12 +1,22 @@
 # Copyright © Aptos Foundation
 # SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
 import asyncio
 import logging
-import time
-from typing import Optional
+from typing import Callable, Optional
 
 from aptos_sdk.account_address import AccountAddress
-from aptos_sdk.async_client import RestClient
+from aptos_sdk.async_client import ApiError, RestClient
+
+
+class AccountSequenceNumberConfig:
+    """Common configuration for account number generation"""
+
+    maximum_in_flight: int = 100
+    maximum_wait_time: int = 30
+    sleep_time: float = 0.01
 
 
 class AccountSequenceNumber:
@@ -46,7 +56,12 @@ class AccountSequenceNumber:
     _last_committed_number: Optional[int]
     _current_number: Optional[int]
 
-    def __init__(self, client: RestClient, account: AccountAddress):
+    def __init__(
+        self,
+        client: RestClient,
+        account: AccountAddress,
+        config: AccountSequenceNumberConfig = AccountSequenceNumberConfig(),
+    ):
         self._client = client
         self._account = account
         self._lock = asyncio.Lock()
@@ -54,6 +69,10 @@ def __init__(self, client: RestClient, account: AccountAddress):
         self._last_uncommitted_number = None
         self._current_number = None
 
+        self._maximum_in_flight = config.maximum_in_flight
+        self._maximum_wait_time = config.maximum_wait_time
+        self._sleep_time = config.sleep_time
+
     async def next_sequence_number(self, block: bool = True) -> Optional[int]:
         """
         Returns the next sequence number available on this account. This leverages a lock to
@@ -69,22 +88,16 @@ async def next_sequence_number(self, block: bool = True) -> Optional[int]:
                 >= self._maximum_in_flight
             ):
                 await self._update()
-                start_time = time.time()
-                while (
+                if (
                     self._current_number - self._last_uncommitted_number
                     >= self._maximum_in_flight
                 ):
                     if not block:
                         return None
-
-                    await asyncio.sleep(self._sleep_time)
-                    if time.time() - start_time > self._maximum_wait_time:
-                        logging.warn(
-                            f"Waited over {self._maximum_wait_time} seconds for a transaction to commit, resyncing {self._account}"
-                        )
-                        await self._initialize()
-                    else:
-                        await self._update()
+                    await self._resync(
+                        lambda acn: acn._current_number - acn._last_uncommitted_number
+                        >= acn._maximum_in_flight
+                    )
 
             next_number = self._current_number
             self._current_number += 1
@@ -103,16 +116,42 @@ async def synchronize(self):
         """
         async with self._lock:
             await self._update()
-            start_time = time.time()
-            while self._last_uncommitted_number != self._current_number:
-                if time.time() - start_time > self._maximum_wait_time:
-                    logging.warn(
-                        f"Waited over {self._maximum_wait_time} seconds for a transaction to commit, resyncing {self._account}"
+            await self._resync(
+                lambda acn: acn._last_uncommitted_number != acn._current_number
+            )
+
+    async def _resync(self, check: Callable[[AccountSequenceNumber], bool]):
+        """Forces a resync with the upstream, this should be called within the lock"""
+        start_time = await self._client.current_timestamp()
+        failed = False
+        while check(self):
+            ledger_time = await self._client.current_timestamp()
+            if ledger_time - start_time > self._maximum_wait_time:
+                logging.warn(
+                    f"Waited over {self._maximum_wait_time} seconds for a transaction to commit, resyncing {self._account}"
+                )
+                failed = True
+                break
+            else:
+                await asyncio.sleep(self._sleep_time)
+                await self._update()
+        if not failed:
+            return
+        for seq_num in range(self._last_uncommitted_number + 1, self._current_number):
+            while True:
+                try:
+                    result = (
+                        await self._client.account_transaction_sequence_number_status(
+                            self._account, seq_num
+                        )
                     )
-                    await self._initialize()
-                else:
-                    await asyncio.sleep(self._sleep_time)
-                    await self._update()
+                    if result:
+                        break
+                except ApiError as error:
+                    if error.status_code == 404:
+                        break
+                    raise
+        await self._initialize()
 
     async def _update(self):
         self._last_uncommitted_number = await self._current_sequence_number()
diff --git a/ecosystem/python/sdk/aptos_sdk/async_client.py b/ecosystem/python/sdk/aptos_sdk/async_client.py
index 15e3d4284b962..466dee13747e7 100644
--- a/ecosystem/python/sdk/aptos_sdk/async_client.py
+++ b/ecosystem/python/sdk/aptos_sdk/async_client.py
@@ -2,6 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import asyncio
+import logging
 import time
 from typing import Any, Dict, List, Optional
 
@@ -53,7 +54,10 @@ def __init__(self, base_url: str, client_config: ClientConfig = ClientConfig()):
         # Default headers
         headers = {Metadata.APTOS_HEADER: Metadata.get_aptos_header_val()}
         self.client = httpx.AsyncClient(
-            http2=client_config.http2, limits=limits, timeout=timeout, headers=headers
+            http2=client_config.http2,
+            limits=limits,
+            timeout=timeout,
+            headers=headers,
         )
         self.client_config = client_config
         self._chain_id = None
@@ -140,6 +144,10 @@ async def account_resources(
             raise ApiError(f"{response.text} - {account_address}", response.status_code)
         return response.json()
 
+    async def current_timestamp(self) -> float:
+        info = await self.info()
+        return float(info["ledger_timestamp"]) / 1_000_000
+
     async def get_table_item(
         self,
         handle: str,
@@ -332,6 +340,20 @@ async def wait_for_transaction(self, txn_hash: str) -> None:
             "success" in response.json() and response.json()["success"]
         ), f"{response.text} - {txn_hash}"
 
+    async def account_transaction_sequence_number_status(
+        self, address: AccountAddress, sequence_number: int
+    ) -> bool:
+        """Retrieve the state of a transaction by account and sequence number."""
+
+        response = await self.client.get(
+            f"{self.base_url}/accounts/{address}/transactions?limit=1&start={sequence_number}"
+        )
+        if response.status_code >= 400:
+            logging.info(f"k {response}")
+            raise ApiError(response.text, response.status_code)
+        data = response.json()
+        return len(data) == 1 and data[0]["type"] != "pending_transaction"
+
     #
     # Transaction helpers
     #
diff --git a/ecosystem/python/sdk/examples/transaction-batching.py b/ecosystem/python/sdk/examples/transaction-batching.py
index 3f9472e271bff..1bb671b5abc5c 100644
--- a/ecosystem/python/sdk/examples/transaction-batching.py
+++ b/ecosystem/python/sdk/examples/transaction-batching.py
@@ -136,7 +136,6 @@ def run(queue: Pipe, node_url: str, account: Account, recipient: AccountAddress)
         asyncio.run(worker.async_run())
 
     async def async_run(self):
-        print(f"hello from {self._account.address()}")
         try:
             self._txn_worker.start()
 
@@ -145,12 +144,16 @@ async def async_run(self):
 
             await self._txn_generator.increase_transaction_count(num_txns)
 
-            print(f"Increase txns from {self._account.address()}")
+            logging.info(f"Increase txns from {self._account.address()}")
             self._conn.send(True)
             self._conn.recv()
 
             txn_hashes = []
             while num_txns != 0:
+                if num_txns % 100 == 0:
+                    logging.info(
+                        f"{self._txn_worker.address()} remaining transactions {num_txns}"
+                    )
                 num_txns -= 1
                 (
                     sequence_number,
@@ -165,7 +168,7 @@ async def async_run(self):
                 else:
                     txn_hashes.append(txn_hash)
 
-            print(f"Submitted txns from {self._account.address()}", flush=True)
+            logging.info(f"Submitted txns from {self._account.address()}")
             self._conn.send(True)
             self._conn.recv()
 
@@ -173,7 +176,7 @@ async def async_run(self):
                 await self._rest_client.wait_for_transaction(txn_hash)
 
             await self._rest_client.close()
-            print(f"Verified txns from {self._account.address()}", flush=True)
+            logging.info(f"Verified txns from {self._account.address()}")
             self._conn.send(True)
         except Exception as e:
             logging.error(
@@ -338,10 +341,12 @@ async def main():
     client_config.http2 = True
     rest_client = RestClient(NODE_URL, client_config)
 
-    num_accounts = 16
-    transactions = 10000
+    num_accounts = 64
+    transactions = 100000
     start = time.time()
 
+    logging.getLogger().setLevel(20)
+
     print("Starting...")
 
     # Generate will create new accounts, load will load existing accounts

From e5a981cdf48c8bcac65a504b2956230e913517c7 Mon Sep 17 00:00:00 2001
From: David Wolinsky 
Date: Thu, 8 Jun 2023 18:41:40 -0700
Subject: [PATCH 115/200] [python] remove unnecessary python dependencies

---
 ecosystem/python/sdk/Makefile       |   6 +-
 ecosystem/python/sdk/poetry.lock    | 212 +++++++++++++---------------
 ecosystem/python/sdk/pyproject.toml |   3 +-
 ecosystem/python/sdk/setup.py       |  23 ---
 4 files changed, 104 insertions(+), 140 deletions(-)
 delete mode 100644 ecosystem/python/sdk/setup.py

diff --git a/ecosystem/python/sdk/Makefile b/ecosystem/python/sdk/Makefile
index 8131281ef3f38..48cf36dae9907 100644
--- a/ecosystem/python/sdk/Makefile
+++ b/ecosystem/python/sdk/Makefile
@@ -10,12 +10,12 @@ test-coverage:
 
 fmt:
 	find ./examples ./aptos_sdk *.py -type f -name "*.py" | xargs poetry run autoflake -i -r --remove-all-unused-imports --remove-unused-variables --ignore-init-module-imports
-	poetry run isort aptos_sdk examples setup.py
-	poetry run black aptos_sdk examples setup.py
+	poetry run isort aptos_sdk examples
+	poetry run black aptos_sdk examples
 
 lint:
 	- poetry run mypy aptos_sdk
-	- poetry run flake8 aptos_sdk examples setup.py
+	- poetry run flake8 aptos_sdk examples
 
 examples:
 	poetry run python -m examples.async-read-aggregator
diff --git a/ecosystem/python/sdk/poetry.lock b/ecosystem/python/sdk/poetry.lock
index 34cad1d1642ad..e5708e47e2648 100644
--- a/ecosystem/python/sdk/poetry.lock
+++ b/ecosystem/python/sdk/poetry.lock
@@ -1,32 +1,31 @@
-# This file is automatically @generated by Poetry 1.4.2 and should not be changed by hand.
+# This file is automatically @generated by Poetry 1.5.1 and should not be changed by hand.
 
 [[package]]
 name = "anyio"
-version = "3.6.2"
+version = "3.7.0"
 description = "High level compatibility layer for multiple asynchronous event loop implementations"
-category = "main"
 optional = false
-python-versions = ">=3.6.2"
+python-versions = ">=3.7"
 files = [
-    {file = "anyio-3.6.2-py3-none-any.whl", hash = "sha256:fbbe32bd270d2a2ef3ed1c5d45041250284e31fc0a4df4a5a6071842051a51e3"},
-    {file = "anyio-3.6.2.tar.gz", hash = "sha256:25ea0d673ae30af41a0c442f81cf3b38c7e79fdc7b60335a4c14e05eb0947421"},
+    {file = "anyio-3.7.0-py3-none-any.whl", hash = "sha256:eddca883c4175f14df8aedce21054bfca3adb70ffe76a9f607aef9d7fa2ea7f0"},
+    {file = "anyio-3.7.0.tar.gz", hash = "sha256:275d9973793619a5374e1c89a4f4ad3f4b0a5510a2b5b939444bee8f4c4d37ce"},
 ]
 
 [package.dependencies]
+exceptiongroup = {version = "*", markers = "python_version < \"3.11\""}
 idna = ">=2.8"
 sniffio = ">=1.1"
 typing-extensions = {version = "*", markers = "python_version < \"3.8\""}
 
 [package.extras]
-doc = ["packaging", "sphinx-autodoc-typehints (>=1.2.0)", "sphinx-rtd-theme"]
-test = ["contextlib2", "coverage[toml] (>=4.5)", "hypothesis (>=4.0)", "mock (>=4)", "pytest (>=7.0)", "pytest-mock (>=3.6.1)", "trustme", "uvloop (<0.15)", "uvloop (>=0.15)"]
-trio = ["trio (>=0.16,<0.22)"]
+doc = ["Sphinx (>=6.1.0)", "packaging", "sphinx-autodoc-typehints (>=1.2.0)", "sphinx-rtd-theme", "sphinxcontrib-jquery"]
+test = ["anyio[trio]", "coverage[toml] (>=4.5)", "hypothesis (>=4.0)", "mock (>=4)", "psutil (>=5.9)", "pytest (>=7.0)", "pytest-mock (>=3.6.1)", "trustme", "uvloop (>=0.17)"]
+trio = ["trio (<0.22)"]
 
 [[package]]
 name = "autoflake"
 version = "1.4"
 description = "Removes unused imports and unused variables"
-category = "dev"
 optional = false
 python-versions = "*"
 files = [
@@ -40,7 +39,6 @@ pyflakes = ">=1.1.0"
 name = "black"
 version = "22.12.0"
 description = "The uncompromising code formatter."
-category = "dev"
 optional = false
 python-versions = ">=3.7"
 files = [
@@ -75,21 +73,19 @@ uvloop = ["uvloop (>=0.15.2)"]
 
 [[package]]
 name = "certifi"
-version = "2022.12.7"
+version = "2023.5.7"
 description = "Python package for providing Mozilla's CA Bundle."
-category = "main"
 optional = false
 python-versions = ">=3.6"
 files = [
-    {file = "certifi-2022.12.7-py3-none-any.whl", hash = "sha256:4ad3232f5e926d6718ec31cfc1fcadfde020920e278684144551c91769c7bc18"},
-    {file = "certifi-2022.12.7.tar.gz", hash = "sha256:35824b4c3a97115964b408844d64aa14db1cc518f6562e8d7261699d1350a9e3"},
+    {file = "certifi-2023.5.7-py3-none-any.whl", hash = "sha256:c6c2e98f5c7869efca1f8916fed228dd91539f9f1b444c314c06eef02980c716"},
+    {file = "certifi-2023.5.7.tar.gz", hash = "sha256:0f0d56dc5a6ad56fd4ba36484d6cc34451e1c6548c61daad8c320169f91eddc7"},
 ]
 
 [[package]]
 name = "cffi"
 version = "1.15.1"
 description = "Foreign Function Interface for Python calling C code."
-category = "main"
 optional = false
 python-versions = "*"
 files = [
@@ -166,7 +162,6 @@ pycparser = "*"
 name = "click"
 version = "8.1.3"
 description = "Composable command line interface toolkit"
-category = "dev"
 optional = false
 python-versions = ">=3.7"
 files = [
@@ -182,7 +177,6 @@ importlib-metadata = {version = "*", markers = "python_version < \"3.8\""}
 name = "colorama"
 version = "0.4.6"
 description = "Cross-platform colored terminal text."
-category = "dev"
 optional = false
 python-versions = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,>=2.7"
 files = [
@@ -192,76 +186,94 @@ files = [
 
 [[package]]
 name = "coverage"
-version = "7.2.4"
+version = "7.2.7"
 description = "Code coverage measurement for Python"
-category = "dev"
 optional = false
 python-versions = ">=3.7"
 files = [
-    {file = "coverage-7.2.4-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:9e5eedde6e6e241ec3816f05767cc77e7456bf5ec6b373fb29917f0990e2078f"},
-    {file = "coverage-7.2.4-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:5c6c6e3b8fb6411a2035da78d86516bfcfd450571d167304911814407697fb7a"},
-    {file = "coverage-7.2.4-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f7668a621afc52db29f6867e0e9c72a1eec9f02c94a7c36599119d557cf6e471"},
-    {file = "coverage-7.2.4-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:cdfb53bef4b2739ff747ebbd76d6ac5384371fd3c7a8af08899074eba034d483"},
-    {file = "coverage-7.2.4-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:a5c4f2e44a2ae15fa6883898e756552db5105ca4bd918634cbd5b7c00e19e8a1"},
-    {file = "coverage-7.2.4-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:700bc9fb1074e0c67c09fe96a803de66663830420781df8dc9fb90d7421d4ccb"},
-    {file = "coverage-7.2.4-cp310-cp310-musllinux_1_1_i686.whl", hash = "sha256:ac4861241e693e21b280f07844ae0e0707665e1dfcbf9466b793584984ae45c4"},
-    {file = "coverage-7.2.4-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:3d6f3c5b6738a494f17c73b4aa3aa899865cc33a74aa85e3b5695943b79ad3ce"},
-    {file = "coverage-7.2.4-cp310-cp310-win32.whl", hash = "sha256:437da7d2fcc35bf45e04b7e9cfecb7c459ec6f6dc17a8558ed52e8d666c2d9ab"},
-    {file = "coverage-7.2.4-cp310-cp310-win_amd64.whl", hash = "sha256:1d3893f285fd76f56651f04d1efd3bdce251c32992a64c51e5d6ec3ba9e3f9c9"},
-    {file = "coverage-7.2.4-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:6a17bf32e9e3333d78606ac1073dd20655dc0752d5b923fa76afd3bc91674ab4"},
-    {file = "coverage-7.2.4-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:f7ffdb3af2a01ce91577f84fc0faa056029fe457f3183007cffe7b11ea78b23c"},
-    {file = "coverage-7.2.4-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:89e63b38c7b888e00fd42ce458f838dccb66de06baea2da71801b0fc9070bfa0"},
-    {file = "coverage-7.2.4-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:4522dd9aeb9cc2c4c54ce23933beb37a4e106ec2ba94f69138c159024c8a906a"},
-    {file = "coverage-7.2.4-cp311-cp311-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:29c7d88468f01a75231797173b52dc66d20a8d91b8bb75c88fc5861268578f52"},
-    {file = "coverage-7.2.4-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:bc47015fc0455753e8aba1f38b81b731aaf7f004a0c390b404e0fcf1d6c1d72f"},
-    {file = "coverage-7.2.4-cp311-cp311-musllinux_1_1_i686.whl", hash = "sha256:5c122d120c11a236558c339a59b4b60947b38ac9e3ad30a0e0e02540b37bf536"},
-    {file = "coverage-7.2.4-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:50fda3d33b705b9c01e3b772cfa7d14de8aec2ec2870e4320992c26d057fde12"},
-    {file = "coverage-7.2.4-cp311-cp311-win32.whl", hash = "sha256:ab08af91cf4d847a6e15d7d5eeae5fead1487caf16ff3a2056dbe64d058fd246"},
-    {file = "coverage-7.2.4-cp311-cp311-win_amd64.whl", hash = "sha256:876e4ef3eff00b50787867c5bae84857a9af4c369a9d5b266cd9b19f61e48ef7"},
-    {file = "coverage-7.2.4-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:3fc9cde48de956bfbacea026936fbd4974ff1dc2f83397c6f1968f0142c9d50b"},
-    {file = "coverage-7.2.4-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:12bc9127c8aca2f7c25c9acca53da3db6799b2999b40f28c2546237b7ea28459"},
-    {file = "coverage-7.2.4-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:2857894c22833d3da6e113623a9b7440159b2295280b4e0d954cadbfa724b85a"},
-    {file = "coverage-7.2.4-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:d4db4e6c115d869cd5397d3d21fd99e4c7053205c33a4ae725c90d19dcd178af"},
-    {file = "coverage-7.2.4-cp37-cp37m-musllinux_1_1_aarch64.whl", hash = "sha256:f37ae1804596f13d811e0247ffc8219f5261b3565bdf45fcbb4fc091b8e9ff35"},
-    {file = "coverage-7.2.4-cp37-cp37m-musllinux_1_1_i686.whl", hash = "sha256:cdee9a77fd0ce000781680b6a1f4b721c567f66f2f73a49be1843ff439d634f3"},
-    {file = "coverage-7.2.4-cp37-cp37m-musllinux_1_1_x86_64.whl", hash = "sha256:0b65a6a5484b7f2970393d6250553c05b2ede069e0e18abe907fdc7f3528252e"},
-    {file = "coverage-7.2.4-cp37-cp37m-win32.whl", hash = "sha256:1a3e8697cb40f28e5bcfb6f4bda7852d96dbb6f6fd7cc306aba4ae690c9905ab"},
-    {file = "coverage-7.2.4-cp37-cp37m-win_amd64.whl", hash = "sha256:4078939c4b7053e14e87c65aa68dbed7867e326e450f94038bfe1a1b22078ff9"},
-    {file = "coverage-7.2.4-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:603a2b172126e3b08c11ca34200143089a088cd0297d4cfc4922d2c1c3a892f9"},
-    {file = "coverage-7.2.4-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:72751d117ceaad3b1ea3bcb9e85f5409bbe9fb8a40086e17333b994dbccc0718"},
-    {file = "coverage-7.2.4-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f19ba9301e6fb0b94ba71fda9a1b02d11f0aab7f8e2455122a4e2921b6703c2f"},
-    {file = "coverage-7.2.4-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:2d784177a7fb9d0f58d24d3e60638c8b729c3693963bf67fa919120f750db237"},
-    {file = "coverage-7.2.4-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:1d2a9180beff1922b09bd7389e23454928e108449e646c26da5c62e29b0bf4e3"},
-    {file = "coverage-7.2.4-cp38-cp38-musllinux_1_1_aarch64.whl", hash = "sha256:39747afc854a7ee14e5e132da7db179d6281faf97dc51e6d7806651811c47538"},
-    {file = "coverage-7.2.4-cp38-cp38-musllinux_1_1_i686.whl", hash = "sha256:60feb703abc8d78e9427d873bcf924c9e30cf540a21971ef5a17154da763b60f"},
-    {file = "coverage-7.2.4-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:c2becddfcbf3d994a8f4f9dd2b6015cae3a3eff50dedc6e4a17c3cccbe8f93d4"},
-    {file = "coverage-7.2.4-cp38-cp38-win32.whl", hash = "sha256:56a674ad18d6b04008283ca03c012be913bf89d91c0803c54c24600b300d9e51"},
-    {file = "coverage-7.2.4-cp38-cp38-win_amd64.whl", hash = "sha256:ab08e03add2cf5793e66ac1bbbb24acfa90c125476f5724f5d44c56eeec1d635"},
-    {file = "coverage-7.2.4-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:92b565c51732ea2e7e541709ccce76391b39f4254260e5922e08e00971e88e33"},
-    {file = "coverage-7.2.4-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:8769a67e8816c7e94d5bf446fc0501641fde78fdff362feb28c2c64d45d0e9b1"},
-    {file = "coverage-7.2.4-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:56d74d6fbd5a98a5629e8467b719b0abea9ca01a6b13555d125c84f8bf4ea23d"},
-    {file = "coverage-7.2.4-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:d9f770c6052d9b5c9b0e824fd8c003fe33276473b65b4f10ece9565ceb62438e"},
-    {file = "coverage-7.2.4-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b3023ce23e41a6f006c09f7e6d62b6c069c36bdc9f7de16a5ef823acc02e6c63"},
-    {file = "coverage-7.2.4-cp39-cp39-musllinux_1_1_aarch64.whl", hash = "sha256:fabd1f4d12dfd6b4f309208c2f31b116dc5900e0b42dbafe4ee1bc7c998ffbb0"},
-    {file = "coverage-7.2.4-cp39-cp39-musllinux_1_1_i686.whl", hash = "sha256:e41a7f44e73b37c6f0132ecfdc1c8b67722f42a3d9b979e6ebc150c8e80cf13a"},
-    {file = "coverage-7.2.4-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:864e36947289be05abd83267c4bade35e772526d3e9653444a9dc891faf0d698"},
-    {file = "coverage-7.2.4-cp39-cp39-win32.whl", hash = "sha256:ea534200efbf600e60130c48552f99f351cae2906898a9cd924c1c7f2fb02853"},
-    {file = "coverage-7.2.4-cp39-cp39-win_amd64.whl", hash = "sha256:00f8fd8a5fe1ffc3aef78ea2dbf553e5c0f4664324e878995e38d41f037eb2b3"},
-    {file = "coverage-7.2.4-pp37.pp38.pp39-none-any.whl", hash = "sha256:856bcb837e96adede31018a0854ce7711a5d6174db1a84e629134970676c54fa"},
-    {file = "coverage-7.2.4.tar.gz", hash = "sha256:7283f78d07a201ac7d9dc2ac2e4faaea99c4d302f243ee5b4e359f3e170dc008"},
+    {file = "coverage-7.2.7-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:d39b5b4f2a66ccae8b7263ac3c8170994b65266797fb96cbbfd3fb5b23921db8"},
+    {file = "coverage-7.2.7-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:6d040ef7c9859bb11dfeb056ff5b3872436e3b5e401817d87a31e1750b9ae2fb"},
+    {file = "coverage-7.2.7-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ba90a9563ba44a72fda2e85302c3abc71c5589cea608ca16c22b9804262aaeb6"},
+    {file = "coverage-7.2.7-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:e7d9405291c6928619403db1d10bd07888888ec1abcbd9748fdaa971d7d661b2"},
+    {file = "coverage-7.2.7-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:31563e97dae5598556600466ad9beea39fb04e0229e61c12eaa206e0aa202063"},
+    {file = "coverage-7.2.7-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:ebba1cd308ef115925421d3e6a586e655ca5a77b5bf41e02eb0e4562a111f2d1"},
+    {file = "coverage-7.2.7-cp310-cp310-musllinux_1_1_i686.whl", hash = "sha256:cb017fd1b2603ef59e374ba2063f593abe0fc45f2ad9abdde5b4d83bd922a353"},
+    {file = "coverage-7.2.7-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:d62a5c7dad11015c66fbb9d881bc4caa5b12f16292f857842d9d1871595f4495"},
+    {file = "coverage-7.2.7-cp310-cp310-win32.whl", hash = "sha256:ee57190f24fba796e36bb6d3aa8a8783c643d8fa9760c89f7a98ab5455fbf818"},
+    {file = "coverage-7.2.7-cp310-cp310-win_amd64.whl", hash = "sha256:f75f7168ab25dd93110c8a8117a22450c19976afbc44234cbf71481094c1b850"},
+    {file = "coverage-7.2.7-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:06a9a2be0b5b576c3f18f1a241f0473575c4a26021b52b2a85263a00f034d51f"},
+    {file = "coverage-7.2.7-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:5baa06420f837184130752b7c5ea0808762083bf3487b5038d68b012e5937dbe"},
+    {file = "coverage-7.2.7-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:fdec9e8cbf13a5bf63290fc6013d216a4c7232efb51548594ca3631a7f13c3a3"},
+    {file = "coverage-7.2.7-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:52edc1a60c0d34afa421c9c37078817b2e67a392cab17d97283b64c5833f427f"},
+    {file = "coverage-7.2.7-cp311-cp311-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:63426706118b7f5cf6bb6c895dc215d8a418d5952544042c8a2d9fe87fcf09cb"},
+    {file = "coverage-7.2.7-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:afb17f84d56068a7c29f5fa37bfd38d5aba69e3304af08ee94da8ed5b0865833"},
+    {file = "coverage-7.2.7-cp311-cp311-musllinux_1_1_i686.whl", hash = "sha256:48c19d2159d433ccc99e729ceae7d5293fbffa0bdb94952d3579983d1c8c9d97"},
+    {file = "coverage-7.2.7-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:0e1f928eaf5469c11e886fe0885ad2bf1ec606434e79842a879277895a50942a"},
+    {file = "coverage-7.2.7-cp311-cp311-win32.whl", hash = "sha256:33d6d3ea29d5b3a1a632b3c4e4f4ecae24ef170b0b9ee493883f2df10039959a"},
+    {file = "coverage-7.2.7-cp311-cp311-win_amd64.whl", hash = "sha256:5b7540161790b2f28143191f5f8ec02fb132660ff175b7747b95dcb77ac26562"},
+    {file = "coverage-7.2.7-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:f2f67fe12b22cd130d34d0ef79206061bfb5eda52feb6ce0dba0644e20a03cf4"},
+    {file = "coverage-7.2.7-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a342242fe22407f3c17f4b499276a02b01e80f861f1682ad1d95b04018e0c0d4"},
+    {file = "coverage-7.2.7-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:171717c7cb6b453aebac9a2ef603699da237f341b38eebfee9be75d27dc38e01"},
+    {file = "coverage-7.2.7-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:49969a9f7ffa086d973d91cec8d2e31080436ef0fb4a359cae927e742abfaaa6"},
+    {file = "coverage-7.2.7-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:b46517c02ccd08092f4fa99f24c3b83d8f92f739b4657b0f146246a0ca6a831d"},
+    {file = "coverage-7.2.7-cp312-cp312-musllinux_1_1_i686.whl", hash = "sha256:a3d33a6b3eae87ceaefa91ffdc130b5e8536182cd6dfdbfc1aa56b46ff8c86de"},
+    {file = "coverage-7.2.7-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:976b9c42fb2a43ebf304fa7d4a310e5f16cc99992f33eced91ef6f908bd8f33d"},
+    {file = "coverage-7.2.7-cp312-cp312-win32.whl", hash = "sha256:8de8bb0e5ad103888d65abef8bca41ab93721647590a3f740100cd65c3b00511"},
+    {file = "coverage-7.2.7-cp312-cp312-win_amd64.whl", hash = "sha256:9e31cb64d7de6b6f09702bb27c02d1904b3aebfca610c12772452c4e6c21a0d3"},
+    {file = "coverage-7.2.7-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:58c2ccc2f00ecb51253cbe5d8d7122a34590fac9646a960d1430d5b15321d95f"},
+    {file = "coverage-7.2.7-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d22656368f0e6189e24722214ed8d66b8022db19d182927b9a248a2a8a2f67eb"},
+    {file = "coverage-7.2.7-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:a895fcc7b15c3fc72beb43cdcbdf0ddb7d2ebc959edac9cef390b0d14f39f8a9"},
+    {file = "coverage-7.2.7-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e84606b74eb7de6ff581a7915e2dab7a28a0517fbe1c9239eb227e1354064dcd"},
+    {file = "coverage-7.2.7-cp37-cp37m-musllinux_1_1_aarch64.whl", hash = "sha256:0a5f9e1dbd7fbe30196578ca36f3fba75376fb99888c395c5880b355e2875f8a"},
+    {file = "coverage-7.2.7-cp37-cp37m-musllinux_1_1_i686.whl", hash = "sha256:419bfd2caae268623dd469eff96d510a920c90928b60f2073d79f8fe2bbc5959"},
+    {file = "coverage-7.2.7-cp37-cp37m-musllinux_1_1_x86_64.whl", hash = "sha256:2aee274c46590717f38ae5e4650988d1af340fe06167546cc32fe2f58ed05b02"},
+    {file = "coverage-7.2.7-cp37-cp37m-win32.whl", hash = "sha256:61b9a528fb348373c433e8966535074b802c7a5d7f23c4f421e6c6e2f1697a6f"},
+    {file = "coverage-7.2.7-cp37-cp37m-win_amd64.whl", hash = "sha256:b1c546aca0ca4d028901d825015dc8e4d56aac4b541877690eb76490f1dc8ed0"},
+    {file = "coverage-7.2.7-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:54b896376ab563bd38453cecb813c295cf347cf5906e8b41d340b0321a5433e5"},
+    {file = "coverage-7.2.7-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:3d376df58cc111dc8e21e3b6e24606b5bb5dee6024f46a5abca99124b2229ef5"},
+    {file = "coverage-7.2.7-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5e330fc79bd7207e46c7d7fd2bb4af2963f5f635703925543a70b99574b0fea9"},
+    {file = "coverage-7.2.7-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:1e9d683426464e4a252bf70c3498756055016f99ddaec3774bf368e76bbe02b6"},
+    {file = "coverage-7.2.7-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8d13c64ee2d33eccf7437961b6ea7ad8673e2be040b4f7fd4fd4d4d28d9ccb1e"},
+    {file = "coverage-7.2.7-cp38-cp38-musllinux_1_1_aarch64.whl", hash = "sha256:b7aa5f8a41217360e600da646004f878250a0d6738bcdc11a0a39928d7dc2050"},
+    {file = "coverage-7.2.7-cp38-cp38-musllinux_1_1_i686.whl", hash = "sha256:8fa03bce9bfbeeef9f3b160a8bed39a221d82308b4152b27d82d8daa7041fee5"},
+    {file = "coverage-7.2.7-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:245167dd26180ab4c91d5e1496a30be4cd721a5cf2abf52974f965f10f11419f"},
+    {file = "coverage-7.2.7-cp38-cp38-win32.whl", hash = "sha256:d2c2db7fd82e9b72937969bceac4d6ca89660db0a0967614ce2481e81a0b771e"},
+    {file = "coverage-7.2.7-cp38-cp38-win_amd64.whl", hash = "sha256:2e07b54284e381531c87f785f613b833569c14ecacdcb85d56b25c4622c16c3c"},
+    {file = "coverage-7.2.7-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:537891ae8ce59ef63d0123f7ac9e2ae0fc8b72c7ccbe5296fec45fd68967b6c9"},
+    {file = "coverage-7.2.7-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:06fb182e69f33f6cd1d39a6c597294cff3143554b64b9825d1dc69d18cc2fff2"},
+    {file = "coverage-7.2.7-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:201e7389591af40950a6480bd9edfa8ed04346ff80002cec1a66cac4549c1ad7"},
+    {file = "coverage-7.2.7-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:f6951407391b639504e3b3be51b7ba5f3528adbf1a8ac3302b687ecababf929e"},
+    {file = "coverage-7.2.7-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6f48351d66575f535669306aa7d6d6f71bc43372473b54a832222803eb956fd1"},
+    {file = "coverage-7.2.7-cp39-cp39-musllinux_1_1_aarch64.whl", hash = "sha256:b29019c76039dc3c0fd815c41392a044ce555d9bcdd38b0fb60fb4cd8e475ba9"},
+    {file = "coverage-7.2.7-cp39-cp39-musllinux_1_1_i686.whl", hash = "sha256:81c13a1fc7468c40f13420732805a4c38a105d89848b7c10af65a90beff25250"},
+    {file = "coverage-7.2.7-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:975d70ab7e3c80a3fe86001d8751f6778905ec723f5b110aed1e450da9d4b7f2"},
+    {file = "coverage-7.2.7-cp39-cp39-win32.whl", hash = "sha256:7ee7d9d4822c8acc74a5e26c50604dff824710bc8de424904c0982e25c39c6cb"},
+    {file = "coverage-7.2.7-cp39-cp39-win_amd64.whl", hash = "sha256:eb393e5ebc85245347950143969b241d08b52b88a3dc39479822e073a1a8eb27"},
+    {file = "coverage-7.2.7-pp37.pp38.pp39-none-any.whl", hash = "sha256:b7b4c971f05e6ae490fef852c218b0e79d4e52f79ef0c8475566584a8fb3e01d"},
+    {file = "coverage-7.2.7.tar.gz", hash = "sha256:924d94291ca674905fe9481f12294eb11f2d3d3fd1adb20314ba89e94f44ed59"},
 ]
 
-[package.dependencies]
-tomli = {version = "*", optional = true, markers = "python_full_version <= \"3.11.0a6\" and extra == \"toml\""}
-
 [package.extras]
 toml = ["tomli"]
 
+[[package]]
+name = "exceptiongroup"
+version = "1.1.1"
+description = "Backport of PEP 654 (exception groups)"
+optional = false
+python-versions = ">=3.7"
+files = [
+    {file = "exceptiongroup-1.1.1-py3-none-any.whl", hash = "sha256:232c37c63e4f682982c8b6459f33a8981039e5fb8756b2074364e5055c498c9e"},
+    {file = "exceptiongroup-1.1.1.tar.gz", hash = "sha256:d484c3090ba2889ae2928419117447a14daf3c1231d5e30d0aae34f354f01785"},
+]
+
+[package.extras]
+test = ["pytest (>=6)"]
+
 [[package]]
 name = "flake8"
 version = "5.0.4"
 description = "the modular source code checker: pep8 pyflakes and co"
-category = "dev"
 optional = false
 python-versions = ">=3.6.1"
 files = [
@@ -279,7 +291,6 @@ pyflakes = ">=2.5.0,<2.6.0"
 name = "h11"
 version = "0.14.0"
 description = "A pure-Python, bring-your-own-I/O implementation of HTTP/1.1"
-category = "main"
 optional = false
 python-versions = ">=3.7"
 files = [
@@ -294,7 +305,6 @@ typing-extensions = {version = "*", markers = "python_version < \"3.8\""}
 name = "h2"
 version = "4.1.0"
 description = "HTTP/2 State-Machine based protocol implementation"
-category = "main"
 optional = false
 python-versions = ">=3.6.1"
 files = [
@@ -310,7 +320,6 @@ hyperframe = ">=6.0,<7"
 name = "hpack"
 version = "4.0.0"
 description = "Pure-Python HPACK header compression"
-category = "main"
 optional = false
 python-versions = ">=3.6.1"
 files = [
@@ -322,7 +331,6 @@ files = [
 name = "httpcore"
 version = "0.16.3"
 description = "A minimal low-level HTTP client."
-category = "main"
 optional = false
 python-versions = ">=3.7"
 files = [
@@ -334,17 +342,16 @@ files = [
 anyio = ">=3.0,<5.0"
 certifi = "*"
 h11 = ">=0.13,<0.15"
-sniffio = ">=1.0.0,<2.0.0"
+sniffio = "==1.*"
 
 [package.extras]
 http2 = ["h2 (>=3,<5)"]
-socks = ["socksio (>=1.0.0,<2.0.0)"]
+socks = ["socksio (==1.*)"]
 
 [[package]]
 name = "httpx"
 version = "0.23.3"
 description = "The next generation HTTP client."
-category = "main"
 optional = false
 python-versions = ">=3.7"
 files = [
@@ -360,15 +367,14 @@ sniffio = "*"
 
 [package.extras]
 brotli = ["brotli", "brotlicffi"]
-cli = ["click (>=8.0.0,<9.0.0)", "pygments (>=2.0.0,<3.0.0)", "rich (>=10,<13)"]
+cli = ["click (==8.*)", "pygments (==2.*)", "rich (>=10,<13)"]
 http2 = ["h2 (>=3,<5)"]
-socks = ["socksio (>=1.0.0,<2.0.0)"]
+socks = ["socksio (==1.*)"]
 
 [[package]]
 name = "hyperframe"
 version = "6.0.1"
 description = "HTTP/2 framing layer for Python"
-category = "main"
 optional = false
 python-versions = ">=3.6.1"
 files = [
@@ -380,7 +386,6 @@ files = [
 name = "idna"
 version = "3.4"
 description = "Internationalized Domain Names in Applications (IDNA)"
-category = "main"
 optional = false
 python-versions = ">=3.5"
 files = [
@@ -392,7 +397,6 @@ files = [
 name = "importlib-metadata"
 version = "4.2.0"
 description = "Read metadata from Python packages"
-category = "dev"
 optional = false
 python-versions = ">=3.6"
 files = [
@@ -412,7 +416,6 @@ testing = ["flufl.flake8", "importlib-resources (>=1.3)", "packaging", "pep517",
 name = "isort"
 version = "5.11.5"
 description = "A Python utility / library to sort Python imports."
-category = "dev"
 optional = false
 python-versions = ">=3.7.0"
 files = [
@@ -430,7 +433,6 @@ requirements-deprecated-finder = ["pip-api", "pipreqs"]
 name = "mccabe"
 version = "0.7.0"
 description = "McCabe checker, plugin for flake8"
-category = "dev"
 optional = false
 python-versions = ">=3.6"
 files = [
@@ -442,7 +444,6 @@ files = [
 name = "mypy"
 version = "0.982"
 description = "Optional static typing for Python"
-category = "dev"
 optional = false
 python-versions = ">=3.7"
 files = [
@@ -487,7 +488,6 @@ reports = ["lxml"]
 name = "mypy-extensions"
 version = "0.4.4"
 description = "Experimental type system extensions for programs checked with the mypy typechecker."
-category = "dev"
 optional = false
 python-versions = ">=2.7"
 files = [
@@ -498,7 +498,6 @@ files = [
 name = "pathspec"
 version = "0.11.1"
 description = "Utility library for gitignore style pattern matching of file paths."
-category = "dev"
 optional = false
 python-versions = ">=3.7"
 files = [
@@ -508,28 +507,26 @@ files = [
 
 [[package]]
 name = "platformdirs"
-version = "3.2.0"
+version = "3.5.1"
 description = "A small Python package for determining appropriate platform-specific dirs, e.g. a \"user data dir\"."
-category = "dev"
 optional = false
 python-versions = ">=3.7"
 files = [
-    {file = "platformdirs-3.2.0-py3-none-any.whl", hash = "sha256:ebe11c0d7a805086e99506aa331612429a72ca7cd52a1f0d277dc4adc20cb10e"},
-    {file = "platformdirs-3.2.0.tar.gz", hash = "sha256:d5b638ca397f25f979350ff789db335903d7ea010ab28903f57b27e1b16c2b08"},
+    {file = "platformdirs-3.5.1-py3-none-any.whl", hash = "sha256:e2378146f1964972c03c085bb5662ae80b2b8c06226c54b2ff4aa9483e8a13a5"},
+    {file = "platformdirs-3.5.1.tar.gz", hash = "sha256:412dae91f52a6f84830f39a8078cecd0e866cb72294a5c66808e74d5e88d251f"},
 ]
 
 [package.dependencies]
 typing-extensions = {version = ">=4.5", markers = "python_version < \"3.8\""}
 
 [package.extras]
-docs = ["furo (>=2022.12.7)", "proselint (>=0.13)", "sphinx (>=6.1.3)", "sphinx-autodoc-typehints (>=1.22,!=1.23.4)"]
-test = ["appdirs (==1.4.4)", "covdefaults (>=2.3)", "pytest (>=7.2.2)", "pytest-cov (>=4)", "pytest-mock (>=3.10)"]
+docs = ["furo (>=2023.3.27)", "proselint (>=0.13)", "sphinx (>=6.2.1)", "sphinx-autodoc-typehints (>=1.23,!=1.23.4)"]
+test = ["appdirs (==1.4.4)", "covdefaults (>=2.3)", "pytest (>=7.3.1)", "pytest-cov (>=4)", "pytest-mock (>=3.10)"]
 
 [[package]]
 name = "pycodestyle"
 version = "2.9.1"
 description = "Python style guide checker"
-category = "dev"
 optional = false
 python-versions = ">=3.6"
 files = [
@@ -541,7 +538,6 @@ files = [
 name = "pycparser"
 version = "2.21"
 description = "C parser in Python"
-category = "main"
 optional = false
 python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"
 files = [
@@ -553,7 +549,6 @@ files = [
 name = "pyflakes"
 version = "2.5.0"
 description = "passive checker of Python programs"
-category = "dev"
 optional = false
 python-versions = ">=3.6"
 files = [
@@ -565,7 +560,6 @@ files = [
 name = "pynacl"
 version = "1.5.0"
 description = "Python binding to the Networking and Cryptography (NaCl) library"
-category = "main"
 optional = false
 python-versions = ">=3.6"
 files = [
@@ -592,7 +586,6 @@ tests = ["hypothesis (>=3.27.0)", "pytest (>=3.2.1,!=3.3.0)"]
 name = "rfc3986"
 version = "1.5.0"
 description = "Validating URI References per RFC 3986"
-category = "main"
 optional = false
 python-versions = "*"
 files = [
@@ -610,7 +603,6 @@ idna2008 = ["idna"]
 name = "sniffio"
 version = "1.3.0"
 description = "Sniff out which async library your code is running under"
-category = "main"
 optional = false
 python-versions = ">=3.7"
 files = [
@@ -622,7 +614,6 @@ files = [
 name = "tomli"
 version = "2.0.1"
 description = "A lil' TOML parser"
-category = "dev"
 optional = false
 python-versions = ">=3.7"
 files = [
@@ -634,7 +625,6 @@ files = [
 name = "typed-ast"
 version = "1.5.4"
 description = "a fork of Python 2 and 3 ast modules with type comment support"
-category = "dev"
 optional = false
 python-versions = ">=3.6"
 files = [
@@ -666,21 +656,19 @@ files = [
 
 [[package]]
 name = "typing-extensions"
-version = "4.5.0"
+version = "4.6.3"
 description = "Backported and Experimental Type Hints for Python 3.7+"
-category = "main"
 optional = false
 python-versions = ">=3.7"
 files = [
-    {file = "typing_extensions-4.5.0-py3-none-any.whl", hash = "sha256:fb33085c39dd998ac16d1431ebc293a8b3eedd00fd4a32de0ff79002c19511b4"},
-    {file = "typing_extensions-4.5.0.tar.gz", hash = "sha256:5cb5f4a79139d699607b3ef622a1dedafa84e115ab0024e0d9c044a9479ca7cb"},
+    {file = "typing_extensions-4.6.3-py3-none-any.whl", hash = "sha256:88a4153d8505aabbb4e13aacb7c486c2b4a33ca3b3f807914a9b4c844c471c26"},
+    {file = "typing_extensions-4.6.3.tar.gz", hash = "sha256:d91d5919357fe7f681a9f2b5b4cb2a5f1ef0a1e9f59c4d8ff0d3491e05c0ffd5"},
 ]
 
 [[package]]
 name = "zipp"
 version = "3.15.0"
 description = "Backport of pathlib-compatible object wrapper for zip files"
-category = "dev"
 optional = false
 python-versions = ">=3.7"
 files = [
@@ -695,4 +683,4 @@ testing = ["big-O", "flake8 (<5)", "jaraco.functools", "jaraco.itertools", "more
 [metadata]
 lock-version = "2.0"
 python-versions = ">=3.7,<4.0"
-content-hash = "d9a288e06237d103a93b496c7e77b124cc4ac79580e4ac6b48842e300c6648a4"
+content-hash = "58444a4ad25fc804f24845b567348e41f0a28dfc8197fe25f6e2391f8bdf2c1b"
diff --git a/ecosystem/python/sdk/pyproject.toml b/ecosystem/python/sdk/pyproject.toml
index 854ff38819ba0..40473f3ca53ec 100644
--- a/ecosystem/python/sdk/pyproject.toml
+++ b/ecosystem/python/sdk/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "aptos-sdk"
-version = "0.6.2"
+version = "0.6.3"
 description = "Aptos SDK"
 authors = ["Aptos Labs "]
 license = "Apache-2.0"
@@ -14,7 +14,6 @@ h2 = "^4.1.0"
 httpx = "^0.23.0"
 PyNaCl = "^1.5.0"
 python = ">=3.7,<4.0"
-importlib = "^1.0.4"
 
 [tool.poetry.dev-dependencies]
 autoflake = "1.4.0"
diff --git a/ecosystem/python/sdk/setup.py b/ecosystem/python/sdk/setup.py
deleted file mode 100644
index b63e624d26eae..0000000000000
--- a/ecosystem/python/sdk/setup.py
+++ /dev/null
@@ -1,23 +0,0 @@
-import setuptools
-
-with open("README.md", "r", encoding="utf-8") as fh:
-    long_description = fh.read()
-
-setuptools.setup(
-    author="Aptos Labs",
-    author_email="opensource@aptoslabs.com",
-    classifiers=[
-        "Programming Language :: Python :: 3",
-        "License :: OSI Approved :: Apache Software License",
-        "Operating System :: OS Independent",
-    ],
-    include_package_data=True,
-    install_requires=["httpx", "pynacl"],
-    long_description=long_description,
-    long_description_content_type="text/markdown",
-    name="aptos_sdk",
-    packages=["aptos_sdk"],
-    python_requires=">=3.7",
-    url="https://github.com/aptos-labs/aptos-core",
-    version="0.6.2",
-)

From 065c93f35997b81db9af0a0f1b3f480901fdac61 Mon Sep 17 00:00:00 2001
From: danielx <66756900+danielxiangzl@users.noreply.github.com>
Date: Thu, 8 Jun 2023 12:17:12 -0700
Subject: [PATCH 116/200] [Execution Benchmark] Calibrate Threshold (#8591)

---
 testsuite/parallel_execution_performance.py | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/testsuite/parallel_execution_performance.py b/testsuite/parallel_execution_performance.py
index df627af4c808f..072b23dc11e1a 100755
--- a/testsuite/parallel_execution_performance.py
+++ b/testsuite/parallel_execution_performance.py
@@ -11,7 +11,7 @@
 THRESHOLDS = {
     "1k_8": 11000,
     "1k_16": 13000,
-    "1k_32": 15000,
+    # "1k_32": 13000,
     "10k_8": 23000,
     "10k_16": 37000,
     "10k_32": 48000,
@@ -23,7 +23,7 @@
 SPEEDUPS = {
     "1k_8": 3,
     "1k_16": 4,
-    "1k_32": 4,
+    # "1k_32": 4,
     "10k_8": 5,
     "10k_16": 8,
     "10k_32": 11,
@@ -58,6 +58,8 @@
     # print(output)
 
     for i, block_size in enumerate(BLOCK_SIZES):
+        if threads == 32 and block_size == "1k":
+            continue
         tps_index = i * 2
         speedup_index = i * 2 + 1
         key = f"{block_size}_{threads}"
@@ -96,6 +98,8 @@
 
 for block_size in BLOCK_SIZES:
     for threads in THREADS:
+        if threads == 32 and block_size == "1k":
+            continue
         key = f"{block_size}_{threads}"
         print(
             f"Average Parallel TPS with {threads} threads for {block_size} block: TPS {tps_set[key]}, Threshold TPS: {THRESHOLDS[key]}, Speedup: {speedups_set[key]}x, Speedup Threshold: {SPEEDUPS[key]}x"

From 255fff00a5725a82aad4ca4be520745676e0661a Mon Sep 17 00:00:00 2001
From: aldenhu 
Date: Wed, 7 Jun 2023 22:12:14 +0000
Subject: [PATCH 117/200] clean AptosVmImpl::new() up a bit

---
 aptos-move/aptos-gas/src/lib.rs               |  4 +-
 aptos-move/aptos-gas/src/transaction/mod.rs   |  2 +-
 .../aptos-gas/src/transaction/storage.rs      | 13 +--
 aptos-move/aptos-vm/src/aptos_vm_impl.rs      | 86 ++++++++++---------
 4 files changed, 52 insertions(+), 53 deletions(-)

diff --git a/aptos-move/aptos-gas/src/lib.rs b/aptos-move/aptos-gas/src/lib.rs
index ddd7fd868146f..e2a091c947d38 100644
--- a/aptos-move/aptos-gas/src/lib.rs
+++ b/aptos-move/aptos-gas/src/lib.rs
@@ -45,4 +45,6 @@ pub use move_core_types::gas_algebra::{
     Arg, Byte, GasQuantity, InternalGas, InternalGasPerArg, InternalGasPerByte, InternalGasUnit,
     NumArgs, NumBytes, UnitDiv,
 };
-pub use transaction::{ChangeSetConfigs, StorageGasParameters, TransactionGasParameters};
+pub use transaction::{
+    ChangeSetConfigs, StorageGasParameters, StoragePricing, TransactionGasParameters,
+};
diff --git a/aptos-move/aptos-gas/src/transaction/mod.rs b/aptos-move/aptos-gas/src/transaction/mod.rs
index 99db9c8d8944e..f2f9533347abf 100644
--- a/aptos-move/aptos-gas/src/transaction/mod.rs
+++ b/aptos-move/aptos-gas/src/transaction/mod.rs
@@ -18,7 +18,7 @@ use move_core_types::gas_algebra::{
 
 mod storage;
 
-pub use storage::{ChangeSetConfigs, StorageGasParameters};
+pub use storage::{ChangeSetConfigs, StorageGasParameters, StoragePricing};
 
 const GAS_SCALING_FACTOR: u64 = 1_000_000;
 
diff --git a/aptos-move/aptos-gas/src/transaction/storage.rs b/aptos-move/aptos-gas/src/transaction/storage.rs
index 1da5181cfecce..8aa7c38593b69 100644
--- a/aptos-move/aptos-gas/src/transaction/storage.rs
+++ b/aptos-move/aptos-gas/src/transaction/storage.rs
@@ -308,14 +308,9 @@ pub struct StorageGasParameters {
 impl StorageGasParameters {
     pub fn new(
         feature_version: u64,
-        gas_params: Option<&AptosGasParameters>,
+        gas_params: &AptosGasParameters,
         storage_gas_schedule: Option<&StorageGasSchedule>,
-    ) -> Option {
-        if feature_version == 0 || gas_params.is_none() {
-            return None;
-        }
-        let gas_params = gas_params.unwrap();
-
+    ) -> Self {
         let pricing = match storage_gas_schedule {
             Some(schedule) => {
                 StoragePricing::V2(StoragePricingV2::new(feature_version, schedule, gas_params))
@@ -325,10 +320,10 @@ impl StorageGasParameters {
 
         let change_set_configs = ChangeSetConfigs::new(feature_version, gas_params);
 
-        Some(Self {
+        Self {
             pricing,
             change_set_configs,
-        })
+        }
     }
 
     pub fn free_and_unlimited() -> Self {
diff --git a/aptos-move/aptos-vm/src/aptos_vm_impl.rs b/aptos-move/aptos-vm/src/aptos_vm_impl.rs
index c5006b4dbbb1a..724b315273e3e 100644
--- a/aptos-move/aptos-vm/src/aptos_vm_impl.rs
+++ b/aptos-move/aptos-vm/src/aptos_vm_impl.rs
@@ -13,7 +13,7 @@ use crate::{
 use aptos_framework::RuntimeModuleMetadataV1;
 use aptos_gas::{
     AbstractValueSizeGasParameters, AptosGasParameters, ChangeSetConfigs, FromOnChainGasSchedule,
-    Gas, NativeGasParameters, StorageGasParameters,
+    Gas, NativeGasParameters, StorageGasParameters, StoragePricing,
 };
 use aptos_logger::{enabled, prelude::*, Level};
 use aptos_state_view::StateView;
@@ -32,6 +32,7 @@ use aptos_vm_types::output::VMOutput;
 use fail::fail_point;
 use move_binary_format::{errors::VMResult, CompiledModule};
 use move_core_types::{
+    gas_algebra::NumArgs,
     language_storage::ModuleId,
     move_resource::MoveStructType,
     value::{serialize_values, MoveValue},
@@ -82,40 +83,41 @@ impl AptosVMImpl {
         let (mut gas_params, gas_feature_version): (Option, u64) =
             gas_config(&storage);
 
-        let storage_gas_schedule = match gas_feature_version {
-            0 => None,
-            _ => StorageGasSchedule::fetch_config(&storage),
-        };
+        let storage_gas_params = if let Some(gas_params) = &mut gas_params {
+            let storage_gas_schedule = match gas_feature_version {
+                0 => None,
+                _ => StorageGasSchedule::fetch_config(&storage),
+            };
 
-        if let (Some(gas_params), Some(storage_gas_schedule)) =
-            (&mut gas_params, &storage_gas_schedule)
-        {
-            match gas_feature_version {
-                2..=6 => {
-                    gas_params.natives.table.common.load_base_legacy =
-                        storage_gas_schedule.per_item_read.into();
-                    gas_params.natives.table.common.load_base_new = 0.into();
-                    gas_params.natives.table.common.load_per_byte =
-                        storage_gas_schedule.per_byte_read.into();
-                    gas_params.natives.table.common.load_failure = 0.into();
-                },
-                7.. => {
-                    gas_params.natives.table.common.load_base_legacy = 0.into();
-                    gas_params.natives.table.common.load_base_new =
-                        storage_gas_schedule.per_item_read.into();
-                    gas_params.natives.table.common.load_per_byte =
-                        storage_gas_schedule.per_byte_read.into();
-                    gas_params.natives.table.common.load_failure = 0.into();
-                },
-                _ => (),
-            }
-        }
+            let storage_gas_params = StorageGasParameters::new(
+                gas_feature_version,
+                gas_params,
+                storage_gas_schedule.as_ref(),
+            );
 
-        let storage_gas_params = StorageGasParameters::new(
-            gas_feature_version,
-            gas_params.as_ref(),
-            storage_gas_schedule.as_ref(),
-        );
+            if let StoragePricing::V2(pricing) = &storage_gas_params.pricing {
+                // Overwrite table io gas parameters with global io pricing.
+                let g = &mut gas_params.natives.table.common;
+                match gas_feature_version {
+                    0..=1 => (),
+                    2..=6 => {
+                        g.load_base_legacy = pricing.per_item_read * NumArgs::new(1);
+                        g.load_base_new = 0.into();
+                        g.load_per_byte = pricing.per_byte_read;
+                        g.load_failure = 0.into();
+                    },
+                    7.. => {
+                        g.load_base_legacy = 0.into();
+                        g.load_base_new = pricing.per_item_read * NumArgs::new(1);
+                        g.load_per_byte = pricing.per_byte_read;
+                        g.load_failure = 0.into();
+                    },
+                }
+            }
+            Some(storage_gas_params)
+        } else {
+            None
+        };
 
         // TODO(Gas): Right now, we have to use some dummy values for gas parameters if they are not found on-chain.
         //            This only happens in a edge case that is probably related to write set transactions or genesis,
@@ -143,7 +145,7 @@ impl AptosVMImpl {
             timed_features = timed_features.with_override_profile(profile)
         }
 
-        let inner = MoveVmExt::new(
+        let move_vm = MoveVmExt::new(
             native_gas_params,
             abs_val_size_gas_params,
             gas_feature_version,
@@ -153,18 +155,18 @@ impl AptosVMImpl {
         )
         .expect("should be able to create Move VM; check if there are duplicated natives");
 
-        let mut vm = Self {
-            move_vm: inner,
+        let version = Version::fetch_config(&storage);
+        let transaction_validation = Self::get_transaction_validation(&storage);
+
+        Self {
+            move_vm,
             gas_feature_version,
             gas_params,
             storage_gas_params,
-            version: None,
-            transaction_validation: None,
+            version,
+            transaction_validation,
             features,
-        };
-        vm.version = Version::fetch_config(&storage);
-        vm.transaction_validation = Self::get_transaction_validation(&storage);
-        vm
+        }
     }
 
     pub(crate) fn mark_loader_cache_as_invalid(&self) {

From dd7eb0f31898ec263c938694af01c1c094cec819 Mon Sep 17 00:00:00 2001
From: Stelian Ionescu 
Date: Thu, 8 Jun 2023 18:00:54 -0400
Subject: [PATCH 118/200] [Helm] Add charts for kube-state-metrics and
 prometheus-node-exporter (#8576)

---
 terraform/helm/kube-state-metrics/Chart.lock    |   6 ++++++
 terraform/helm/kube-state-metrics/Chart.yaml    |   8 ++++++++
 .../charts/kube-state-metrics-5.7.0.tgz         | Bin 0 -> 12213 bytes
 terraform/helm/kube-state-metrics/values.yaml   |   5 +++++
 .../helm/prometheus-node-exporter/Chart.lock    |   6 ++++++
 .../helm/prometheus-node-exporter/Chart.yaml    |   8 ++++++++
 .../charts/prometheus-node-exporter-4.17.5.tgz  | Bin 0 -> 12078 bytes
 .../helm/prometheus-node-exporter/values.yaml   |   5 +++++
 8 files changed, 38 insertions(+)
 create mode 100644 terraform/helm/kube-state-metrics/Chart.lock
 create mode 100644 terraform/helm/kube-state-metrics/Chart.yaml
 create mode 100644 terraform/helm/kube-state-metrics/charts/kube-state-metrics-5.7.0.tgz
 create mode 100644 terraform/helm/kube-state-metrics/values.yaml
 create mode 100644 terraform/helm/prometheus-node-exporter/Chart.lock
 create mode 100644 terraform/helm/prometheus-node-exporter/Chart.yaml
 create mode 100644 terraform/helm/prometheus-node-exporter/charts/prometheus-node-exporter-4.17.5.tgz
 create mode 100644 terraform/helm/prometheus-node-exporter/values.yaml

diff --git a/terraform/helm/kube-state-metrics/Chart.lock b/terraform/helm/kube-state-metrics/Chart.lock
new file mode 100644
index 0000000000000..943e8cd6b914f
--- /dev/null
+++ b/terraform/helm/kube-state-metrics/Chart.lock
@@ -0,0 +1,6 @@
+dependencies:
+- name: kube-state-metrics
+  repository: https://prometheus-community.github.io/helm-charts
+  version: 5.7.0
+digest: sha256:6c8144333bebb7a2956d27f0438b11920b0a914c18fe8c7381adee0a6041044f
+generated: "2023-06-07T17:17:42.178703-04:00"
diff --git a/terraform/helm/kube-state-metrics/Chart.yaml b/terraform/helm/kube-state-metrics/Chart.yaml
new file mode 100644
index 0000000000000..fc6ded4fff28c
--- /dev/null
+++ b/terraform/helm/kube-state-metrics/Chart.yaml
@@ -0,0 +1,8 @@
+apiVersion: v2
+name: aptos-kube-state-metrics
+version: 5.7.0
+
+dependencies:
+  - name: kube-state-metrics
+    version: 5.7.0
+    repository: "https://prometheus-community.github.io/helm-charts"
diff --git a/terraform/helm/kube-state-metrics/charts/kube-state-metrics-5.7.0.tgz b/terraform/helm/kube-state-metrics/charts/kube-state-metrics-5.7.0.tgz
new file mode 100644
index 0000000000000000000000000000000000000000..4891bf5b08348bd88dc5cd6340d145296fd40882
GIT binary patch
literal 12213
zcmV;mFG|oKiwG0|00000|0w_~VMtOiV@ORlOnEsqVl!4SWK%V1T2nbTPgYhoO;>Dc
zVQyr3R8em|NM&qo0PMZ}bK5r3IDS9#ufQYap4d5)lI%E1HBWBNb<#F-N$RoP-rQs|
z4Mai`YLZ|8P_~-p`?r5*@j`+xdbQ)U{fM1uED~5OfW_`&vAej+N5mHrOX4R)avF->
z=@fGr%yAO`?QWiazu$lI__6x8-|yG|?LR#}{@dX3MJ6=x?Zh
zN9`|tav?GQTmRN=)jRhmd2mL5CR|XK4$
zBoVz9%Jigb3n2bVC|K04NCs@uyqEOs?bmTlELxi&|rXhw2^JaD~kAtT{-)ouw7C18;
z=S18g16aQPkB*KWKd!C+dfL&L@fN}iymDb(gd78*NuCpr
zCU`=I9zvW{AgS~;x@UPDUyzU!DTe6Xd#{Up
zvpPHKyASn!p-OZ-ZxXW+j)w}TONOQ-&QQpb3`;tqF_m+4P306ZIVBv03Pp51rQuW|
zu4@PNh64reB#zlNB2-nyDZ-rNIbvhv-rE5w5g07|a;UyAz7hB~z*Uf~Q-x618Mq8{l1e+~
zk|8!DoYRODG>E25NI=*EJTJ(!)A2k-WI$q)DRMqQa!Lidrg4lSlErM^ChD+27+t`t
zaUNd~spOrU5)@&Hy{@i4A_(V_C0NoB$MGD%IOI$S^nbz6n$L2g__g>a%2*^&
zE@(PY&_+3prB73@s~|;GgwVe^8WSvYzJ&no8jMKfD{MeycF`qtnF^pKa+48G6Ou|C
z+h%O<;4e;4%8-!Q5dI{`9H){H5qJRGLWOxIDIUcn8lo|d1@S!F&mkJXz`v$K0@dOu
zq9ChqjKY{A%qKatuck9(>6lIchZYvmRji8K;3SL55c$4t(4YK9GoPd(14Isx@5gN7
zk7-N}5RqX3qZ!9)fHNip9mUYEi9jJvVbaDdPa_1~-9kYb#cb3|Flaozh=rmT#?&vm
z6eN*HZY0Mie4@$O6NJxbs2FI*xE!Kq{bzke;g&7KFlZg>)tTz?2!~hKm`7C}1e{Qb
z|5IBSR1OxAGX)l4#tcW_;uxnPd^W7Ii+)VwISdKAMmP+KP$Lh+Q!S6ioF(vH5cKLy
z)Zkqxz2zLI6Ji%?fwgG~rzw+4EfGWX>9gl`yXd5x{1}f&tlGv=r2dIx#EDUeyf7D%
zC9hQ>RUJ^rS=OpW0q7qsD-a|mp=8{&;Mw1{K!J?I2MRQ%z)E6*1<}=!U`T-cgGI{5
zs(_h8qlRi>ppYs>Cg2xdp=-vk1Y)_gRY&Z`Gw@Z{ip2tK>n)K`pb2s={ycYmZzE%LX{CsBgMxUqVk|@4#pVPmX<}iATLeB=L{C{oaNlNxcE@Z
zvmG|Gqs9XH=sZu=NW);B#;IZzr(-3#M2176*j)^B
zNhI2%<2okrT{Q@-Q6Wx&GXwV)c7>^Oj3f20WC*&9B-{58lynNY6L1nmC?h!snM>W5z8lW_S*}F3k5Im{Y~3H+V|k(eg-10@<^{eR4fkU~j6Aa??MfwO!v)yrSgwOR&h
zc~mM$z#5vq2t2?O7U>ya*&-s1iUMC;efndL=UR`hYSJT))9|-mt@o;!Qi^B&VDLET
zs~4qiyi7ZW3EM(0o5oe!4XG?+;fFMv67GwfN+McBvf|~p5X$W%(ai;(5KCsI%tff%
zMHd+f>3EI=33Cprj381f^%?NTK!}=#baAC`ibB8CWaA7GQw9>DWils9fbE^JXuoIx
z0FoQ2!JU(F*^yGE2q@EPgT&%W^on8jGZy&;Rrf4N^@`lcURMz5%PH~eU;HuSJ}#?*
zP_TbrR1wo+u(F_)l!dwZ53rhCX|bHZ#)6~~N||EF!VF|&^p&E%UReyq1kZ@(q)KrP
zSt>%xa$$gnQwA#sh8^ZV7la2|CsiDprm)ln5uoO$q5c=teV(U?0Y{io&QeXAiuuJ<
z%9t4F1v&>v43|-^2(i^8*p6VV;h2EF}C4l0r;m0(ELOA+0
z7pg=8O{4@ADa_{wS|XB!sWBiZ%y~SArK?70ED1*s%OQUl6krpow@ZqNhFLyDgML4;
zFA|a{9`NMx8(Q>Kvz>aSMxCR>H`J_x8H@9TyaCZI3^x)efuA6}wa#SXIM^$s7GYjld&ZbYdWhfZ{ID!
z364OKwX)Xm;}flxXt}1BJSDI@Cwj+?E-K}aC`7B4FVTS-R?3O$x&~fTtdv<`O0=3_
z^tu{Ytz-pOm4THb%(l^Ja8wwL4j1Z%wWdbSmT;WMu~yqilEqjSc0~pHoQw%4X{gi@
z5R8l?Wed=z48^*w)^H7S2_yl4R$@mRUHGjylQNtb8w#g0(8;YF>n+*R*T>7*D(FG`
zNe~obL5Aq$KNslbzc0|MlQ&AM)co3tU!#V$bOn$P@U;kVf`4PF5*y@7^k5K$>;c!A
z22!>G+fm!J!LiabE?WemZ?>vCyiTjK1n;(bwzPA0
zE7}I#s0X??f!;jNa7>jRepZkHGM0CN4uiv|L0_%)lw1>DK~J@`7Ira7Cvxgwr`f(lD7vL-2Ael&+t1<91N`eOz%
zPT7ttz0$oXMjqI?RsuABzA@?QFIQwfMDYLewTy+{N*2}~tMJn?!sv`e$m+jH?}Zi|
ze4qsMx>6zV*3jNVmI7^yUZx=TKt>jtxq0VxyI#g3i-g&awe1Ppq=nO;j74q{`}r<#
z?BXoLJTbF#S3m^`VV88bFy|tavC9a$$g~sK!U2x6DGsVlD7z<#&NzeZD6ly(L=PW5
z+ysW%`8Y6!=wZadE5hwJ3(pQ{32;Q@TJSjN
znNmxru!|~Xf^m#zj3eJi-|4@M=38se)qGFYUS6xJkDRl4g_NmB(}_7Y?9B$fw{DZB
zUPxn_Cu-$GJ^fRaKkS{VAN5)q)uHPRptmgLD5;&923+fa8Z4YqW%%KRY*5JP8g{=0
zB~LPXp$cA@a>Ig2`AD*tsicw;QNBgUuQj2qFl54s5Y`@N%-u9?d#kue*&4u1uneb0
zP?=Wh#LL6i5tz*}2h%I@g)9}4L-kvu1Z*s3I0DhB|L057ny*{)oz?(7{qaJ5J1sw1hxP3m;;(UVGhRykzVuMZxx`7MW7ph0#p#TkzQ>GR|jD>h>PO{ViI#p*y
zUKeHcBKFLGy=Bbv)OUQT++`h&dVt^yDtNB=$G3SjG3u&1#7GkC3zA`Nzln`W-Eoy0
z5qmBX*b{hF3fK^*f(R&2Zg40~Ev<3`_v$f@IGK#8xVgV3uQV?7q+gEfT(V4_=sJt2*Ft{ePFrhd$Q5BJ*?OIb(W7%t<@Dwg&hF?b*{n
z^zeCsuz3FN>Y4Br9Di_7{+%8KLGbR`xjaqtwRi3&!yTFfImAnOs*4kM0bX5{FYgXI>Y*1nQybL=mB`
zq&Z!Ng|-d)zVpfY5m;TX+~bsm78oE#Sdb@=k#g-LktTWr6?Tn!8_9_r7HAR8C0#GB
zl2Iz_fu?Nb=w#PKh4aF?DXBs&7gI;;J+Hhfb(C1CuXe$+r=5QH5#wl%lel2y4gwWr?Jl}qez6+$BAMvGXsV6sDAZ}BGHiZD`LpA9
z;B`yEXS)ZSTJf85+b!#t#{^Kl?mqDaohQDe
z>%^CJocJPc6Ry)l&1ItLFi~}vs5(nDTqX38h0&C*o)u?NN=T|ROUGr;Y}%`aed{x*
zy!iqE_?_z|1%s*&LQPylNmGMh@HqGe2yRIsy$B7<6C^G-YZWeDJt|Kld+d(h=u;c7
zH5jCHj;jJQN|v##MI_bi5a>d=PTFd3jT7>L`lOCi3fD`6Od#i((i3f24?6LtJVtMk
z1_k^d7%bg>p#H0VI+a5GSALL6(GOQCKck!Km>a*^%aRy$+SNl|G5
z(ywc3w&7kt;fq>_VK%})u+yWR@UmP@qNY{j*`-v3=-hG2)DCY@6X;a!B=8L~=N=9s
zmWgC6@(`3c(M1YArdG(IT~Ky~4ElYupxhQ{y1E6LZqkDG7tSIqNqI`q?$uLpSrVBV
zT7oHKj&*&}XMj|Ia>PMo!B8%NU=MH{I8n~6UrtQN%J)Y>4bYkOVKmDKYIS}bk2?pb
z^D3p1;u!usC;CvaquE^t$fsjHz;wHB7_4vj0EAj`*8-qwD`|YyE8bfA@KdB31YFnWuo`?$IF)&fxMBoYhy+H_u=5^uonOM
zP#=+?YC&3UL5ZnY?P-hnAjjZ!a`pA>
zK&`-gm8xhK<+gZ$K7A@&Hc_X=Tw@(OJ19V(KL@Ld7n=`LUd+P4#9IY13voRB^a?HbJqokN~N(f^&T51Ev_k!iXzG_CVGofxGiB9NElPtXxP~aJnz#d
zAJK6!2$k52z^G=QKYLz1c%+zM=(aw-R7=8YbDm$s(G=Dy6Bv1|13f$+y-bC6D=^BP
zK@aD0N>XXOqNN*LvPXhRfMyieeOdQ)w<}vH9hK$85e>Z$A3k_oMbao!jT^y(Ivr&F
z(VSo%Ya;4xMw=ZCN=Nk=KL#I7h*T)RsKfsD^XHw^{Zl+k<^L~J5@&>qKxVf|1+iTI
z4-StW4{GxN>CvFSlmGYeeEQUTgl04us{Qzw#sv1_&taR6!zme}N4?LVJt*b9yvb~!
zyBq7EY)XM=%K6qJvPf)okY5&5wg#QnAy9|-mR&>1!VLF2k~~jC^yEnWNt26wJf=6O
zA>F_)l(f+fr~bPht1K)9LKO%j9?F^IuUsPAsV_WFQEPvH&fkUqchRXq)9r3Ta*O`1kYat+)TF#|lw50mtFcXQ7tM6FSYQH;pdg6sPoIkE
z*|Vp_D}?|4BG9T|^?|N6(lLK@)&jC{G?%8L1S-7g)MX&!hc5C#zI@p9xbpFvnonJazaQN?SuCWmoG_<)L)SVmFahd9$nzSxz2}9Q7$<^U(W5?B~qW12#moglobr!V2^V6rLv+WQ@
z69P?z#A&$sNTCZNMZw|SAh1eQri}?|jAQkCpaH0eEm1Cewfha6=s{?{5=;nKw_vI(
zIst(2p%M?cv|<^W2k+fLz17uf;c^9lMi|{{Q1w{00#-A~Z2_<<-~5j81cU6W=OaU}
z(kxdNm%WIF5_L317V_HUMsuokQ1D3~`_ixh@ALjz>!u0Q&bxBlL3<$s)x20A3$m%9
z#+!ZQie~Z=?ZLk0$1$ieodjp^wBy8k6%IQFS@h|%TDCrNR;7_fs4AINsbbv)s3M71
zO~B=p=)tn7cNQEgu049K%AfiYh$(L2MD7^cbZDp{#Cv}i!@rAv{k^1s_KMXO%lss0
zuh1_o(3ztbl#*h<214RV{gu-XI{_<^wfKA`G@a>pFy3+&zRDD=G2r(++6$#oLxe9}
zWQ7U1eSMV{;>Am=rQE$Pw6^wdHNtHGE7ZNB$7?UicFh0q-TN9#`Tj;>qhbgPCw@C}V^8CO5v}*r996Wt;ytDt`$75I-PNUK?RSERAe#3j@
zaJqG>clZGqYekvPH<51SS>H)cgC+ipyuwKUdt(r%sK
zQA*Q@q!K-DDC;I?NC9WL*(5H^CBLI8$YMXR!C9(TN$<1ap}z-vFYRZjkD;qE=d~E{
zbvoCy2^F1uqOmQ*(u+A-OgSc?e%Z&MHE14v{#;;OpVkeal(YT>Ikr?Q>GZ*MGbq0i
zkY7}^1mncv1AsHeZPqnkIe$2ybW-0%&KQo344FqcTZAkgqRZ1Wcit+NBL
zYm;U9ifb(Ty)fQ9>pvT;k4`COcT)CG{w$aO+NH=z=)2Xe5G&;W0Azkm{vRLj&j0V_
zY2o60ghP8=Sb0}XYpnLhuAEn8a4uEYo|3#}Di_emR0m;^f0A5|+eK{9}W8(Li1WL~!Sc>!r4d-nTw
zyV=!&JEt+G$))8+CTT)tCuX4zZ6eNstcqly#rSMB)z93$Xr=4b1Vv@B6|-Kewy2?^
zhX`2$&>2XbYeAeza^9D4nqvA^qP=w|TFFM%+>O@r$SD9Up>h!j)G;uWPmmtEav#5V
zkm{4u$PQIhY{?4c4CKO!wf3Am`jrLvU@B#%_SVDaND`i6K1bj5zv-jB1r`8j2i{*~
z@-D*_oR+Fv`D$|mx4HFp|LeBxugS5~I_+%0JoH1-S-Ey?vu8iP_~q@%o0r80q=PKK
z<186EFOl}qH7b4My^d_O3?p#T$u^t1I6FE00`2Kc0`AyU=nJU}FsjVU9lhdG3sfKC
zW{KrX$-suz-IqS{eW20jpFTNcU9aUjbCpSH>Trs{ljqJ_bISjYeq}U8orBIwv}#1u
zn$@Y^ye_1(I0?T^?!nkfY}h_N-*uuYW7Cc1kJvwZ8!(WhSOYXp|+M_gE%-
zSI9l?!TTbo+$obR`o=Z$$mVm!Y9`j5mA9Xkc2zSpGX8<0KS
z7|Hv>uA!vZd_hhFW#D?t(kp8e>u%6*aR{qyRoe5ZyKOdd;I{;)ECRC_5x3W?#UN^I
zyX%*r!E~&-W2`l?a{suf{MNfkHKN4VnKFDFMVtund||4Jg=_*~<(ZJ2;N&?Bz_8aV
zRDxlRNPATsNex<&xIxRwXV0EJtCTY7gT^!_&sFxL`l#yyJ*S*HAXy>p7SCcsoS{Yn
zrj=Db6@eqI^H&#P)rwBQLs}u-YOxJuRh!f1Mv|-HiybVHJ$EC07Ra9#;1!aoRrC#e
z?`+F}?G;fvn~3`*Yj0e0?50$?JFZ-vkj;7YqWWud>?(je;@@imUB%7ojJ8cdSb-DF8{5Lxe|Ci?Qn^PKEqWrhB{BM@jy$`Pc&5rB;vAF)C7p2*x
zvURUStgeV?ExT5@T%<#vYc(z~WUK;eUw*4_fWiHMB{Q2RZ&WnBN`oDGLuYOj=|32y0
z`xGRv~3(
zs*XSkM
zE?V08OGKBg9rd*&A?W(4Vq1cg8dOl=cZhbux__N#Isa#oJx{sK9&pwEuRmzye|r3Q
z7yo-NPs{$VaeHOC2V9r`D{c)!pbDs&8>+_N3#MMJcNZ-EF1T`2Sk?w=(-`385SoqG
zVuCYHXEY`g_mauV8HtY`YTMMqHE=KPi2r$+9eWi~iFUl7@
zPfx^8f*3)_b9LSNn_S3q`0|#e=ZwjRN@BjIX?{~Fr^=k9bM-yXGT7Io636C>q*jm*
z^;>m)xD~eQ+SU<`)P4Hq>POC)L=ylM6b?QKO^2uqPDt?05Is3QK05Xg8Vj9Vg0*rC$sw6>*lZWY{LJy%>lU5{&!qI|2sU|o&Vp@^QYqfUpi;t
zHe%rRc>{0JdYRHs<*jW`>URfe{q7{O-;Qhl0iUJ(-*Evm_GXBF|A*p570znSBv!jTk&@FY;YkIJtbn=7|>+;#Zv8uPz={oi8K?>x)b|KMm8@7J$xv;Hc3>*hwxf-dD^FO0`|wP-$&=*8%G39H7oMmf^JX
z-ri48IxuLYtwOUllC2mOP`1E;v-DRsTD$#`f!0LA0NNad2$O`Rf~-GNrAY{&<17dt4?!ax>7Hw>f-kmJC?G~F#ySF||WQ<2Nbp=-&DjMh($k2pJeZ+Vhigv(k
zjzf}540^*g8BH0x(!4Y`v5;#Mc9c*7w
z`e>}R)M~J|K#oPX92o$xdAk|tfkKj0YF~&j#x%JVBJB`wkJ+6fwGBQjiV8o!k@E9f
z8zpV)ZC__?aJRzlb_2wsEn2nt?(bYPasY3Q6^v)dQpo|G^;Li+=+q!?gP8{VF=rCr
z5+fJV=9mbZyI^}142W&o*4CffHC|YdHf`P9!LbR^E+SJG);5?hjwiq%H&Fylt);TN
z3VCzPW;mwN*HAiEG`vMm6uZY#;&8grW@(*aZUEl`KiI2>cd%Vqj%aHuYh$Z(X+2n-
zezA$(l%&#d&ZQVic12Q7W|Ul4@X}_r&igjdb&J)4wV;pva2OIHmbFkxNmJ>tG6bn4
zVCQ*U_w`&+s&>h;zl#U>^FAx>|F^mL(LAgCKOWcPzYhC@o&W#+JT?3OvIBtn@j$CV
zzJ3T$*!~|hjsN@gn-MlL?a<0x9DZwt*tN!GvxKw@yRiwFB^gGF%5T>j`IR+mNk0}OaJADAGaP-3W1NPB
zzdAFkyYjA`P#g6+OR~kbRk~0+=W}&V)oj-NYSYu0YrR4maWs6sA#fAapljF1X))%D
zuYNM__b@(hS?c(pwDh|u+o;+$v~KB6HO50UbGB@kAm#DS>Gu!*tfT*7t%rXp|KGvj
zupa-{fAXZi)Bo<{X=kBk=Vc85OHx2q_IF<@F5?!F3%870SUfbFhWan5zA#+AE%o<(
zB>k@8x+DkqE*Z?9{8@+pCq@(eLj3>fljDZ{_vz6t{`+2@g?r&3Y3_$y8DKtx!WuG8
zmY5E&bHT4{q)=AlYd4pj
z_5@>{Ww=>D>-R?Qe%%3c-?a8ea+=)1IA$!mY&2ebd7JhNLaXsoZBBYk6Y2`yCW19l
zyD}r(I(@bv+}r|XF3c91sph$?+yZ*%*)t1I>1z7b;-16R42!0c@EMLvB<-7ujbn|P
z%guOgBdcchQs1vrwqJR@3W-)28)Kp_i1>*+gJ9pRYTuUIw&f{H?R1xoJ1?EfcQ=Nu
zsp_047ERNM(?a7@^`4x17OQn&w_J#}F~+3*fZivx-?ekS^>s15KPRYB$&{
zVC3xsvwmV~%Z&|p-!bGJL*6mu9YfwRAfvj1Oh|B)i1B4jhd=l=G|09M)m
z`;GihgQMe}|KGhlE%~2X4DYr5;T7=tQ=_UE$Y5(bt|KG>+
z75IOfyY^p04BW!U`!0rHmkn_DZ2Bza|E)20o9_Wu@c%>jR^$JN$GiN0_wu;$KP$4k
zHX}28vq8tb(A$v98H-Lza&fQmcBMrtI3p&0ZiDofI7GIGtyU@5iE%Z|kfjpSl<+f?
zbHg5i6(82Sj=Ygbux4gypQj=VKy+?53?+n?j}?o{79c;Zx=p+lWP)$hRgT1|SiW=Z
zEsYDvSHWws%504#O`BL2@3z3QgtrryX@Tw84hHoa^&U$<+GdY(mCniZw1xo=uyKUM=WKi;tNoVuVeS%+n(O
zgDHsvmc-z(|C?ps%ipCC?g!jG$nx-ytw$~LNZRgE;?mN!cz3}=>>`?7hW)-
zvZwy9(f5MUZ@j1eZ(mF&J@}vfDQ0P}1T@0oRi2?SjfwCc1>!pM9t9(OFK(1_rkF2~ugf5r_>%lbcmdGg}T%OHvFs*M%v|M>86
zef>W^Jl^?#-pkWPO$tCikT^l7Q_Q93y-J0|aV*rmWA9oD;|WRS`@N}@nHctZ6Dp_q
zNI8R+ZiBsMz5T%Rx?S`=k?5RcOi;=A9KA}%%=^Fp@qHx8jf`n3{fG)sMv(9S)BEt@
zL&#FWV&Z|2LY!m_;V5!qHT{q!NuE+UM;4{FkAcCHvK~P4L+Gt=plVSKEqdNB7lfd9
z#kaDv@G20~Uc^G7eyIQb0)=|}Xv{c*24Qm*u`pMc&M6DfFSR~ueM@x_2E~lIoq~F=
zsrmfw{N?MHCl@b&d3*Ba<@?q#Xc>6)ZXDx@c<*+tl9K5CUbpglAB{-Nu7h7H17VO@
zIToheis67>|CG|@{m#?&p6i|{(Zor@W<;pV?SWwbU63F&ow1apQXnh@3n`XX_&`ZT
z0BRo`kyuqw7wr+1W;3XCy})B-=Zli-bU&MLtOV|&?yCai4yWA(ySgvB-0Gfm(HlD9
zD&rLzbCw_>fx6pp0tidFgy;R26pFW>rROD
z%eOwf-B-nn&USM<+YKe;D+8r$3y${r=_aAHNThNY7e=
ze}%c5>WEdAszz~EWCHXBjeyuMr^F6;Wcr)3YgKy8U?U10HDHFG_Xxe4k+S&ONUEm2%|09;3H(~q
z)-{b|lcZbe|4>Q0$CaipwHYW-*|Y2Ce^C*iz8`p(thgM6Ae|oV068h!h+gG3cRbpg
zQH(J9P(3C2pvafp;3SL5zMdM4J~+vaJ|LYTPf>h0McB;L94GNz-EXK(CCv%(Il+;2
zInb^GWfD2m>7e%>Le+cviu9B%#L>~k3pW65ahwpTsYWfE+BDmt5v@#W#Bmz_)~nU&
zNlr*F!O+#7t>3dq`nb5Y#V{&Zka{_Y;Lo_P+C95x_w1fO`t$z>00960VGmCU04f0h
DrCR-0

literal 0
HcmV?d00001

diff --git a/terraform/helm/kube-state-metrics/values.yaml b/terraform/helm/kube-state-metrics/values.yaml
new file mode 100644
index 0000000000000..e5a42c59e6715
--- /dev/null
+++ b/terraform/helm/kube-state-metrics/values.yaml
@@ -0,0 +1,5 @@
+kube-state-metrics:
+  namespaceOverride: monitoring
+  podAnnotations:
+    prometheus.io/scrape: "true"
+    prometheus.io/port: "8080"
diff --git a/terraform/helm/prometheus-node-exporter/Chart.lock b/terraform/helm/prometheus-node-exporter/Chart.lock
new file mode 100644
index 0000000000000..a2787d23f6fac
--- /dev/null
+++ b/terraform/helm/prometheus-node-exporter/Chart.lock
@@ -0,0 +1,6 @@
+dependencies:
+- name: prometheus-node-exporter
+  repository: https://prometheus-community.github.io/helm-charts
+  version: 4.17.5
+digest: sha256:fa78ac7db5c879ed613904daf0f4049b10b5268a1d44f846facf59297b0a1f75
+generated: "2023-06-07T17:17:49.635213-04:00"
diff --git a/terraform/helm/prometheus-node-exporter/Chart.yaml b/terraform/helm/prometheus-node-exporter/Chart.yaml
new file mode 100644
index 0000000000000..52351e84cb28d
--- /dev/null
+++ b/terraform/helm/prometheus-node-exporter/Chart.yaml
@@ -0,0 +1,8 @@
+apiVersion: v2
+name: aptos-prometheus-node-exporter
+version: 4.17.5
+
+dependencies:
+  - name: prometheus-node-exporter
+    version: 4.17.5
+    repository: "https://prometheus-community.github.io/helm-charts"
diff --git a/terraform/helm/prometheus-node-exporter/charts/prometheus-node-exporter-4.17.5.tgz b/terraform/helm/prometheus-node-exporter/charts/prometheus-node-exporter-4.17.5.tgz
new file mode 100644
index 0000000000000000000000000000000000000000..9db215da1342b29bd709caf9d56c5c20b52378ce
GIT binary patch
literal 12078
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
Date: Thu, 8 Jun 2023 17:14:01 -0500
Subject: [PATCH 119/200] Add a zip functions to iterate over 2 vectors
 concurrently (#8584)

---
 .../framework/move-stdlib/doc/vector.md       | 232 +++++++++++++++++-
 .../framework/move-stdlib/sources/vector.move |  99 +++++++-
 .../move-stdlib/tests/vector_tests.move       |  96 ++++++++
 3 files changed, 425 insertions(+), 2 deletions(-)

diff --git a/aptos-move/framework/move-stdlib/doc/vector.md b/aptos-move/framework/move-stdlib/doc/vector.md
index 52f1002a82ca8..7b4578232be25 100644
--- a/aptos-move/framework/move-stdlib/doc/vector.md
+++ b/aptos-move/framework/move-stdlib/doc/vector.md
@@ -41,13 +41,19 @@ the return on investment didn't seem worth it for these simple functions.
 -  [Function `for_each`](#0x1_vector_for_each)
 -  [Function `for_each_reverse`](#0x1_vector_for_each_reverse)
 -  [Function `for_each_ref`](#0x1_vector_for_each_ref)
+-  [Function `zip`](#0x1_vector_zip)
+-  [Function `zip_reverse`](#0x1_vector_zip_reverse)
+-  [Function `zip_ref`](#0x1_vector_zip_ref)
 -  [Function `enumerate_ref`](#0x1_vector_enumerate_ref)
 -  [Function `for_each_mut`](#0x1_vector_for_each_mut)
+-  [Function `zip_mut`](#0x1_vector_zip_mut)
 -  [Function `enumerate_mut`](#0x1_vector_enumerate_mut)
 -  [Function `fold`](#0x1_vector_fold)
 -  [Function `foldr`](#0x1_vector_foldr)
 -  [Function `map_ref`](#0x1_vector_map_ref)
+-  [Function `zip_map_ref`](#0x1_vector_zip_map_ref)
 -  [Function `map`](#0x1_vector_map)
+-  [Function `zip_map`](#0x1_vector_zip_map)
 -  [Function `filter`](#0x1_vector_filter)
 -  [Function `partition`](#0x1_vector_partition)
 -  [Function `rotate`](#0x1_vector_rotate)
@@ -105,6 +111,16 @@ The index into the vector is out of bounds
 
 
 
+
+
+The length of the vectors are not equal.
+
+
+
const EVECTORS_LENGTH_MISMATCH: u64 = 131074;
+

+
+
+
 
 
 ## Function `empty`
@@ -798,6 +814,111 @@ Apply the function to a reference of each element in the vector.
 
 
 
+
+
+
+
+## Function `zip`
+
+Apply the function to each pair of elements in the two given vectors, consuming them.
+
+
+
public fun zip<Element1, Element2>(v1: vector<Element1>, v2: vector<Element2>, f: |(Element1, Element2)|())
+

+
+
+
+

+Implementation
+
+
+
public inline fun zip<Element1, Element2>(v1: vector<Element1>, v2: vector<Element2>, f: |Element1, Element2|) {
+    // We need to reverse the vectors to consume it efficiently
+    reverse(&mut v1);
+    reverse(&mut v2);
+    zip_reverse(v1, v2, |e1, e2| f(e1, e2));
+}
+

+
+
+
+

+
+
+
+## Function `zip_reverse`
+
+Apply the function to each pair of elements in the two given vectors in the reverse order, consuming them.
+This errors out if the vectors are not of the same length.
+
+
+
public fun zip_reverse<Element1, Element2>(v1: vector<Element1>, v2: vector<Element2>, f: |(Element1, Element2)|())
+

+
+
+
+

+Implementation
+
+
+
public inline fun zip_reverse<Element1, Element2>(
+    v1: vector<Element1>,
+    v2: vector<Element2>,
+    f: |Element1, Element2|,
+) {
+    let len = length(&v1);
+    // We can't use the constant EVECTORS_LENGTH_MISMATCH here as all calling code would then need to define it
+    // due to how inline functions work.
+    assert!(len == length(&v2), 0x20002);
+    while (len > 0) {
+        f(pop_back(&mut v1), pop_back(&mut v2));
+        len = len - 1;
+    };
+    destroy_empty(v1);
+    destroy_empty(v2);
+}
+

+
+
+
+

+
+
+
+## Function `zip_ref`
+
+Apply the function to the references of each pair of elements in the two given vectors.
+This errors out if the vectors are not of the same length.
+
+
+
public fun zip_ref<Element1, Element2>(v1: &vector<Element1>, v2: &vector<Element2>, f: |(&Element1, &Element2)|())
+

+
+
+
+

+Implementation
+
+
+
public inline fun zip_ref<Element1, Element2>(
+    v1: &vector<Element1>,
+    v2: &vector<Element2>,
+    f: |&Element1, &Element2|,
+) {
+    let len = length(v1);
+    // We can't use the constant EVECTORS_LENGTH_MISMATCH here as all calling code would then need to define it
+    // due to how inline functions work.
+    assert!(len == length(v2), 0x20002);
+    let i = 0;
+    while (i < len) {
+        f(borrow(v1, i), borrow(v2, i));
+        i = i + 1
+    }
+}
+

+
+
+
 

 
 
@@ -858,6 +979,44 @@ Apply the function to a mutable reference to each element in the vector.
 
 
 
+
+
+
+
+## Function `zip_mut`
+
+Apply the function to mutable references to each pair of elements in the two given vectors.
+This errors out if the vectors are not of the same length.
+
+
+
public fun zip_mut<Element1, Element2>(v1: &mut vector<Element1>, v2: &mut vector<Element2>, f: |(&mut Element1, &mut Element2)|())
+

+
+
+
+

+Implementation
+
+
+
public inline fun zip_mut<Element1, Element2>(
+    v1: &mut vector<Element1>,
+    v2: &mut vector<Element2>,
+    f: |&mut Element1, &mut Element2|,
+) {
+    let i = 0;
+    let len = length(v1);
+    // We can't use the constant EVECTORS_LENGTH_MISMATCH here as all calling code would then need to define it
+    // due to how inline functions work.
+    assert!(len == length(v2), 0x20002);
+    while (i < len) {
+        f(borrow_mut(v1, i), borrow_mut(v2, i));
+        i = i + 1
+    }
+}
+

+
+
+
 

 
 
@@ -959,7 +1118,7 @@ Fold right like fold above but working right to left. For example, public fun map_ref<Element, NewElement>(v: &vector<Element>, f: |&Element|NewElement): vector<NewElement>
@@ -983,6 +1142,42 @@ original map.
 
 
 
+
+
+
+
+## Function `zip_map_ref`
+
+Map the function over the references of the element pairs of two vectors, producing a new vector from the return
+values without modifying the original vectors.
+
+
+
public fun zip_map_ref<Element1, Element2, NewElement>(v1: &vector<Element1>, v2: &vector<Element2>, f: |(&Element1, &Element2)|NewElement): vector<NewElement>
+

+
+
+
+

+Implementation
+
+
+
public inline fun zip_map_ref<Element1, Element2, NewElement>(
+    v1: &vector<Element1>,
+    v2: &vector<Element2>,
+    f: |&Element1, &Element2|NewElement
+): vector<NewElement> {
+    // We can't use the constant EVECTORS_LENGTH_MISMATCH here as all calling code would then need to define it
+    // due to how inline functions work.
+    assert!(length(v1) == length(v2), 0x20002);
+
+    let result = vector<NewElement>[];
+    zip_ref(v1, v2, |e1, e2| push_back(&mut result, f(e1, e2)));
+    result
+}
+

+
+
+
 

 
 
@@ -1013,6 +1208,41 @@ Map the function over the elements of the vector, producing a new vector.
 
 
 
+
+
+
+
+## Function `zip_map`
+
+Map the function over the element pairs of the two vectors, producing a new vector.
+
+
+
public fun zip_map<Element1, Element2, NewElement>(v1: vector<Element1>, v2: vector<Element2>, f: |(Element1, Element2)|NewElement): vector<NewElement>
+

+
+
+
+

+Implementation
+
+
+
public inline fun zip_map<Element1, Element2, NewElement>(
+    v1: vector<Element1>,
+    v2: vector<Element2>,
+    f: |Element1, Element2|NewElement
+): vector<NewElement> {
+    // We can't use the constant EVECTORS_LENGTH_MISMATCH here as all calling code would then need to define it
+    // due to how inline functions work.
+    assert!(length(&v1) == length(&v2), 0x20002);
+
+    let result = vector<NewElement>[];
+    zip(v1, v2, |e1, e2| push_back(&mut result, f(e1, e2)));
+    result
+}
+

+
+
+
 

 
 
diff --git a/aptos-move/framework/move-stdlib/sources/vector.move b/aptos-move/framework/move-stdlib/sources/vector.move
index 1fdb2a2a29ea2..f7f467286d381 100644
--- a/aptos-move/framework/move-stdlib/sources/vector.move
+++ b/aptos-move/framework/move-stdlib/sources/vector.move
@@ -15,6 +15,9 @@ module std::vector {
     /// The index into the vector is out of bounds
     const EINVALID_RANGE: u64 = 0x20001;
 
+    /// The length of the vectors are not equal.
+    const EVECTORS_LENGTH_MISMATCH: u64 = 0x20002;
+
     #[bytecode_instruction]
     /// Create an empty vector.
     native public fun empty(): vector;
@@ -263,6 +266,51 @@ module std::vector {
         }
     }
 
+    /// Apply the function to each pair of elements in the two given vectors, consuming them.
+    public inline fun zip(v1: vector, v2: vector, f: |Element1, Element2|) {
+        // We need to reverse the vectors to consume it efficiently
+        reverse(&mut v1);
+        reverse(&mut v2);
+        zip_reverse(v1, v2, |e1, e2| f(e1, e2));
+    }
+
+    /// Apply the function to each pair of elements in the two given vectors in the reverse order, consuming them.
+    /// This errors out if the vectors are not of the same length.
+    public inline fun zip_reverse(
+        v1: vector,
+        v2: vector,
+        f: |Element1, Element2|,
+    ) {
+        let len = length(&v1);
+        // We can't use the constant EVECTORS_LENGTH_MISMATCH here as all calling code would then need to define it
+        // due to how inline functions work.
+        assert!(len == length(&v2), 0x20002);
+        while (len > 0) {
+            f(pop_back(&mut v1), pop_back(&mut v2));
+            len = len - 1;
+        };
+        destroy_empty(v1);
+        destroy_empty(v2);
+    }
+
+    /// Apply the function to the references of each pair of elements in the two given vectors.
+    /// This errors out if the vectors are not of the same length.
+    public inline fun zip_ref(
+        v1: &vector,
+        v2: &vector,
+        f: |&Element1, &Element2|,
+    ) {
+        let len = length(v1);
+        // We can't use the constant EVECTORS_LENGTH_MISMATCH here as all calling code would then need to define it
+        // due to how inline functions work.
+        assert!(len == length(v2), 0x20002);
+        let i = 0;
+        while (i < len) {
+            f(borrow(v1, i), borrow(v2, i));
+            i = i + 1
+        }
+    }
+
     /// Apply the function to a reference of each element in the vector with its index.
     public inline fun enumerate_ref(v: &vector, f: |u64, &Element|) {
         let i = 0;
@@ -283,6 +331,24 @@ module std::vector {
         }
     }
 
+    /// Apply the function to mutable references to each pair of elements in the two given vectors.
+    /// This errors out if the vectors are not of the same length.
+    public inline fun zip_mut(
+        v1: &mut vector,
+        v2: &mut vector,
+        f: |&mut Element1, &mut Element2|,
+    ) {
+        let i = 0;
+        let len = length(v1);
+        // We can't use the constant EVECTORS_LENGTH_MISMATCH here as all calling code would then need to define it
+        // due to how inline functions work.
+        assert!(len == length(v2), 0x20002);
+        while (i < len) {
+            f(borrow_mut(v1, i), borrow_mut(v2, i));
+            i = i + 1
+        }
+    }
+
     /// Apply the function to a mutable reference of each element in the vector with its index.
     public inline fun enumerate_mut(v: &mut vector, f: |u64, &mut Element|) {
         let i = 0;
@@ -318,7 +384,7 @@ module std::vector {
     }
 
     /// Map the function over the references of the elements of the vector, producing a new vector without modifying the
-    /// original map.
+    /// original vector.
     public inline fun map_ref(
         v: &vector,
         f: |&Element|NewElement
@@ -328,6 +394,22 @@ module std::vector {
         result
     }
 
+    /// Map the function over the references of the element pairs of two vectors, producing a new vector from the return
+    /// values without modifying the original vectors.
+    public inline fun zip_map_ref(
+        v1: &vector,
+        v2: &vector,
+        f: |&Element1, &Element2|NewElement
+    ): vector {
+        // We can't use the constant EVECTORS_LENGTH_MISMATCH here as all calling code would then need to define it
+        // due to how inline functions work.
+        assert!(length(v1) == length(v2), 0x20002);
+
+        let result = vector[];
+        zip_ref(v1, v2, |e1, e2| push_back(&mut result, f(e1, e2)));
+        result
+    }
+
     /// Map the function over the elements of the vector, producing a new vector.
     public inline fun map(
         v: vector,
@@ -338,6 +420,21 @@ module std::vector {
         result
     }
 
+    /// Map the function over the element pairs of the two vectors, producing a new vector.
+    public inline fun zip_map(
+        v1: vector,
+        v2: vector,
+        f: |Element1, Element2|NewElement
+    ): vector {
+        // We can't use the constant EVECTORS_LENGTH_MISMATCH here as all calling code would then need to define it
+        // due to how inline functions work.
+        assert!(length(&v1) == length(&v2), 0x20002);
+
+        let result = vector[];
+        zip(v1, v2, |e1, e2| push_back(&mut result, f(e1, e2)));
+        result
+    }
+
     /// Filter the vector using the boolean function, removing all elements for which `p(e)` is not true.
     public inline fun filter(
         v: vector,
diff --git a/aptos-move/framework/move-stdlib/tests/vector_tests.move b/aptos-move/framework/move-stdlib/tests/vector_tests.move
index ea2c540d9880d..606e9cd66fcfc 100644
--- a/aptos-move/framework/move-stdlib/tests/vector_tests.move
+++ b/aptos-move/framework/move-stdlib/tests/vector_tests.move
@@ -588,6 +588,25 @@ module std::vector_tests {
         assert!(s == 6, 0)
     }
 
+    #[test]
+    fun test_zip() {
+        let v1 = vector[1, 2, 3];
+        let v2 = vector[10, 20, 30];
+        let s = 0;
+        V::zip(v1, v2, |e1, e2| s = s + e1 * e2);
+        assert!(s == 140, 0);
+    }
+
+    #[test]
+    // zip is an inline function so any error code will be reported at the call site.
+    #[expected_failure(abort_code = V::EVECTORS_LENGTH_MISMATCH, location = Self)]
+    fun test_zip_mismatching_lengths_should_fail() {
+        let v1 = vector[1];
+        let v2 = vector[10, 20];
+        let s = 0;
+        V::zip(v1, v2, |e1, e2| s = s + e1 * e2);
+    }
+
     #[test]
     fun test_enumerate_ref() {
         let v = vector[1, 2, 3];
@@ -617,6 +636,83 @@ module std::vector_tests {
         assert!(v == vector[2, 3, 4], 0)
     }
 
+    #[test]
+    fun test_zip_ref() {
+        let v1 = vector[1, 2, 3];
+        let v2 = vector[10, 20, 30];
+        let s = 0;
+        V::zip_ref(&v1, &v2, |e1, e2| s = s + *e1 * *e2);
+        assert!(s == 140, 0);
+    }
+
+    #[test]
+    // zip_ref is an inline function so any error code will be reported at the call site.
+    #[expected_failure(abort_code = V::EVECTORS_LENGTH_MISMATCH, location = Self)]
+    fun test_zip_ref_mismatching_lengths_should_fail() {
+        let v1 = vector[1];
+        let v2 = vector[10, 20];
+        let s = 0;
+        V::zip_ref(&v1, &v2, |e1, e2| s = s + *e1 * *e2);
+    }
+
+    #[test]
+    fun test_zip_mut() {
+        let v1 = vector[1, 2, 3];
+        let v2 = vector[10, 20, 30];
+        V::zip_mut(&mut v1, &mut v2, |e1, e2| {
+            let e1: &mut u64 = e1;
+            let e2: &mut u64 = e2;
+            *e1 = *e1 + 1;
+            *e2 = *e2 + 10;
+        });
+        assert!(v1 == vector[2, 3, 4], 0);
+        assert!(v2 == vector[20, 30, 40], 0);
+    }
+
+    #[test]
+    fun test_zip_map() {
+        let v1 = vector[1, 2, 3];
+        let v2 = vector[10, 20, 30];
+        let result = V::zip_map(v1, v2, |e1, e2| e1 + e2);
+        assert!(result == vector[11, 22, 33], 0);
+    }
+
+    #[test]
+    fun test_zip_map_ref() {
+        let v1 = vector[1, 2, 3];
+        let v2 = vector[10, 20, 30];
+        let result = V::zip_map_ref(&v1, &v2, |e1, e2| *e1 + *e2);
+        assert!(result == vector[11, 22, 33], 0);
+    }
+
+    #[test]
+    // zip_mut is an inline function so any error code will be reported at the call site.
+    #[expected_failure(abort_code = V::EVECTORS_LENGTH_MISMATCH, location = Self)]
+    fun test_zip_mut_mismatching_lengths_should_fail() {
+        let v1 = vector[1];
+        let v2 = vector[10, 20];
+        let s = 0;
+        V::zip_mut(&mut v1, &mut v2, |e1, e2| s = s + *e1 * *e2);
+    }
+
+    #[test]
+    // zip_map is an inline function so any error code will be reported at the call site.
+    #[expected_failure(abort_code = V::EVECTORS_LENGTH_MISMATCH, location = Self)]
+    fun test_zip_map_mismatching_lengths_should_fail() {
+        let v1 = vector[1];
+        let v2 = vector[10, 20];
+        V::zip_map(v1, v2, |e1, e2| e1 * e2);
+    }
+
+    #[test]
+    // zip_map_ref is an inline function so any error code will be reported at the call site.
+    #[expected_failure(abort_code = V::EVECTORS_LENGTH_MISMATCH, location = Self)]
+    fun test_zip_map_ref_mismatching_lengths_should_fail() {
+        let v1 = vector[1];
+        let v2 = vector[10, 20];
+        V::zip_map_ref(&v1, &v2, |e1, e2| *e1 * *e2);
+    }
+
     #[test]
     fun test_enumerate_mut() {
         let v = vector[1, 2, 3];

From fb415a403092c4603182b8dfbdacb625a7166529 Mon Sep 17 00:00:00 2001
From: Stelian Ionescu 
Date: Thu, 8 Jun 2023 15:46:16 -0400
Subject: [PATCH 120/200] [TF] Add health check for waypoint service in GCP
 testnet-addons

Also, add a default for "gke_maintenance_policy" in the
aptos-node-testnet module.
---
 terraform/aptos-node-testnet/gcp/addons.tf    |  2 +-
 terraform/aptos-node-testnet/gcp/main.tf      |  8 ++++--
 terraform/aptos-node-testnet/gcp/variables.tf |  8 +++++-
 .../testnet-addons/templates/waypoint.yaml    | 28 +++++++++++++++++--
 4 files changed, 38 insertions(+), 8 deletions(-)

diff --git a/terraform/aptos-node-testnet/gcp/addons.tf b/terraform/aptos-node-testnet/gcp/addons.tf
index 3bd31c0487e19..372a88e3c4ebd 100644
--- a/terraform/aptos-node-testnet/gcp/addons.tf
+++ b/terraform/aptos-node-testnet/gcp/addons.tf
@@ -153,7 +153,7 @@ resource "helm_release" "testnet-addons" {
       }
       ingress = {
         gce_static_ip           = "aptos-${local.workspace_name}-testnet-addons-ingress"
-        gce_managed_certificate = "aptos-${local.workspace_name}-testnet-addons"
+        gce_managed_certificate = "aptos-${local.workspace_name}-${var.zone_name}-testnet-addons"
       }
       load_test = {
         fullnodeGroups = try(var.aptos_node_helm_values.fullnode.groups, [])
diff --git a/terraform/aptos-node-testnet/gcp/main.tf b/terraform/aptos-node-testnet/gcp/main.tf
index 2dd2c99b6b1b1..d9b7193b0457c 100644
--- a/terraform/aptos-node-testnet/gcp/main.tf
+++ b/terraform/aptos-node-testnet/gcp/main.tf
@@ -26,9 +26,11 @@ module "validator" {
   region  = var.region
 
   # DNS
-  zone_name    = var.zone_name # keep empty if you don't want a DNS name
-  zone_project = var.zone_project
-  record_name  = var.record_name
+  zone_name     = var.zone_name # keep empty if you don't want a DNS name
+  zone_project  = var.zone_project
+  record_name   = var.record_name
+  workspace_dns = var.workspace_dns
+  # dns_prefix_name = var.dns_prefix_name
   # do not create the main fullnode and validator DNS records
   # instead, rely on external-dns from the testnet-addons
   create_dns_records = var.create_dns_records
diff --git a/terraform/aptos-node-testnet/gcp/variables.tf b/terraform/aptos-node-testnet/gcp/variables.tf
index 4e2a30cd30cae..d7e88193a713c 100644
--- a/terraform/aptos-node-testnet/gcp/variables.tf
+++ b/terraform/aptos-node-testnet/gcp/variables.tf
@@ -211,5 +211,11 @@ variable "gke_maintenance_policy" {
       recurrence = string
     })
   })
-  default = null
+  default = {
+    recurring_window = {
+      start_time = "2023-06-01T14:00:00Z"
+      end_time   = "2023-06-01T18:00:00Z"
+      recurrence = "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"
+    }
+  }
 }
diff --git a/terraform/helm/testnet-addons/templates/waypoint.yaml b/terraform/helm/testnet-addons/templates/waypoint.yaml
index f7df236e432b1..154fa3f986ed5 100644
--- a/terraform/helm/testnet-addons/templates/waypoint.yaml
+++ b/terraform/helm/testnet-addons/templates/waypoint.yaml
@@ -6,7 +6,13 @@ metadata:
     {{- include "testnet-addons.labels" . | nindent 4 }}
     app: {{ include "testnet-addons.fullname" . }}-waypoint
   annotations:
-    alb.ingress.kubernetes.io/healthcheck-path: /health
+    {{- if eq .Values.cloud "EKS" }}
+    alb.ingress.kubernetes.io/healthcheck-path: /waypoint.txt
+    {{- end }}
+    {{- if eq .Values.cloud "GKE" }}
+    cloud.google.com/backend-config: '{"default":"{{ include "testnet-addons.fullname" . }}-waypoint"}'
+    cloud.google.com/neg: '{"ingress": true}'
+    {{- end }}
 spec:
   selector:
     {{- include "testnet-addons.selectorLabels" . | nindent 4 }}
@@ -15,9 +21,25 @@ spec:
   - port: 80
     targetPort: 8080
   type: NodePort
-
 ---
-
+{{- if eq .Values.cloud "GKE" }}
+apiVersion: cloud.google.com/v1
+kind: BackendConfig
+metadata:
+  name: {{ include "testnet-addons.fullname" . }}-waypoint
+  namespace: default
+spec:
+  healthCheck:
+    checkIntervalSec: 30
+    timeoutSec: 5
+    healthyThreshold: 1
+    unhealthyThreshold: 2
+    type: HTTP
+    requestPath: /waypoint.txt
+    # container targetPort
+    port: 8080
+{{- end }}
+---
 apiVersion: apps/v1
 kind: Deployment
 metadata:

From 13aaec4d52668140cbebe54069a99b979507af06 Mon Sep 17 00:00:00 2001
From: Guoteng Rao <3603304+grao1991@users.noreply.github.com>
Date: Thu, 8 Jun 2023 17:24:43 -0700
Subject: [PATCH 121/200] [Storage][Sharding][Pruner] Restructure ledger
 pruner. (#8443)

---
 storage/aptosdb/src/ledger_db.rs              |  16 ++
 storage/aptosdb/src/lib.rs                    |  24 +-
 storage/aptosdb/src/pruner/db_pruner.rs       |  15 +-
 storage/aptosdb/src/pruner/db_sub_pruner.rs   |   9 +-
 .../pruner/event_store/event_store_pruner.rs  |  51 ++++-
 .../ledger_store/ledger_metadata_pruner.rs    |  64 ++++++
 .../ledger_store/ledger_store_pruner.rs       | 212 ++++++++----------
 .../aptosdb/src/pruner/ledger_store/mod.rs    |   2 +-
 .../ledger_store/version_data_pruner.rs       |  28 ---
 storage/aptosdb/src/pruner/pruner_utils.rs    |  32 ++-
 storage/aptosdb/src/pruner/state_kv_pruner.rs |  60 ++---
 storage/aptosdb/src/pruner/state_store/mod.rs |  48 +---
 .../pruner/state_store/state_value_pruner.rs  |  15 +-
 .../src/pruner/transaction_store/mod.rs       |   4 +-
 .../transaction_accumulator_pruner.rs         |  59 +++++
 .../transaction_info_pruner.rs                |  59 +++++
 .../transaction_store/transaction_pruner.rs   |  75 +++++++
 .../transaction_store_pruner.rs               |  62 -----
 .../transaction_store/write_set_pruner.rs     |  51 ++++-
 storage/aptosdb/src/schema/db_metadata/mod.rs |   5 +
 storage/aptosdb/src/state_kv_db.rs            |  14 --
 21 files changed, 517 insertions(+), 388 deletions(-)
 create mode 100644 storage/aptosdb/src/pruner/ledger_store/ledger_metadata_pruner.rs
 delete mode 100644 storage/aptosdb/src/pruner/ledger_store/version_data_pruner.rs
 create mode 100644 storage/aptosdb/src/pruner/transaction_store/transaction_accumulator_pruner.rs
 create mode 100644 storage/aptosdb/src/pruner/transaction_store/transaction_info_pruner.rs
 create mode 100644 storage/aptosdb/src/pruner/transaction_store/transaction_pruner.rs
 delete mode 100644 storage/aptosdb/src/pruner/transaction_store/transaction_store_pruner.rs

diff --git a/storage/aptosdb/src/ledger_db.rs b/storage/aptosdb/src/ledger_db.rs
index 658d05d3f1bfb..9438d4c7bfda7 100644
--- a/storage/aptosdb/src/ledger_db.rs
+++ b/storage/aptosdb/src/ledger_db.rs
@@ -167,18 +167,34 @@ impl LedgerDb {
         &self.transaction_accumulator_db
     }
 
+    pub(crate) fn transaction_accumulator_db_arc(&self) -> Arc {
+        Arc::clone(&self.transaction_accumulator_db)
+    }
+
     pub(crate) fn transaction_db(&self) -> &DB {
         &self.transaction_db
     }
 
+    pub(crate) fn transaction_db_arc(&self) -> Arc {
+        Arc::clone(&self.transaction_db)
+    }
+
     pub(crate) fn transaction_info_db(&self) -> &DB {
         &self.transaction_info_db
     }
 
+    pub(crate) fn transaction_info_db_arc(&self) -> Arc {
+        Arc::clone(&self.transaction_info_db)
+    }
+
     pub(crate) fn write_set_db(&self) -> &DB {
         &self.write_set_db
     }
 
+    pub(crate) fn write_set_db_arc(&self) -> Arc {
+        Arc::clone(&self.write_set_db)
+    }
+
     fn open_rocksdb(
         path: PathBuf,
         name: &str,
diff --git a/storage/aptosdb/src/lib.rs b/storage/aptosdb/src/lib.rs
index 633f86885b7ee..ac7db9bd2d6a4 100644
--- a/storage/aptosdb/src/lib.rs
+++ b/storage/aptosdb/src/lib.rs
@@ -55,8 +55,8 @@ use crate::{
     },
     pruner::{
         ledger_pruner_manager::LedgerPrunerManager, pruner_manager::PrunerManager, pruner_utils,
-        state_kv_pruner::StateKvPruner, state_kv_pruner_manager::StateKvPrunerManager,
-        state_merkle_pruner_manager::StateMerklePrunerManager, state_store::StateMerklePruner,
+        state_kv_pruner_manager::StateKvPrunerManager,
+        state_merkle_pruner_manager::StateMerklePrunerManager,
     },
     schema::*,
     stale_node_index::StaleNodeIndexSchema,
@@ -2113,28 +2113,10 @@ impl DbWriter for AptosDB {
                 &DbMetadataValue::Version(version),
             )?;
 
-            let mut state_merkle_batch = SchemaBatch::new();
-            StateMerklePruner::prune_genesis(
-                self.state_merkle_db.clone(),
-                &mut state_merkle_batch,
-            )?;
-
-            let mut state_kv_batch = SchemaBatch::new();
-            StateKvPruner::prune_genesis(
-                self.state_store.state_kv_db.clone(),
-                &mut state_kv_batch,
-            )?;
-
             // Apply the change set writes to the database (atomically) and update in-memory state
             //
             // TODO(grao): Support sharding here.
-            self.state_merkle_db
-                .metadata_db()
-                .write_schemas(state_merkle_batch)?;
-            self.state_kv_db
-                .clone()
-                .commit_nonsharded(version, state_kv_batch)?;
-            self.ledger_db.metadata_db_arc().write_schemas(batch)?;
+            self.ledger_db.metadata_db().write_schemas(batch)?;
 
             self.ledger_pruner.save_min_readable_version(version)?;
             self.state_store
diff --git a/storage/aptosdb/src/pruner/db_pruner.rs b/storage/aptosdb/src/pruner/db_pruner.rs
index b55bbeac145a9..acbbb9f63fe2b 100644
--- a/storage/aptosdb/src/pruner/db_pruner.rs
+++ b/storage/aptosdb/src/pruner/db_pruner.rs
@@ -3,7 +3,6 @@
 
 use anyhow::{Context, Result};
 use aptos_logger::info;
-use aptos_schemadb::SchemaBatch;
 use aptos_types::transaction::Version;
 use std::cmp::min;
 
@@ -32,11 +31,8 @@ pub trait DBPruner: Send + Sync {
     /// Initializes the least readable version stored in underlying DB storage
     fn initialize_min_readable_version(&self) -> Result;
 
-    /// Saves the min readable version.
-    fn save_min_readable_version(&self, version: Version, batch: &SchemaBatch) -> Result<()>;
-
-    /// Returns the least readable version stores in the DB pruner
-    fn min_readable_version(&self) -> Version;
+    /// Returns the progress of the pruner.
+    fn progress(&self) -> Version;
 
     /// Sets the target version for the pruner
     fn set_target_version(&self, target_version: Version);
@@ -49,16 +45,13 @@ pub trait DBPruner: Send + Sync {
     fn get_current_batch_target(&self, max_versions: Version) -> Version {
         // Current target version  might be less than the target version to ensure we don't prune
         // more than max_version in one go.
-        min(
-            self.min_readable_version() + max_versions,
-            self.target_version(),
-        )
+        min(self.progress() + max_versions, self.target_version())
     }
     /// Records the current progress of the pruner by updating the least readable version
     fn record_progress(&self, min_readable_version: Version);
 
     /// True if there is pruning work pending to be done
     fn is_pruning_pending(&self) -> bool {
-        self.target_version() > self.min_readable_version()
+        self.target_version() > self.progress()
     }
 }
diff --git a/storage/aptosdb/src/pruner/db_sub_pruner.rs b/storage/aptosdb/src/pruner/db_sub_pruner.rs
index 016854571ea5a..b4b70af96bcfa 100644
--- a/storage/aptosdb/src/pruner/db_sub_pruner.rs
+++ b/storage/aptosdb/src/pruner/db_sub_pruner.rs
@@ -1,16 +1,11 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
-use aptos_schemadb::SchemaBatch;
+use aptos_types::transaction::Version;
 
 /// Defines the trait for sub-pruner of a parent DB pruner
 pub trait DBSubPruner {
     /// Performs the actual pruning, a target version is passed, which is the target the pruner
     /// tries to prune.
-    fn prune(
-        &self,
-        db_batch: &mut SchemaBatch,
-        min_readable_version: u64,
-        target_version: u64,
-    ) -> anyhow::Result<()>;
+    fn prune(&self, current_progress: Version, target_version: Version) -> anyhow::Result<()>;
 }
diff --git a/storage/aptosdb/src/pruner/event_store/event_store_pruner.rs b/storage/aptosdb/src/pruner/event_store/event_store_pruner.rs
index 5ffed3a0b6c94..b35ba237bd4b9 100644
--- a/storage/aptosdb/src/pruner/event_store/event_store_pruner.rs
+++ b/storage/aptosdb/src/pruner/event_store/event_store_pruner.rs
@@ -1,29 +1,56 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
-use crate::{pruner::db_sub_pruner::DBSubPruner, EventStore};
-use aptos_schemadb::SchemaBatch;
+
+use crate::{
+    pruner::{
+        db_sub_pruner::DBSubPruner, pruner_utils::get_or_initialize_ledger_subpruner_progress,
+    },
+    schema::db_metadata::{DbMetadataKey, DbMetadataSchema, DbMetadataValue},
+    EventStore,
+};
+use anyhow::Result;
+use aptos_schemadb::{SchemaBatch, DB};
+use aptos_types::transaction::Version;
 use std::sync::Arc;
 
 #[derive(Debug)]
 pub struct EventStorePruner {
     event_store: Arc,
+    event_db: Arc,
 }
 
 impl DBSubPruner for EventStorePruner {
-    fn prune(
-        &self,
-        db_batch: &mut SchemaBatch,
-        min_readable_version: u64,
-        target_version: u64,
-    ) -> anyhow::Result<()> {
+    fn prune(&self, current_progress: Version, target_version: Version) -> Result<()> {
+        let batch = SchemaBatch::new();
         self.event_store
-            .prune_events(min_readable_version, target_version, db_batch)?;
-        Ok(())
+            .prune_events(current_progress, target_version, &batch)?;
+        batch.put::(
+            &DbMetadataKey::EventPrunerProgress,
+            &DbMetadataValue::Version(target_version),
+        )?;
+        self.event_db.write_schemas(batch)
     }
 }
 
 impl EventStorePruner {
-    pub(in crate::pruner) fn new(event_store: Arc) -> Self {
-        EventStorePruner { event_store }
+    pub(in crate::pruner) fn new(
+        event_store: Arc,
+        event_db: Arc,
+        metadata_progress: Version,
+    ) -> Result {
+        let progress = get_or_initialize_ledger_subpruner_progress(
+            &event_db,
+            &DbMetadataKey::EventPrunerProgress,
+            metadata_progress,
+        )?;
+
+        let myself = EventStorePruner {
+            event_store,
+            event_db,
+        };
+
+        myself.prune(progress, metadata_progress)?;
+
+        Ok(myself)
     }
 }
diff --git a/storage/aptosdb/src/pruner/ledger_store/ledger_metadata_pruner.rs b/storage/aptosdb/src/pruner/ledger_store/ledger_metadata_pruner.rs
new file mode 100644
index 0000000000000..c4514b3687177
--- /dev/null
+++ b/storage/aptosdb/src/pruner/ledger_store/ledger_metadata_pruner.rs
@@ -0,0 +1,64 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::schema::{
+    db_metadata::{DbMetadataKey, DbMetadataSchema, DbMetadataValue},
+    version_data::VersionDataSchema,
+};
+use anyhow::{anyhow, Result};
+use aptos_schemadb::{ReadOptions, SchemaBatch, DB};
+use aptos_types::transaction::Version;
+use std::sync::Arc;
+
+#[derive(Debug)]
+pub struct LedgerMetadataPruner {
+    ledger_metadata_db: Arc,
+}
+
+impl LedgerMetadataPruner {
+    pub(in crate::pruner) fn new(ledger_metadata_db: Arc) -> Result {
+        if let Some(v) =
+            ledger_metadata_db.get::(&DbMetadataKey::LedgerPrunerProgress)?
+        {
+            v.expect_version();
+        } else {
+            // NOTE: I **think** all db should have the LedgerPrunerProgress. Have a fallback path
+            // here in case the database was super old before we introducing this progress counter.
+            let mut iter = ledger_metadata_db.iter::(ReadOptions::default())?;
+            iter.seek_to_first();
+            let version = match iter.next().transpose()? {
+                Some((version, _)) => version,
+                None => 0,
+            };
+            ledger_metadata_db.put::(
+                &DbMetadataKey::LedgerPrunerProgress,
+                &DbMetadataValue::Version(version),
+            )?;
+        }
+
+        Ok(LedgerMetadataPruner { ledger_metadata_db })
+    }
+
+    pub(in crate::pruner) fn prune(
+        &self,
+        current_progress: Version,
+        target_version: Version,
+    ) -> Result<()> {
+        let batch = SchemaBatch::new();
+        for version in current_progress..target_version {
+            batch.delete::(&version)?;
+        }
+        batch.put::(
+            &DbMetadataKey::LedgerPrunerProgress,
+            &DbMetadataValue::Version(target_version),
+        )?;
+        self.ledger_metadata_db.write_schemas(batch)
+    }
+
+    pub(in crate::pruner) fn progress(&self) -> Result {
+        self.ledger_metadata_db
+            .get::(&DbMetadataKey::LedgerPrunerProgress)?
+            .map(|v| v.expect_version())
+            .ok_or_else(|| anyhow!("LedgerPrunerProgress cannot be None."))
+    }
+}
diff --git a/storage/aptosdb/src/pruner/ledger_store/ledger_store_pruner.rs b/storage/aptosdb/src/pruner/ledger_store/ledger_store_pruner.rs
index a4f6653cace6d..19d66aae57fe2 100644
--- a/storage/aptosdb/src/pruner/ledger_store/ledger_store_pruner.rs
+++ b/storage/aptosdb/src/pruner/ledger_store/ledger_store_pruner.rs
@@ -2,40 +2,40 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::{
-    db_metadata::DbMetadataSchema,
+    ledger_db::LedgerDb,
     metrics::PRUNER_VERSIONS,
     pruner::{
         db_pruner::DBPruner,
         db_sub_pruner::DBSubPruner,
         event_store::event_store_pruner::EventStorePruner,
-        ledger_store::version_data_pruner::VersionDataPruner,
+        ledger_store::ledger_metadata_pruner::LedgerMetadataPruner,
         transaction_store::{
-            transaction_store_pruner::TransactionStorePruner, write_set_pruner::WriteSetPruner,
+            transaction_accumulator_pruner::TransactionAccumulatorPruner,
+            transaction_info_pruner::TransactionInfoPruner, transaction_pruner::TransactionPruner,
+            write_set_pruner::WriteSetPruner,
         },
     },
-    schema::{
-        db_metadata::{DbMetadataKey, DbMetadataValue},
-        transaction::TransactionSchema,
-    },
     EventStore, TransactionStore,
 };
-use aptos_logger::warn;
-use aptos_schemadb::{ReadOptions, SchemaBatch, DB};
+use anyhow::Result;
 use aptos_types::transaction::{AtomicVersion, Version};
-use std::sync::{atomic::Ordering, Arc};
+use std::{
+    cmp::min,
+    sync::{atomic::Ordering, Arc},
+};
 
 pub const LEDGER_PRUNER_NAME: &str = "ledger_pruner";
 
 /// Responsible for pruning everything except for the state tree.
 pub(crate) struct LedgerPruner {
-    db: Arc,
     /// Keeps track of the target version that the pruner needs to achieve.
     target_version: AtomicVersion,
-    min_readable_version: AtomicVersion,
-    transaction_store_pruner: Arc,
-    version_data_pruner: Arc,
-    event_store_pruner: Arc,
-    write_set_pruner: Arc,
+
+    progress: AtomicVersion,
+
+    ledger_metadata_pruner: Box,
+
+    sub_pruners: Vec>,
 }
 
 impl DBPruner for LedgerPruner {
@@ -43,86 +43,50 @@ impl DBPruner for LedgerPruner {
         LEDGER_PRUNER_NAME
     }
 
-    fn prune(&self, max_versions: usize) -> anyhow::Result {
-        if !self.is_pruning_pending() {
-            return Ok(self.min_readable_version());
-        }
+    fn prune(&self, max_versions: usize) -> Result {
+        let mut progress = self.progress();
+        let target_version = self.target_version();
 
-        // Collect the schema batch writes
-        let mut db_batch = SchemaBatch::new();
-        let current_target_version = self.prune_inner(max_versions, &mut db_batch)?;
-        self.save_min_readable_version(current_target_version, &db_batch)?;
-        // Commit all the changes to DB atomically
-        self.db.write_schemas(db_batch)?;
-
-        // TODO(zcc): recording progress after writing schemas might provide wrong answers to
-        // API calls when they query min_readable_version while the write_schemas are still in
-        // progress.
-        self.record_progress(current_target_version);
-        Ok(current_target_version)
-    }
+        while progress < target_version {
+            let current_batch_target_version =
+                min(progress + max_versions as Version, target_version);
 
-    fn save_min_readable_version(
-        &self,
-        version: Version,
-        batch: &SchemaBatch,
-    ) -> anyhow::Result<()> {
-        batch.put::(
-            &DbMetadataKey::LedgerPrunerProgress,
-            &DbMetadataValue::Version(version),
-        )
-    }
+            self.ledger_metadata_pruner
+                .prune(progress, current_batch_target_version)?;
 
-    fn initialize_min_readable_version(&self) -> anyhow::Result {
-        let stored_min_version = self
-            .db
-            .get::(&DbMetadataKey::LedgerPrunerProgress)?
-            .map_or(0, |v| v.expect_version());
-        let mut iter = self.db.iter::(ReadOptions::default())?;
-        iter.seek(&stored_min_version)?;
-        let version = match iter.next().transpose()? {
-            Some((version, _)) => version,
-            None => 0,
-        };
-        match version.cmp(&stored_min_version) {
-            std::cmp::Ordering::Greater => {
-                let res = self.db.put::(
-                    &DbMetadataKey::LedgerPrunerProgress,
-                    &DbMetadataValue::Version(version),
-                );
-                warn!(
-                    stored_min_version = stored_min_version,
-                    actual_min_version = version,
-                    res = ?res,
-                    "Try to update stored min readable transaction version to the actual one.",
-                );
-                Ok(version)
-            },
-            std::cmp::Ordering::Equal => Ok(version),
-            std::cmp::Ordering::Less => {
-                panic!("No transaction is found at or after stored ledger pruner progress ({}), db might be corrupted.", stored_min_version)
-            },
+            // NOTE: If necessary, this can be done in parallel.
+            self.sub_pruners
+                .iter()
+                .try_for_each(|pruner| pruner.prune(progress, current_batch_target_version))?;
+
+            progress = current_batch_target_version;
+            self.record_progress(progress);
         }
+
+        Ok(target_version)
+    }
+
+    fn initialize_min_readable_version(&self) -> Result {
+        self.ledger_metadata_pruner.progress()
     }
 
-    fn min_readable_version(&self) -> Version {
-        self.min_readable_version.load(Ordering::Relaxed)
+    fn progress(&self) -> Version {
+        self.progress.load(Ordering::SeqCst)
     }
 
     fn set_target_version(&self, target_version: Version) {
-        self.target_version.store(target_version, Ordering::Relaxed);
+        self.target_version.store(target_version, Ordering::SeqCst);
         PRUNER_VERSIONS
             .with_label_values(&["ledger_pruner", "target"])
             .set(target_version as i64);
     }
 
     fn target_version(&self) -> Version {
-        self.target_version.load(Ordering::Relaxed)
+        self.target_version.load(Ordering::SeqCst)
     }
 
     fn record_progress(&self, min_readable_version: Version) {
-        self.min_readable_version
-            .store(min_readable_version, Ordering::Relaxed);
+        self.progress.store(min_readable_version, Ordering::SeqCst);
         PRUNER_VERSIONS
             .with_label_values(&["ledger_pruner", "progress"])
             .set(min_readable_version as i64);
@@ -130,53 +94,57 @@ impl DBPruner for LedgerPruner {
 }
 
 impl LedgerPruner {
-    pub fn new(
-        db: Arc,
-        transaction_store: Arc,
-        event_store: Arc,
-    ) -> Self {
+    pub fn new(ledger_db: Arc) -> Result {
+        let ledger_metadata_pruner = Box::new(
+            LedgerMetadataPruner::new(ledger_db.metadata_db_arc())
+                .expect("Failed to initialize ledger_metadata_pruner."),
+        );
+
+        let metadata_progress = ledger_metadata_pruner.progress()?;
+
+        let transaction_store = Arc::new(TransactionStore::new(Arc::clone(&ledger_db)));
+
+        let event_store_pruner = Box::new(EventStorePruner::new(
+            Arc::new(EventStore::new(ledger_db.event_db_arc())),
+            ledger_db.event_db_arc(),
+            metadata_progress,
+        )?);
+        let transaction_accumulator_pruner = Box::new(TransactionAccumulatorPruner::new(
+            Arc::clone(&transaction_store),
+            ledger_db.transaction_accumulator_db_arc(),
+            metadata_progress,
+        )?);
+        let transaction_info_pruner = Box::new(TransactionInfoPruner::new(
+            Arc::clone(&transaction_store),
+            ledger_db.transaction_info_db_arc(),
+            metadata_progress,
+        )?);
+        let transaction_pruner = Box::new(TransactionPruner::new(
+            Arc::clone(&transaction_store),
+            ledger_db.transaction_db_arc(),
+            metadata_progress,
+        )?);
+        let write_set_pruner = Box::new(WriteSetPruner::new(
+            Arc::clone(&transaction_store),
+            ledger_db.write_set_db_arc(),
+            metadata_progress,
+        )?);
+
         let pruner = LedgerPruner {
-            db,
-            target_version: AtomicVersion::new(0),
-            min_readable_version: AtomicVersion::new(0),
-            transaction_store_pruner: Arc::new(TransactionStorePruner::new(
-                transaction_store.clone(),
-            )),
-            event_store_pruner: Arc::new(EventStorePruner::new(event_store)),
-            write_set_pruner: Arc::new(WriteSetPruner::new(transaction_store)),
-            version_data_pruner: Arc::new(VersionDataPruner::new()),
+            target_version: AtomicVersion::new(metadata_progress),
+            progress: AtomicVersion::new(metadata_progress),
+            ledger_metadata_pruner,
+            sub_pruners: vec![
+                event_store_pruner,
+                transaction_accumulator_pruner,
+                transaction_info_pruner,
+                transaction_pruner,
+                write_set_pruner,
+            ],
         };
-        pruner.initialize();
-        pruner
-    }
-
-    fn prune_inner(
-        &self,
-        max_versions: usize,
-        db_batch: &mut SchemaBatch,
-    ) -> anyhow::Result {
-        let min_readable_version = self.min_readable_version();
-
-        // Current target version might be less than the target version to ensure we don't prune
-        // more than max_version in one go.
-        let current_target_version = self.get_current_batch_target(max_versions as Version);
 
-        if current_target_version < min_readable_version {
-            return Ok(min_readable_version);
-        }
+        pruner.initialize();
 
-        self.transaction_store_pruner.prune(
-            db_batch,
-            min_readable_version,
-            current_target_version,
-        )?;
-        self.write_set_pruner
-            .prune(db_batch, min_readable_version, current_target_version)?;
-        self.version_data_pruner
-            .prune(db_batch, min_readable_version, current_target_version)?;
-        self.event_store_pruner
-            .prune(db_batch, min_readable_version, current_target_version)?;
-
-        Ok(current_target_version)
+        Ok(pruner)
     }
 }
diff --git a/storage/aptosdb/src/pruner/ledger_store/mod.rs b/storage/aptosdb/src/pruner/ledger_store/mod.rs
index d0f57aa5727f5..764c7e183cbd0 100644
--- a/storage/aptosdb/src/pruner/ledger_store/mod.rs
+++ b/storage/aptosdb/src/pruner/ledger_store/mod.rs
@@ -1,5 +1,5 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
+pub(crate) mod ledger_metadata_pruner;
 pub(crate) mod ledger_store_pruner;
-pub(crate) mod version_data_pruner;
diff --git a/storage/aptosdb/src/pruner/ledger_store/version_data_pruner.rs b/storage/aptosdb/src/pruner/ledger_store/version_data_pruner.rs
deleted file mode 100644
index 672f9bd84f88e..0000000000000
--- a/storage/aptosdb/src/pruner/ledger_store/version_data_pruner.rs
+++ /dev/null
@@ -1,28 +0,0 @@
-// Copyright © Aptos Foundation
-// SPDX-License-Identifier: Apache-2.0
-
-use crate::{pruner::db_sub_pruner::DBSubPruner, schema::version_data::VersionDataSchema};
-use aptos_schemadb::SchemaBatch;
-
-#[derive(Debug)]
-pub struct VersionDataPruner {}
-
-impl DBSubPruner for VersionDataPruner {
-    fn prune(
-        &self,
-        db_batch: &mut SchemaBatch,
-        min_readable_version: u64,
-        target_version: u64,
-    ) -> anyhow::Result<()> {
-        for version in min_readable_version..target_version {
-            db_batch.delete::(&version)?;
-        }
-        Ok(())
-    }
-}
-
-impl VersionDataPruner {
-    pub(in crate::pruner) fn new() -> Self {
-        VersionDataPruner {}
-    }
-}
diff --git a/storage/aptosdb/src/pruner/pruner_utils.rs b/storage/aptosdb/src/pruner/pruner_utils.rs
index 581a9672182eb..72433a55b3ad6 100644
--- a/storage/aptosdb/src/pruner/pruner_utils.rs
+++ b/storage/aptosdb/src/pruner/pruner_utils.rs
@@ -10,15 +10,17 @@ use crate::{
         state_kv_pruner::StateKvPruner,
         state_store::{generics::StaleNodeIndexSchemaTrait, StateMerklePruner},
     },
-    schema::{db_metadata::DbMetadataKey, version_data::VersionDataSchema},
+    schema::{
+        db_metadata::{DbMetadataKey, DbMetadataSchema, DbMetadataValue},
+        version_data::VersionDataSchema,
+    },
     state_kv_db::StateKvDb,
     state_merkle_db::StateMerkleDb,
     utils::get_progress,
-    EventStore, TransactionStore,
 };
 use anyhow::Result;
 use aptos_jellyfish_merkle::StaleNodeIndex;
-use aptos_schemadb::{schema::KeyCodec, ReadOptions};
+use aptos_schemadb::{schema::KeyCodec, ReadOptions, DB};
 use aptos_types::transaction::Version;
 use std::sync::Arc;
 
@@ -34,11 +36,7 @@ where
 
 /// A utility function to instantiate the ledger pruner
 pub(crate) fn create_ledger_pruner(ledger_db: Arc) -> Arc {
-    Arc::new(LedgerPruner::new(
-        ledger_db.metadata_db_arc(),
-        Arc::new(TransactionStore::new(Arc::clone(&ledger_db))),
-        Arc::new(EventStore::new(ledger_db.event_db_arc())),
-    ))
+    Arc::new(LedgerPruner::new(ledger_db).expect("Failed to create ledger pruner."))
 }
 
 /// A utility function to instantiate the state kv pruner.
@@ -82,3 +80,21 @@ where
 {
     Ok(get_progress(state_merkle_db.metadata_db(), &S::tag())?.unwrap_or(0))
 }
+
+pub(crate) fn get_or_initialize_ledger_subpruner_progress(
+    sub_db: &DB,
+    progress_key: &DbMetadataKey,
+    metadata_progress: Version,
+) -> Result {
+    Ok(
+        if let Some(v) = sub_db.get::(progress_key)? {
+            v.expect_version()
+        } else {
+            sub_db.put::(
+                progress_key,
+                &DbMetadataValue::Version(metadata_progress),
+            )?;
+            metadata_progress
+        },
+    )
+}
diff --git a/storage/aptosdb/src/pruner/state_kv_pruner.rs b/storage/aptosdb/src/pruner/state_kv_pruner.rs
index 460caf5db06e3..70a6f317effa6 100644
--- a/storage/aptosdb/src/pruner/state_kv_pruner.rs
+++ b/storage/aptosdb/src/pruner/state_kv_pruner.rs
@@ -4,11 +4,7 @@
 use crate::{
     db_metadata::DbMetadataSchema,
     metrics::PRUNER_VERSIONS,
-    pruner::{
-        db_pruner::DBPruner, db_sub_pruner::DBSubPruner,
-        state_store::state_value_pruner::StateValuePruner,
-    },
-    pruner_utils,
+    pruner::{db_pruner::DBPruner, state_store::state_value_pruner::StateValuePruner},
     schema::db_metadata::{DbMetadataKey, DbMetadataValue},
     state_kv_db::StateKvDb,
 };
@@ -24,8 +20,8 @@ pub(crate) struct StateKvPruner {
     state_kv_db: Arc,
     /// Keeps track of the target version that the pruner needs to achieve.
     target_version: AtomicVersion,
-    min_readable_version: AtomicVersion,
-    state_value_pruner: Arc,
+    progress: AtomicVersion,
+    state_value_pruner: Arc,
 }
 
 impl DBPruner for StateKvPruner {
@@ -35,25 +31,18 @@ impl DBPruner for StateKvPruner {
 
     fn prune(&self, max_versions: usize) -> Result {
         if !self.is_pruning_pending() {
-            return Ok(self.min_readable_version());
+            return Ok(self.progress());
         }
 
         let mut db_batch = SchemaBatch::new();
         let current_target_version = self.prune_inner(max_versions, &mut db_batch)?;
-        self.save_min_readable_version(current_target_version, &db_batch)?;
+        self.save_progress(current_target_version, &db_batch)?;
         self.state_kv_db.commit_raw_batch(db_batch)?;
         self.record_progress(current_target_version);
 
         Ok(current_target_version)
     }
 
-    fn save_min_readable_version(&self, version: Version, batch: &SchemaBatch) -> Result<()> {
-        batch.put::(
-            &DbMetadataKey::StateKvPrunerProgress,
-            &DbMetadataValue::Version(version),
-        )
-    }
-
     fn initialize_min_readable_version(&self) -> anyhow::Result {
         Ok(self
             .state_kv_db
@@ -62,8 +51,8 @@ impl DBPruner for StateKvPruner {
             .map_or(0, |v| v.expect_version()))
     }
 
-    fn min_readable_version(&self) -> Version {
-        self.min_readable_version.load(Ordering::Relaxed)
+    fn progress(&self) -> Version {
+        self.progress.load(Ordering::SeqCst)
     }
 
     fn set_target_version(&self, target_version: Version) {
@@ -78,8 +67,7 @@ impl DBPruner for StateKvPruner {
     }
 
     fn record_progress(&self, min_readable_version: Version) {
-        self.min_readable_version
-            .store(min_readable_version, Ordering::Relaxed);
+        self.progress.store(min_readable_version, Ordering::Relaxed);
         PRUNER_VERSIONS
             .with_label_values(&["state_kv_pruner", "progress"])
             .set(min_readable_version as i64);
@@ -91,43 +79,35 @@ impl StateKvPruner {
         let pruner = StateKvPruner {
             state_kv_db: Arc::clone(&state_kv_db),
             target_version: AtomicVersion::new(0),
-            min_readable_version: AtomicVersion::new(0),
+            progress: AtomicVersion::new(0),
             state_value_pruner: Arc::new(StateValuePruner::new(state_kv_db)),
         };
         pruner.initialize();
         pruner
     }
 
-    /// Prunes the genesis transaction and saves the db alterations to the given change set
-    pub fn prune_genesis(
-        state_kv_db: Arc,
-        db_batch: &mut SchemaBatch,
-    ) -> anyhow::Result<()> {
-        let target_version = 1; // The genesis version is 0. Delete [0,1) (exclusive)
-        let max_version = 1; // We should only be pruning a single version
-
-        let state_kv_pruner = pruner_utils::create_state_kv_pruner(state_kv_db);
-        state_kv_pruner.set_target_version(target_version);
-        state_kv_pruner.prune_inner(max_version, db_batch)?;
-
-        Ok(())
-    }
-
     fn prune_inner(
         &self,
         max_versions: usize,
         db_batch: &mut SchemaBatch,
     ) -> anyhow::Result {
-        let min_readable_version = self.min_readable_version();
+        let progress = self.progress();
 
         let current_target_version = self.get_current_batch_target(max_versions as Version);
-        if current_target_version < min_readable_version {
-            return Ok(min_readable_version);
+        if current_target_version < progress {
+            return Ok(progress);
         }
 
         self.state_value_pruner
-            .prune(db_batch, min_readable_version, current_target_version)?;
+            .prune(db_batch, progress, current_target_version)?;
 
         Ok(current_target_version)
     }
+
+    fn save_progress(&self, version: Version, batch: &SchemaBatch) -> Result<()> {
+        batch.put::(
+            &DbMetadataKey::StateKvPrunerProgress,
+            &DbMetadataValue::Version(version),
+        )
+    }
 }
diff --git a/storage/aptosdb/src/pruner/state_store/mod.rs b/storage/aptosdb/src/pruner/state_store/mod.rs
index 987e4f47a2d73..56c1c94526e6d 100644
--- a/storage/aptosdb/src/pruner/state_store/mod.rs
+++ b/storage/aptosdb/src/pruner/state_store/mod.rs
@@ -6,10 +6,9 @@ use crate::{
     jellyfish_merkle_node::JellyfishMerkleNodeSchema,
     metrics::PRUNER_VERSIONS,
     pruner::{db_pruner::DBPruner, state_store::generics::StaleNodeIndexSchemaTrait},
-    pruner_utils,
     schema::db_metadata::DbMetadataValue,
     state_merkle_db::StateMerkleDb,
-    StaleNodeIndexCrossEpochSchema, OTHER_TIMERS_SECONDS,
+    OTHER_TIMERS_SECONDS,
 };
 use anyhow::Result;
 use aptos_infallible::Mutex;
@@ -50,12 +49,12 @@ where
 
     fn prune(&self, batch_size: usize) -> Result {
         if !self.is_pruning_pending() {
-            return Ok(self.min_readable_version());
+            return Ok(self.progress());
         }
-        let min_readable_version = self.min_readable_version();
+        let progress = self.progress();
         let target_version = self.target_version();
 
-        match self.prune_state_merkle(min_readable_version, target_version, batch_size, None) {
+        match self.prune_state_merkle(progress, target_version, batch_size, None) {
             Ok(new_min_readable_version) => Ok(new_min_readable_version),
             Err(e) => {
                 error!(
@@ -68,14 +67,6 @@ where
         }
     }
 
-    fn save_min_readable_version(
-        &self,
-        version: Version,
-        batch: &SchemaBatch,
-    ) -> anyhow::Result<()> {
-        batch.put::(&S::tag(), &DbMetadataValue::Version(version))
-    }
-
     fn initialize_min_readable_version(&self) -> Result {
         Ok(self
             .state_merkle_db
@@ -84,7 +75,7 @@ where
             .map_or(0, |v| v.expect_version()))
     }
 
-    fn min_readable_version(&self) -> Version {
+    fn progress(&self) -> Version {
         let (version, _) = *self.progress.lock();
         version
     }
@@ -165,7 +156,7 @@ where
                     batch.delete::(&index)
                 })?;
 
-                self.save_min_readable_version(new_min_readable_version, &batch)?;
+                self.save_progress(new_min_readable_version, &batch)?;
 
                 // TODO(grao): Support sharding here.
                 self.state_merkle_db.metadata_db().write_schemas(batch)?;
@@ -222,31 +213,8 @@ where
         };
         Ok((indices, is_end_of_target_version))
     }
-}
 
-impl StateMerklePruner {
-    /// Prunes the genesis state and saves the db alterations to the given change set
-    pub fn prune_genesis(
-        state_merkle_db: Arc,
-        batch: &mut SchemaBatch,
-    ) -> Result<()> {
-        let target_version = 1; // The genesis version is 0. Delete [0,1) (exclusive)
-        let max_version = 1; // We should only be pruning a single version
-
-        let state_merkle_pruner = pruner_utils::create_state_merkle_pruner::<
-            StaleNodeIndexCrossEpochSchema,
-        >(state_merkle_db);
-        state_merkle_pruner.set_target_version(target_version);
-
-        let min_readable_version = state_merkle_pruner.min_readable_version();
-        let target_version = state_merkle_pruner.target_version();
-        state_merkle_pruner.prune_state_merkle(
-            min_readable_version,
-            target_version,
-            max_version,
-            Some(batch),
-        )?;
-
-        Ok(())
+    fn save_progress(&self, version: Version, batch: &SchemaBatch) -> anyhow::Result<()> {
+        batch.put::(&S::tag(), &DbMetadataValue::Version(version))
     }
 }
diff --git a/storage/aptosdb/src/pruner/state_store/state_value_pruner.rs b/storage/aptosdb/src/pruner/state_store/state_value_pruner.rs
index dc728788f6074..efdc2af2af4da 100644
--- a/storage/aptosdb/src/pruner/state_store/state_value_pruner.rs
+++ b/storage/aptosdb/src/pruner/state_store/state_value_pruner.rs
@@ -2,7 +2,6 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::{
-    pruner::db_sub_pruner::DBSubPruner,
     schema::{stale_state_value_index::StaleStateValueIndexSchema, state_value::StateValueSchema},
     state_kv_db::StateKvDb,
 };
@@ -13,8 +12,12 @@ pub struct StateValuePruner {
     state_kv_db: Arc,
 }
 
-impl DBSubPruner for StateValuePruner {
-    fn prune(
+impl StateValuePruner {
+    pub(in crate::pruner) fn new(state_kv_db: Arc) -> Self {
+        StateValuePruner { state_kv_db }
+    }
+
+    pub(in crate::pruner) fn prune(
         &self,
         db_batch: &mut SchemaBatch,
         min_readable_version: u64,
@@ -37,9 +40,3 @@ impl DBSubPruner for StateValuePruner {
         Ok(())
     }
 }
-
-impl StateValuePruner {
-    pub(in crate::pruner) fn new(state_kv_db: Arc) -> Self {
-        StateValuePruner { state_kv_db }
-    }
-}
diff --git a/storage/aptosdb/src/pruner/transaction_store/mod.rs b/storage/aptosdb/src/pruner/transaction_store/mod.rs
index e589ef0711b47..3b5d05337ce7a 100644
--- a/storage/aptosdb/src/pruner/transaction_store/mod.rs
+++ b/storage/aptosdb/src/pruner/transaction_store/mod.rs
@@ -3,5 +3,7 @@
 
 #[cfg(test)]
 mod test;
-pub(crate) mod transaction_store_pruner;
+pub(crate) mod transaction_accumulator_pruner;
+pub(crate) mod transaction_info_pruner;
+pub(crate) mod transaction_pruner;
 pub(crate) mod write_set_pruner;
diff --git a/storage/aptosdb/src/pruner/transaction_store/transaction_accumulator_pruner.rs b/storage/aptosdb/src/pruner/transaction_store/transaction_accumulator_pruner.rs
new file mode 100644
index 0000000000000..47769b16aaf0e
--- /dev/null
+++ b/storage/aptosdb/src/pruner/transaction_store/transaction_accumulator_pruner.rs
@@ -0,0 +1,59 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::{
+    pruner::{
+        db_sub_pruner::DBSubPruner, pruner_utils::get_or_initialize_ledger_subpruner_progress,
+    },
+    schema::db_metadata::{DbMetadataKey, DbMetadataSchema, DbMetadataValue},
+    TransactionStore,
+};
+use anyhow::Result;
+use aptos_schemadb::{SchemaBatch, DB};
+use aptos_types::transaction::Version;
+use std::sync::Arc;
+
+#[derive(Debug)]
+pub struct TransactionAccumulatorPruner {
+    transaction_store: Arc,
+    transaction_accumulator_db: Arc,
+}
+
+impl DBSubPruner for TransactionAccumulatorPruner {
+    fn prune(&self, current_progress: Version, target_version: Version) -> Result<()> {
+        let batch = SchemaBatch::new();
+        self.transaction_store.prune_transaction_accumulator(
+            current_progress,
+            target_version,
+            &batch,
+        )?;
+        batch.put::(
+            &DbMetadataKey::TransactionAccumulatorPrunerProgress,
+            &DbMetadataValue::Version(target_version),
+        )?;
+        self.transaction_accumulator_db.write_schemas(batch)
+    }
+}
+
+impl TransactionAccumulatorPruner {
+    pub(in crate::pruner) fn new(
+        transaction_store: Arc,
+        transaction_accumulator_db: Arc,
+        metadata_progress: Version,
+    ) -> Result {
+        let progress = get_or_initialize_ledger_subpruner_progress(
+            &transaction_accumulator_db,
+            &DbMetadataKey::TransactionAccumulatorPrunerProgress,
+            metadata_progress,
+        )?;
+
+        let myself = TransactionAccumulatorPruner {
+            transaction_store,
+            transaction_accumulator_db,
+        };
+
+        myself.prune(progress, metadata_progress)?;
+
+        Ok(myself)
+    }
+}
diff --git a/storage/aptosdb/src/pruner/transaction_store/transaction_info_pruner.rs b/storage/aptosdb/src/pruner/transaction_store/transaction_info_pruner.rs
new file mode 100644
index 0000000000000..4887f23e65209
--- /dev/null
+++ b/storage/aptosdb/src/pruner/transaction_store/transaction_info_pruner.rs
@@ -0,0 +1,59 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::{
+    pruner::{
+        db_sub_pruner::DBSubPruner, pruner_utils::get_or_initialize_ledger_subpruner_progress,
+    },
+    schema::db_metadata::{DbMetadataKey, DbMetadataSchema, DbMetadataValue},
+    TransactionStore,
+};
+use anyhow::Result;
+use aptos_schemadb::{SchemaBatch, DB};
+use aptos_types::transaction::Version;
+use std::sync::Arc;
+
+#[derive(Debug)]
+pub struct TransactionInfoPruner {
+    transaction_store: Arc,
+    transaction_info_db: Arc,
+}
+
+impl DBSubPruner for TransactionInfoPruner {
+    fn prune(&self, current_progress: Version, target_version: Version) -> Result<()> {
+        let batch = SchemaBatch::new();
+        self.transaction_store.prune_transaction_info_schema(
+            current_progress,
+            target_version,
+            &batch,
+        )?;
+        batch.put::(
+            &DbMetadataKey::TransactionInfoPrunerProgress,
+            &DbMetadataValue::Version(target_version),
+        )?;
+        self.transaction_info_db.write_schemas(batch)
+    }
+}
+
+impl TransactionInfoPruner {
+    pub(in crate::pruner) fn new(
+        transaction_store: Arc,
+        transaction_info_db: Arc,
+        metadata_progress: Version,
+    ) -> Result {
+        let progress = get_or_initialize_ledger_subpruner_progress(
+            &transaction_info_db,
+            &DbMetadataKey::TransactionInfoPrunerProgress,
+            metadata_progress,
+        )?;
+
+        let myself = TransactionInfoPruner {
+            transaction_store,
+            transaction_info_db,
+        };
+
+        myself.prune(progress, metadata_progress)?;
+
+        Ok(myself)
+    }
+}
diff --git a/storage/aptosdb/src/pruner/transaction_store/transaction_pruner.rs b/storage/aptosdb/src/pruner/transaction_store/transaction_pruner.rs
new file mode 100644
index 0000000000000..e5e8e21ebedf4
--- /dev/null
+++ b/storage/aptosdb/src/pruner/transaction_store/transaction_pruner.rs
@@ -0,0 +1,75 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::{
+    pruner::{
+        db_sub_pruner::DBSubPruner, pruner_utils::get_or_initialize_ledger_subpruner_progress,
+    },
+    schema::db_metadata::{DbMetadataKey, DbMetadataSchema, DbMetadataValue},
+    TransactionStore,
+};
+use anyhow::Result;
+use aptos_schemadb::{SchemaBatch, DB};
+use aptos_types::transaction::{Transaction, Version};
+use std::sync::Arc;
+
+#[derive(Debug)]
+pub struct TransactionPruner {
+    transaction_store: Arc,
+    transaction_db: Arc,
+}
+
+impl DBSubPruner for TransactionPruner {
+    fn prune(&self, current_progress: Version, target_version: Version) -> Result<()> {
+        let batch = SchemaBatch::new();
+        let candidate_transactions =
+            self.get_pruning_candidate_transactions(current_progress, target_version)?;
+        self.transaction_store
+            .prune_transaction_by_hash(&candidate_transactions, &batch)?;
+        self.transaction_store
+            .prune_transaction_by_account(&candidate_transactions, &batch)?;
+        self.transaction_store.prune_transaction_schema(
+            current_progress,
+            target_version,
+            &batch,
+        )?;
+        batch.put::(
+            &DbMetadataKey::TransactionPrunerProgress,
+            &DbMetadataValue::Version(target_version),
+        )?;
+        self.transaction_db.write_schemas(batch)
+    }
+}
+
+impl TransactionPruner {
+    pub(in crate::pruner) fn new(
+        transaction_store: Arc,
+        transaction_db: Arc,
+        metadata_progress: Version,
+    ) -> Result {
+        let progress = get_or_initialize_ledger_subpruner_progress(
+            &transaction_db,
+            &DbMetadataKey::TransactionPrunerProgress,
+            metadata_progress,
+        )?;
+
+        let myself = TransactionPruner {
+            transaction_store,
+            transaction_db,
+        };
+
+        myself.prune(progress, metadata_progress)?;
+
+        Ok(myself)
+    }
+
+    fn get_pruning_candidate_transactions(
+        &self,
+        start: Version,
+        end: Version,
+    ) -> anyhow::Result> {
+        self.transaction_store
+            .get_transaction_iter(start, (end - start) as usize)?
+            .collect()
+    }
+}
diff --git a/storage/aptosdb/src/pruner/transaction_store/transaction_store_pruner.rs b/storage/aptosdb/src/pruner/transaction_store/transaction_store_pruner.rs
deleted file mode 100644
index 68a151be260f8..0000000000000
--- a/storage/aptosdb/src/pruner/transaction_store/transaction_store_pruner.rs
+++ /dev/null
@@ -1,62 +0,0 @@
-// Copyright © Aptos Foundation
-// SPDX-License-Identifier: Apache-2.0
-use crate::{pruner::db_sub_pruner::DBSubPruner, TransactionStore};
-use aptos_schemadb::SchemaBatch;
-use aptos_types::transaction::{Transaction, Version};
-use std::sync::Arc;
-
-#[derive(Debug)]
-pub struct TransactionStorePruner {
-    transaction_store: Arc,
-}
-
-impl DBSubPruner for TransactionStorePruner {
-    fn prune(
-        &self,
-        db_batch: &mut SchemaBatch,
-        min_readable_version: u64,
-        target_version: u64,
-    ) -> anyhow::Result<()> {
-        // Current target version  might be less than the target version to ensure we don't prune
-        // more than max_version in one go.
-
-        let candidate_transactions =
-            self.get_pruning_candidate_transactions(min_readable_version, target_version)?;
-        self.transaction_store
-            .prune_transaction_by_hash(&candidate_transactions, db_batch)?;
-        self.transaction_store
-            .prune_transaction_by_account(&candidate_transactions, db_batch)?;
-        self.transaction_store.prune_transaction_schema(
-            min_readable_version,
-            target_version,
-            db_batch,
-        )?;
-        self.transaction_store.prune_transaction_info_schema(
-            min_readable_version,
-            target_version,
-            db_batch,
-        )?;
-        self.transaction_store.prune_transaction_accumulator(
-            min_readable_version,
-            target_version,
-            db_batch,
-        )?;
-        Ok(())
-    }
-}
-
-impl TransactionStorePruner {
-    pub(in crate::pruner) fn new(transaction_store: Arc) -> Self {
-        TransactionStorePruner { transaction_store }
-    }
-
-    fn get_pruning_candidate_transactions(
-        &self,
-        start: Version,
-        end: Version,
-    ) -> anyhow::Result> {
-        self.transaction_store
-            .get_transaction_iter(start, (end - start) as usize)?
-            .collect()
-    }
-}
diff --git a/storage/aptosdb/src/pruner/transaction_store/write_set_pruner.rs b/storage/aptosdb/src/pruner/transaction_store/write_set_pruner.rs
index 53f63bd11b92f..dab713b98aa0f 100644
--- a/storage/aptosdb/src/pruner/transaction_store/write_set_pruner.rs
+++ b/storage/aptosdb/src/pruner/transaction_store/write_set_pruner.rs
@@ -1,29 +1,56 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
-use crate::{pruner::db_sub_pruner::DBSubPruner, TransactionStore};
-use aptos_schemadb::SchemaBatch;
+
+use crate::{
+    pruner::{
+        db_sub_pruner::DBSubPruner, pruner_utils::get_or_initialize_ledger_subpruner_progress,
+    },
+    schema::db_metadata::{DbMetadataKey, DbMetadataSchema, DbMetadataValue},
+    TransactionStore,
+};
+use anyhow::Result;
+use aptos_schemadb::{SchemaBatch, DB};
+use aptos_types::transaction::Version;
 use std::sync::Arc;
 
 #[derive(Debug)]
 pub struct WriteSetPruner {
     transaction_store: Arc,
+    write_set_db: Arc,
 }
 
 impl DBSubPruner for WriteSetPruner {
-    fn prune(
-        &self,
-        db_batch: &mut SchemaBatch,
-        min_readable_version: u64,
-        target_version: u64,
-    ) -> anyhow::Result<()> {
+    fn prune(&self, current_progress: Version, target_version: Version) -> Result<()> {
+        let batch = SchemaBatch::new();
         self.transaction_store
-            .prune_write_set(min_readable_version, target_version, db_batch)?;
-        Ok(())
+            .prune_write_set(current_progress, target_version, &batch)?;
+        batch.put::(
+            &DbMetadataKey::WriteSetPrunerProgress,
+            &DbMetadataValue::Version(target_version),
+        )?;
+        self.write_set_db.write_schemas(batch)
     }
 }
 
 impl WriteSetPruner {
-    pub(in crate::pruner) fn new(transaction_store: Arc) -> Self {
-        WriteSetPruner { transaction_store }
+    pub(in crate::pruner) fn new(
+        transaction_store: Arc,
+        write_set_db: Arc,
+        metadata_progress: Version,
+    ) -> Result {
+        let progress = get_or_initialize_ledger_subpruner_progress(
+            &write_set_db,
+            &DbMetadataKey::WriteSetPrunerProgress,
+            metadata_progress,
+        )?;
+
+        let myself = WriteSetPruner {
+            transaction_store,
+            write_set_db,
+        };
+
+        myself.prune(progress, metadata_progress)?;
+
+        Ok(myself)
     }
 }
diff --git a/storage/aptosdb/src/schema/db_metadata/mod.rs b/storage/aptosdb/src/schema/db_metadata/mod.rs
index fc5dbb137fbaa..61958912d39bd 100644
--- a/storage/aptosdb/src/schema/db_metadata/mod.rs
+++ b/storage/aptosdb/src/schema/db_metadata/mod.rs
@@ -57,6 +57,11 @@ pub enum DbMetadataKey {
     StateKvShardCommitProgress(ShardId),
     StateMerkleCommitProgress,
     StateMerkleShardCommitProgress(ShardId),
+    EventPrunerProgress,
+    TransactionAccumulatorPrunerProgress,
+    TransactionInfoPrunerProgress,
+    TransactionPrunerProgress,
+    WriteSetPrunerProgress,
 }
 
 define_schema!(
diff --git a/storage/aptosdb/src/state_kv_db.rs b/storage/aptosdb/src/state_kv_db.rs
index 3022957baaa0f..fb20066ee267b 100644
--- a/storage/aptosdb/src/state_kv_db.rs
+++ b/storage/aptosdb/src/state_kv_db.rs
@@ -95,20 +95,6 @@ impl StateKvDb {
         Ok(state_kv_db)
     }
 
-    // TODO(grao): Remove this function.
-    pub(crate) fn commit_nonsharded(
-        &self,
-        version: Version,
-        state_kv_batch: SchemaBatch,
-    ) -> Result<()> {
-        state_kv_batch.put::(
-            &DbMetadataKey::StateKvCommitProgress,
-            &DbMetadataValue::Version(version),
-        )?;
-
-        self.commit_raw_batch(state_kv_batch)
-    }
-
     pub(crate) fn commit(
         &self,
         version: Version,

From ffddc82f9570083c91bb17c19a6ac31741a020f9 Mon Sep 17 00:00:00 2001
From: Rustie Lin 
Date: Thu, 8 Jun 2023 21:20:55 -0700
Subject: [PATCH 122/200] [forge] add PFN support (#8531)

---
 Cargo.lock                                    |   3 +-
 Cargo.toml                                    |  25 +-
 aptos-node/Cargo.toml                         |   1 -
 aptos-node/src/lib.rs                         |  17 +-
 config/Cargo.toml                             |   1 +
 config/src/config/node_config.rs              |  46 +-
 .../helm/aptos-node/templates/validator.yaml  |   4 -
 testsuite/forge-test-runner-template.yaml     |   2 +-
 testsuite/forge.py                            |   8 +-
 testsuite/forge/Cargo.toml                    |  13 +-
 .../forge/src/backend/k8s/cluster_helper.rs   |  53 +-
 testsuite/forge/src/backend/k8s/constants.rs  |   5 +
 testsuite/forge/src/backend/k8s/fullnode.rs   | 747 ++++++++++++++++++
 testsuite/forge/src/backend/k8s/kube_api.rs   | 317 +++++++-
 testsuite/forge/src/backend/k8s/mod.rs        |  16 +-
 testsuite/forge/src/backend/k8s/prometheus.rs |  33 +-
 .../forge/src/backend/k8s/stateful_set.rs     | 102 +--
 testsuite/forge/src/backend/k8s/swarm.rs      |  84 +-
 testsuite/forge/src/backend/local/swarm.rs    |   6 +-
 testsuite/forge/src/interface/node.rs         |  13 +-
 testsuite/forge/src/interface/swarm.rs        |   4 +-
 testsuite/smoke-test/src/full_nodes.rs        |   5 +-
 testsuite/smoke-test/src/fullnode.rs          |   1 +
 testsuite/smoke-test/src/network.rs           |   7 +-
 testsuite/testcases/src/forge_setup_test.rs   |  24 +-
 25 files changed, 1326 insertions(+), 211 deletions(-)
 create mode 100644 testsuite/forge/src/backend/k8s/fullnode.rs

diff --git a/Cargo.lock b/Cargo.lock
index 658dd89aed005..455ab65f742d9 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -578,6 +578,7 @@ dependencies = [
  "poem-openapi",
  "rand 0.7.3",
  "serde 1.0.149",
+ "serde_merge",
  "serde_yaml 0.8.26",
  "thiserror",
  "url",
@@ -1245,6 +1246,7 @@ dependencies = [
  "aptos-retrier",
  "aptos-sdk",
  "aptos-secure-storage",
+ "aptos-short-hex-str",
  "aptos-state-sync-driver",
  "aptos-transaction-emitter-lib",
  "aptos-transaction-generator-lib",
@@ -2323,7 +2325,6 @@ dependencies = [
  "rayon",
  "serde 1.0.149",
  "serde_json",
- "serde_merge",
  "serde_yaml 0.8.26",
  "tokio",
  "tokio-stream",
diff --git a/Cargo.toml b/Cargo.toml
index 1b74aedbf767c..f297ab54bd82f 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -96,7 +96,7 @@ members = [
     "ecosystem/indexer-grpc/indexer-grpc-integration-tests",
     "ecosystem/indexer-grpc/indexer-grpc-parser",
     "ecosystem/indexer-grpc/indexer-grpc-post-processor",
-     "ecosystem/indexer-grpc/indexer-grpc-server-framework",
+    "ecosystem/indexer-grpc/indexer-grpc-server-framework",
     "ecosystem/indexer-grpc/indexer-grpc-utils",
     "ecosystem/node-checker",
     "ecosystem/node-checker/fn-check-client",
@@ -430,7 +430,13 @@ dashmap = "5.2.0"
 datatest-stable = "0.1.1"
 debug-ignore = { version = "1.0.3", features = ["serde"] }
 derivative = "2.2.0"
-diesel = { version = "2.1.0", features = ["chrono", "postgres", "r2d2", "numeric", "serde_json"] }
+diesel = { version = "2.1.0", features = [
+    "chrono",
+    "postgres",
+    "r2d2",
+    "numeric",
+    "serde_json",
+] }
 diesel_migrations = { version = "2.1.0", features = ["postgres"] }
 digest = "0.9.0"
 dir-diff = "0.3.2"
@@ -523,7 +529,12 @@ rayon = "1.5.2"
 redis = { version = "0.22.3", features = ["tokio-comp", "script"] }
 redis-test = { version = "0.1.1", features = ["aio"] }
 regex = "1.5.5"
-reqwest = { version = "0.11.11", features = ["blocking", "cookies", "json", "stream"] }
+reqwest = { version = "0.11.11", features = [
+    "blocking",
+    "cookies",
+    "json",
+    "stream",
+] }
 reqwest-middleware = "0.2.0"
 reqwest-retry = "0.2.1"
 ring = { version = "0.16.20", features = ["std"] }
@@ -619,9 +630,13 @@ move-resource-viewer = { path = "third_party/move/tools/move-resource-viewer" }
 move-symbol-pool = { path = "third_party/move/move-symbol-pool" }
 move-table-extension = { path = "third_party/move/extensions/move-table-extension" }
 move-transactional-test-runner = { path = "third_party/move/testing-infra/transactional-test-runner" }
-move-unit-test = { path = "third_party/move/tools/move-unit-test", features = ["table-extension"] }
+move-unit-test = { path = "third_party/move/tools/move-unit-test", features = [
+    "table-extension",
+] }
 move-vm-runtime = { path = "third_party/move/move-vm/runtime" }
-move-vm-test-utils = { path = "third_party/move/move-vm/test-utils", features = ["table-extension"] }
+move-vm-test-utils = { path = "third_party/move/move-vm/test-utils", features = [
+    "table-extension",
+] }
 move-vm-types = { path = "third_party/move/move-vm/types" }
 
 [profile.release]
diff --git a/aptos-node/Cargo.toml b/aptos-node/Cargo.toml
index 3700ba1d82de0..d951d471de065 100644
--- a/aptos-node/Cargo.toml
+++ b/aptos-node/Cargo.toml
@@ -68,7 +68,6 @@ rand = { workspace = true }
 rayon = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
-serde_merge = { workspace = true }
 serde_yaml = { workspace = true }
 tokio = { workspace = true }
 tokio-stream = { workspace = true }
diff --git a/aptos-node/src/lib.rs b/aptos-node/src/lib.rs
index 6f0be3b864787..c74bc4dfda6ab 100644
--- a/aptos-node/src/lib.rs
+++ b/aptos-node/src/lib.rs
@@ -18,7 +18,7 @@ mod tests;
 use anyhow::anyhow;
 use aptos_api::bootstrap as bootstrap_api;
 use aptos_build_info::build_information;
-use aptos_config::config::{NodeConfig, PersistableConfig};
+use aptos_config::config::{merge_node_config, NodeConfig, PersistableConfig};
 use aptos_framework::ReleaseBundle;
 use aptos_logger::{prelude::*, telemetry_log_writer::TelemetryLog, Level, LoggerFilterUpdater};
 use aptos_state_sync_driver::driver_factory::StateSyncRuntimes;
@@ -328,19 +328,6 @@ where
     start(config, Some(log_file), false)
 }
 
-/// Merges node_config with the config override file
-fn merge_test_config_override(
-    node_config: NodeConfig,
-    test_config_override: serde_yaml::Value,
-) -> NodeConfig {
-    serde_merge::tmerge::(
-        node_config,
-        test_config_override,
-    )
-    .map_err(|e| anyhow::anyhow!("Unable to merge default config with override. Error: {}", e))
-    .unwrap()
-}
-
 /// Creates a single node test config, with a few config tweaks to reduce
 /// the overhead of running the node on a local machine.
 fn create_single_node_test_config(
@@ -368,7 +355,7 @@ fn create_single_node_test_config(
                     e
                 )
             })?;
-            merge_test_config_override(NodeConfig::get_default_validator_config(), values)
+            merge_node_config(NodeConfig::get_default_validator_config(), values)?
         },
         None => NodeConfig::get_default_validator_config(),
     };
diff --git a/config/Cargo.toml b/config/Cargo.toml
index d6767b7a19b07..7d22af1d2aa20 100644
--- a/config/Cargo.toml
+++ b/config/Cargo.toml
@@ -31,6 +31,7 @@ mirai-annotations = { workspace = true }
 poem-openapi = { workspace = true }
 rand = { workspace = true }
 serde = { workspace = true }
+serde_merge = { workspace = true }
 serde_yaml = { workspace = true }
 thiserror = { workspace = true }
 url = { workspace = true }
diff --git a/config/src/config/node_config.rs b/config/src/config/node_config.rs
index c9affc2d8d820..ebf1aba8e2ad5 100644
--- a/config/src/config/node_config.rs
+++ b/config/src/config/node_config.rs
@@ -228,9 +228,25 @@ fn parse_serialized_node_config(serialized_config: &str, caller: &'static str) -
     })
 }
 
+/// Merges node_config with a config config override
+pub fn merge_node_config(
+    node_config: NodeConfig,
+    override_node_config: serde_yaml::Value,
+) -> Result {
+    serde_merge::tmerge::(
+        node_config,
+        override_node_config,
+    )
+    .map_err(|e| {
+        Error::Unexpected(format!(
+            "Unable to merge default config with override. Error: {}",
+            e
+        ))
+    })
+}
 #[cfg(test)]
 mod test {
-    use crate::config::{NodeConfig, SafetyRulesConfig};
+    use crate::config::{merge_node_config, Error, NodeConfig, SafetyRulesConfig};
 
     #[test]
     fn verify_config_defaults() {
@@ -242,4 +258,32 @@ mod test {
         // Verify the safety rules config default
         SafetyRulesConfig::get_default_config();
     }
+
+    #[test]
+    fn verify_merge_node_config() {
+        let node_config = NodeConfig::get_default_pfn_config();
+        let override_node_config = serde_yaml::from_str(
+            r#"
+            api:
+                enabled: false
+            "#,
+        )
+        .unwrap();
+        let merged_node_config = merge_node_config(node_config, override_node_config).unwrap();
+        assert!(!merged_node_config.api.enabled);
+    }
+
+    #[test]
+    fn verify_bad_merge_node_config() {
+        let node_config = NodeConfig::get_default_pfn_config();
+        let override_node_config = serde_yaml::from_str(
+            r#"
+            blablafakenodeconfigkeyblabla:
+                enabled: false
+            "#,
+        )
+        .unwrap();
+        let merged_node_config = merge_node_config(node_config, override_node_config);
+        assert!(matches!(merged_node_config, Err(Error::Unexpected(_))));
+    }
 }
diff --git a/terraform/helm/aptos-node/templates/validator.yaml b/terraform/helm/aptos-node/templates/validator.yaml
index 77dff71d9a79e..9b6514e81c46f 100644
--- a/terraform/helm/aptos-node/templates/validator.yaml
+++ b/terraform/helm/aptos-node/templates/validator.yaml
@@ -105,10 +105,6 @@ spec:
           valueFrom:
             fieldRef:
               fieldPath: metadata.namespace
-        - name: KUBERNETES_POD_NAME
-          valueFrom:
-            fieldRef:
-              fieldPath: metadata.name
         - name: RUST_BACKTRACE
           value: "0"
       {{- end }}
diff --git a/testsuite/forge-test-runner-template.yaml b/testsuite/forge-test-runner-template.yaml
index 4bbdaa2c682f9..373bdad43557b 100644
--- a/testsuite/forge-test-runner-template.yaml
+++ b/testsuite/forge-test-runner-template.yaml
@@ -11,7 +11,7 @@ spec:
   serviceAccountName: forge
   containers:
   - name: main
-    image: {FORGE_IMAGE_REPO}:{FORGE_IMAGE_TAG}
+    image: {FORGE_IMAGE}
     imagePullPolicy: Always
     command:
     - /bin/bash
diff --git a/testsuite/forge.py b/testsuite/forge.py
index fccc4a101386a..0fd7f96fa66ff 100644
--- a/testsuite/forge.py
+++ b/testsuite/forge.py
@@ -676,14 +676,12 @@ def run(self, context: ForgeContext) -> ForgeResult:
 
         # determine the interal image repos based on the context of where the cluster is located
         if context.cloud == Cloud.AWS:
-            forge_image_repo = f"{context.aws_account_num}.dkr.ecr.{context.aws_region}.amazonaws.com/aptos/forge"
+            forge_image_full = f"{context.aws_account_num}.dkr.ecr.{context.aws_region}.amazonaws.com/aptos/forge:{context.forge_image_tag}"
             validator_node_selector = "eks.amazonaws.com/nodegroup: validators"
         elif (
             context.cloud == Cloud.GCP
         ):  # the GCP project for images is separate than the cluster
-            forge_image_repo = (
-                f"us-west1-docker.pkg.dev/aptos-global/aptos-internal/forge"
-            )
+            forge_image_full = f"us-west1-docker.pkg.dev/aptos-global/aptos-internal/forge:{context.forge_image_tag}"
             validator_node_selector = ""  # no selector
             # TODO: also no NAP node selector yet
             # TODO: also registries need to be set up such that the default compute service account can access it:  $PROJECT_ID-compute@developer.gserviceaccount.com
@@ -695,7 +693,7 @@ def run(self, context: ForgeContext) -> ForgeResult:
             FORGE_IMAGE_TAG=context.forge_image_tag,
             IMAGE_TAG=context.image_tag,
             UPGRADE_IMAGE_TAG=context.upgrade_image_tag,
-            FORGE_IMAGE_REPO=forge_image_repo,
+            FORGE_IMAGE=forge_image_full,
             FORGE_NAMESPACE=context.forge_namespace,
             FORGE_ARGS=" ".join(context.forge_args),
             FORGE_TRIGGERED_BY=forge_triggered_by,
diff --git a/testsuite/forge/Cargo.toml b/testsuite/forge/Cargo.toml
index 1d25cafdcce8e..a19789c5b50de 100644
--- a/testsuite/forge/Cargo.toml
+++ b/testsuite/forge/Cargo.toml
@@ -29,6 +29,7 @@ aptos-rest-client = { workspace = true }
 aptos-retrier = { workspace = true }
 aptos-sdk = { workspace = true }
 aptos-secure-storage = { workspace = true }
+aptos-short-hex-str = { workspace = true }
 aptos-state-sync-driver = { workspace = true }
 aptos-transaction-emitter-lib = { workspace = true }
 aptos-transaction-generator-lib = { workspace = true }
@@ -41,8 +42,14 @@ hyper = { workspace = true }
 hyper-tls = { workspace = true }
 itertools = { workspace = true }
 json-patch = { workspace = true }
-k8s-openapi = { version = "0.13.1", default-features = false, features = ["v1_22"] }
-kube = { version = "0.65.0", default-features = false, features = ["jsonpatch", "client", "rustls-tls"] }
+k8s-openapi = { version = "0.13.1", default-features = false, features = [
+    "v1_22",
+] }
+kube = { version = "0.65.0", default-features = false, features = [
+    "jsonpatch",
+    "client",
+    "rustls-tls",
+] }
 num_cpus = { workspace = true }
 once_cell = { workspace = true }
 prometheus-http-query = { workspace = true }
@@ -50,7 +57,7 @@ rand = { workspace = true }
 rayon = { workspace = true }
 regex = { workspace = true }
 reqwest = { workspace = true }
-serde ={ workspace = true }
+serde = { workspace = true }
 serde_json = { workspace = true }
 serde_yaml = { workspace = true }
 structopt = { workspace = true }
diff --git a/testsuite/forge/src/backend/k8s/cluster_helper.rs b/testsuite/forge/src/backend/k8s/cluster_helper.rs
index 0ade62e0b393d..f101a9e0cf391 100644
--- a/testsuite/forge/src/backend/k8s/cluster_helper.rs
+++ b/testsuite/forge/src/backend/k8s/cluster_helper.rs
@@ -4,8 +4,8 @@
 
 use crate::{
     get_fullnodes, get_validators, k8s_wait_genesis_strategy, k8s_wait_nodes_strategy,
-    nodes_healthcheck, wait_stateful_set, Create, ForgeRunnerMode, GenesisConfigFn, K8sApi,
-    K8sNode, NodeConfigFn, Result, APTOS_NODE_HELM_CHART_PATH, APTOS_NODE_HELM_RELEASE_NAME,
+    nodes_healthcheck, wait_stateful_set, ForgeRunnerMode, GenesisConfigFn, K8sApi, K8sNode,
+    NodeConfigFn, ReadWrite, Result, APTOS_NODE_HELM_CHART_PATH, APTOS_NODE_HELM_RELEASE_NAME,
     DEFAULT_ROOT_KEY, FORGE_KEY_SEED, FULLNODE_HAPROXY_SERVICE_SUFFIX, FULLNODE_SERVICE_SUFFIX,
     GENESIS_HELM_CHART_PATH, GENESIS_HELM_RELEASE_NAME, HELM_BIN, KUBECTL_BIN,
     MANAGEMENT_CONFIGMAP_PREFIX, NAMESPACE_CLEANUP_THRESHOLD_SECS, POD_CLEANUP_THRESHOLD_SECS,
@@ -145,10 +145,8 @@ async fn wait_nodes_stateful_set(
 ) -> Result<()> {
     // wait for all nodes healthy
     for node in nodes.values() {
-        // retry exponentially until 1 min, then every 1 min until ~22 min
-        let retry_policy = RetryPolicy::exponential(Duration::from_secs(5))
-            .with_max_retries(25)
-            .with_max_delay(Duration::from_secs(60));
+        // retry every 10 seconds for 20 minutes
+        let retry_policy = RetryPolicy::fixed(Duration::from_secs(10)).with_max_retries(120);
         wait_stateful_set(
             kube_client,
             kube_namespace,
@@ -197,6 +195,9 @@ pub(crate) async fn delete_k8s_resources(client: K8sClient, kube_namespace: &str
     let testnet_addons_helm_selector = "app.kubernetes.io/part-of=testnet-addons";
     let genesis_helm_selector = "app.kubernetes.io/part-of=aptos-genesis";
 
+    // selector for manually created resources from Forge
+    let forge_pfn_selector = "app.kubernetes.io/part-of=forge-pfn";
+
     // delete all deployments and statefulsets
     // cross this with all the compute resources created by aptos-node helm chart
     let deployments: Api = Api::namespaced(client.clone(), kube_namespace);
@@ -210,6 +211,7 @@ pub(crate) async fn delete_k8s_resources(client: K8sClient, kube_namespace: &str
         aptos_node_helm_selector,
         testnet_addons_helm_selector,
         genesis_helm_selector,
+        forge_pfn_selector,
     ] {
         info!("Deleting k8s resources with selector: {}", selector);
         delete_k8s_collection(deployments.clone(), "Deployments", selector).await?;
@@ -497,6 +499,8 @@ pub async fn check_persistent_volumes(
     Ok(())
 }
 
+/// Installs a testnet in a k8s namespace by first running genesis, and the installing the aptos-nodes via helm
+/// Returns the current era, as well as a mapping of validators and fullnodes
 pub async fn install_testnet_resources(
     kube_namespace: String,
     num_validators: usize,
@@ -508,7 +512,7 @@ pub async fn install_testnet_resources(
     enable_haproxy: bool,
     genesis_helm_config_fn: Option,
     node_helm_config_fn: Option,
-) -> Result<(HashMap, HashMap)> {
+) -> Result<(String, HashMap, HashMap)> {
     let kube_client = create_k8s_client().await?;
 
     // get deployment-specific helm values and cache it
@@ -597,7 +601,7 @@ pub async fn install_testnet_resources(
     )
     .await?;
 
-    Ok((validators, fullnodes))
+    Ok((new_era.clone(), validators, fullnodes))
 }
 
 pub fn construct_node_helm_values(
@@ -797,7 +801,7 @@ enum ApiError {
 }
 
 async fn create_namespace(
-    namespace_api: Arc>,
+    namespace_api: Arc>,
     kube_namespace: String,
 ) -> Result<(), ApiError> {
     let kube_namespace_name = kube_namespace.clone();
@@ -1032,36 +1036,7 @@ pub fn make_k8s_label(value: String) -> String {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use async_trait::async_trait;
-    use hyper::http::StatusCode;
-    use kube::error::ErrorResponse;
-
-    struct FailedNamespacesApi {
-        status_code: u16,
-    }
-
-    impl FailedNamespacesApi {
-        fn from_status_code(status_code: u16) -> Self {
-            FailedNamespacesApi { status_code }
-        }
-    }
-
-    #[async_trait]
-    impl Create for FailedNamespacesApi {
-        async fn create(
-            &self,
-            _pp: &PostParams,
-            _namespace: &Namespace,
-        ) -> Result {
-            let status = StatusCode::from_u16(self.status_code).unwrap();
-            Err(KubeError::Api(ErrorResponse {
-                status: status.to_string(),
-                code: status.as_u16(),
-                message: "Failed to create namespace".to_string(),
-                reason: "Failed to parse error data".into(),
-            }))
-        }
-    }
+    use crate::FailedNamespacesApi;
 
     #[tokio::test]
     async fn test_create_namespace_final_error() {
diff --git a/testsuite/forge/src/backend/k8s/constants.rs b/testsuite/forge/src/backend/k8s/constants.rs
index 8781d928bf5da..086ad561d622f 100644
--- a/testsuite/forge/src/backend/k8s/constants.rs
+++ b/testsuite/forge/src/backend/k8s/constants.rs
@@ -43,3 +43,8 @@ pub const FULLNODE_SERVICE_SUFFIX: &str = "fullnode";
 pub const VALIDATOR_HAPROXY_SERVICE_SUFFIX: &str = "validator-lb";
 pub const FULLNODE_HAPROXY_SERVICE_SUFFIX: &str = "fullnode-lb";
 pub const HAPROXY_SERVICE_SUFFIX: &str = "lb";
+
+// kubernetes resource names for validator 0, which may be used for templating
+pub const VALIDATOR_0_STATEFUL_SET_NAME: &str = "aptos-node-0-validator";
+pub const VALIDATOR_0_GENESIS_SECRET_PREFIX: &str = "aptos-node-0-genesis";
+pub const VALIDATOR_0_DATA_PERSISTENT_VOLUME_CLAIM_PREFIX: &str = "aptos-node-0-validator";
diff --git a/testsuite/forge/src/backend/k8s/fullnode.rs b/testsuite/forge/src/backend/k8s/fullnode.rs
new file mode 100644
index 0000000000000..32dc566bce4b9
--- /dev/null
+++ b/testsuite/forge/src/backend/k8s/fullnode.rs
@@ -0,0 +1,747 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::{
+    get_stateful_set_image, K8sNode, ReadWrite, Result, Version, REST_API_SERVICE_PORT,
+    VALIDATOR_0_DATA_PERSISTENT_VOLUME_CLAIM_PREFIX, VALIDATOR_0_GENESIS_SECRET_PREFIX,
+    VALIDATOR_0_STATEFUL_SET_NAME,
+};
+use anyhow::Context;
+use aptos_config::{
+    config::{
+        merge_node_config, ApiConfig, BaseConfig, DiscoveryMethod, ExecutionConfig, NetworkConfig,
+        NodeConfig, RoleType, WaypointConfig,
+    },
+    network_id::NetworkId,
+};
+use aptos_logger::info;
+use aptos_sdk::types::PeerId;
+use aptos_short_hex_str::AsShortHexStr;
+use k8s_openapi::{
+    api::{
+        apps::v1::{StatefulSet, StatefulSetSpec},
+        core::v1::{
+            ConfigMap, ConfigMapVolumeSource, Container, PersistentVolumeClaim,
+            PersistentVolumeClaimSpec, PodSpec, PodTemplateSpec, ResourceRequirements,
+            SecretVolumeSource, Service, ServicePort, ServiceSpec, Volume, VolumeMount,
+        },
+    },
+    apimachinery::pkg::apis::meta::v1::LabelSelector,
+};
+use kube::api::{ObjectMeta, PostParams};
+use std::{
+    collections::BTreeMap,
+    net::{Ipv4Addr, SocketAddr, SocketAddrV4},
+    path::PathBuf,
+    sync::Arc,
+};
+use tempfile::TempDir;
+
+// these are constants given by the aptos-node helm chart
+// see terraform/helm/aptos-node/templates/validator.yaml
+
+// the name of the NodeConfig for the PFN, as well as the key in the k8s ConfigMap
+// where the NodeConfig is stored
+const FULLNODE_CONFIG_MAP_KEY: &str = "fullnode.yaml";
+
+// the path where the genesis is mounted in the validator
+const GENESIS_CONFIG_VOLUME_NAME: &str = "genesis-config";
+const GENESIS_CONFIG_VOLUME_PATH: &str = "/opt/aptos/genesis";
+
+// the path where the config file is mounted in the fullnode
+const APTOS_CONFIG_VOLUME_NAME: &str = "aptos-config";
+const APTOS_CONFIG_VOLUME_PATH: &str = "/opt/aptos/etc";
+
+// the path where the data volume is mounted in the fullnode
+const APTOS_DATA_VOLUME_NAME: &str = "aptos-data";
+const APTOS_DATA_VOLUME_PATH: &str = "/opt/aptos/data";
+
+/// Derive the fullnode image from the validator image. They will share the same image repo (validator), but not necessarily the version (image tag)
+fn get_fullnode_image_from_validator_image(
+    validator_stateful_set: &StatefulSet,
+    version: &Version,
+) -> Result {
+    let fullnode_kube_image = get_stateful_set_image(validator_stateful_set)?;
+    let fullnode_image_repo = fullnode_kube_image.name;
+
+    // fullnode uses the validator image, with a different image tag
+    Ok(format!("{}:{}", fullnode_image_repo, version))
+}
+
+/// Create a ConfigMap with the given NodeConfig, with a constant key
+async fn create_node_config_configmap(
+    node_config_config_map_name: String,
+    node_config: &NodeConfig,
+) -> Result {
+    let mut data: BTreeMap = BTreeMap::new();
+    data.insert(
+        FULLNODE_CONFIG_MAP_KEY.to_string(),
+        serde_yaml::to_string(&node_config)?,
+    );
+    let node_config_config_map = ConfigMap {
+        binary_data: None,
+        data: Some(data.clone()),
+        metadata: ObjectMeta {
+            name: Some(node_config_config_map_name),
+            ..ObjectMeta::default()
+        },
+        immutable: None,
+    };
+    Ok(node_config_config_map)
+}
+
+/// Create a PFN data volume by using the validator data volume as a template
+fn create_fullnode_persistent_volume_claim(
+    validator_data_volume: PersistentVolumeClaim,
+) -> Result {
+    let volume_requests = validator_data_volume
+        .spec
+        .as_ref()
+        .expect("Could not get volume spec from validator data volume")
+        .resources
+        .as_ref()
+        .expect("Could not get volume resources from validator data volume")
+        .requests
+        .clone();
+
+    Ok(PersistentVolumeClaim {
+        metadata: ObjectMeta {
+            name: Some(APTOS_DATA_VOLUME_NAME.to_string()),
+            ..ObjectMeta::default()
+        },
+        spec: Some(PersistentVolumeClaimSpec {
+            access_modes: Some(vec!["ReadWriteOnce".to_string()]),
+            resources: Some(ResourceRequirements {
+                requests: volume_requests,
+                ..ResourceRequirements::default()
+            }),
+            ..PersistentVolumeClaimSpec::default()
+        }),
+        ..PersistentVolumeClaim::default()
+    })
+}
+
+fn create_fullnode_labels(fullnode_name: String) -> BTreeMap {
+    [
+        ("app.kubernetes.io/name".to_string(), "fullnode".to_string()),
+        ("app.kubernetes.io/instance".to_string(), fullnode_name),
+        (
+            "app.kubernetes.io/part-of".to_string(),
+            "forge-pfn".to_string(),
+        ),
+    ]
+    .iter()
+    .cloned()
+    .collect()
+}
+
+fn create_fullnode_service(fullnode_name: String) -> Result {
+    Ok(Service {
+        metadata: ObjectMeta {
+            name: Some(fullnode_name.clone()),
+            ..ObjectMeta::default()
+        },
+        spec: Some(ServiceSpec {
+            selector: Some(create_fullnode_labels(fullnode_name)),
+            // for now, only expose the REST API
+            ports: Some(vec![ServicePort {
+                port: REST_API_SERVICE_PORT as i32,
+                ..ServicePort::default()
+            }]),
+            ..ServiceSpec::default()
+        }),
+        ..Service::default()
+    })
+}
+
+fn create_fullnode_container(
+    fullnode_image: String,
+    validator_container: &Container,
+) -> Result {
+    Ok(Container {
+        image: Some(fullnode_image),
+        command: Some(vec![
+            "/usr/local/bin/aptos-node".to_string(),
+            "-f".to_string(),
+            format!("/opt/aptos/etc/{}", FULLNODE_CONFIG_MAP_KEY),
+        ]),
+        volume_mounts: Some(vec![
+            VolumeMount {
+                mount_path: APTOS_CONFIG_VOLUME_PATH.to_string(),
+                name: APTOS_CONFIG_VOLUME_NAME.to_string(),
+                ..VolumeMount::default()
+            },
+            VolumeMount {
+                mount_path: APTOS_DATA_VOLUME_PATH.to_string(),
+                name: APTOS_DATA_VOLUME_NAME.to_string(),
+                ..VolumeMount::default()
+            },
+            VolumeMount {
+                mount_path: GENESIS_CONFIG_VOLUME_PATH.to_string(),
+                name: GENESIS_CONFIG_VOLUME_NAME.to_string(),
+                ..VolumeMount::default()
+            },
+        ]),
+        // specifically, inherit resources, env,ports, securityContext from the validator's container
+        ..validator_container.clone()
+    })
+}
+
+fn create_fullnode_volumes(
+    fullnode_genesis_secret_name: String,
+    fullnode_node_config_config_map_name: String,
+) -> Vec {
+    vec![
+        Volume {
+            name: GENESIS_CONFIG_VOLUME_NAME.to_string(),
+            secret: Some(SecretVolumeSource {
+                secret_name: Some(fullnode_genesis_secret_name),
+                ..SecretVolumeSource::default()
+            }),
+            ..Volume::default()
+        },
+        Volume {
+            name: APTOS_CONFIG_VOLUME_NAME.to_string(),
+            config_map: Some(ConfigMapVolumeSource {
+                name: Some(fullnode_node_config_config_map_name),
+                ..ConfigMapVolumeSource::default()
+            }),
+            ..Volume::default()
+        },
+    ]
+}
+
+/// Create a fullnode StatefulSet given some templates from the validator
+fn create_fullnode_stateful_set(
+    fullnode_name: String,
+    fullnode_image: String,
+    fullnode_genesis_secret_name: String,
+    fullnode_node_config_config_map_name: String,
+    validator_stateful_set: StatefulSet,
+    validator_data_volume: PersistentVolumeClaim,
+) -> Result {
+    // extract some useful structs from the validator
+    let validator_stateful_set_spec = validator_stateful_set
+        .spec
+        .as_ref()
+        .context("Validator StatefulSet does not have spec")?
+        .clone();
+    let validator_stateful_set_pod_spec = validator_stateful_set_spec
+        .template
+        .spec
+        .as_ref()
+        .context("Validator StatefulSet does not have spec.template.spec")?
+        .clone();
+
+    let validator_container = validator_stateful_set_pod_spec
+        .containers
+        .first()
+        .context("Validator StatefulSet does not have any containers")?;
+
+    // common labels
+    let labels_map: BTreeMap = create_fullnode_labels(fullnode_name.clone());
+
+    // create the fullnode data volume
+    let data_volume = create_fullnode_persistent_volume_claim(validator_data_volume)?;
+
+    // create the fullnode container
+    let fullnode_container = create_fullnode_container(fullnode_image, validator_container)?;
+
+    // create the fullnode volumes
+    let fullnode_volumes = create_fullnode_volumes(
+        fullnode_genesis_secret_name,
+        fullnode_node_config_config_map_name,
+    );
+
+    // build the fullnode stateful set
+    let mut fullnode_stateful_set = StatefulSet::default();
+    fullnode_stateful_set.metadata.name = Some(fullnode_name.clone());
+    fullnode_stateful_set.metadata.labels = Some(labels_map.clone());
+    fullnode_stateful_set.spec = Some(StatefulSetSpec {
+        service_name: fullnode_name, // the name of the service is the same as that of the fullnode
+        selector: LabelSelector {
+            match_labels: Some(labels_map.clone()),
+            ..LabelSelector::default()
+        },
+        volume_claim_templates: Some(vec![data_volume]), // a PVC that is created directly by the StatefulSet, and owned by it
+        template: PodTemplateSpec {
+            metadata: Some(ObjectMeta {
+                labels: Some(labels_map),
+                ..ObjectMeta::default()
+            }),
+            spec: Some(PodSpec {
+                containers: vec![fullnode_container],
+                volumes: Some(fullnode_volumes),
+                // specifically, inherit nodeSelector, affinity, tolerations, securityContext, serviceAccountName from the validator's PodSpec
+                ..validator_stateful_set_pod_spec.clone()
+            }),
+        },
+        ..validator_stateful_set_spec
+    });
+    Ok(fullnode_stateful_set)
+}
+
+/// Create a default PFN NodeConfig that uses the genesis, waypoint, and data paths expected in k8s
+pub fn get_default_pfn_node_config() -> NodeConfig {
+    let mut waypoint_path = PathBuf::from(GENESIS_CONFIG_VOLUME_PATH);
+    waypoint_path.push("waypoint.txt");
+
+    let mut genesis_path = PathBuf::from(GENESIS_CONFIG_VOLUME_PATH);
+    genesis_path.push("genesis.blob");
+
+    NodeConfig {
+        base: BaseConfig {
+            role: RoleType::FullNode,
+            data_dir: PathBuf::from(APTOS_DATA_VOLUME_PATH),
+            waypoint: WaypointConfig::FromFile(waypoint_path),
+            ..BaseConfig::default()
+        },
+        execution: ExecutionConfig {
+            genesis_file_location: genesis_path,
+            ..ExecutionConfig::default()
+        },
+        full_node_networks: vec![NetworkConfig {
+            network_id: NetworkId::Public,
+            discovery_method: DiscoveryMethod::Onchain,
+            // defaults to listening on "/ip4/0.0.0.0/tcp/6180"
+            ..NetworkConfig::default()
+        }],
+        api: ApiConfig {
+            // API defaults to listening on "127.0.0.1:8080". Override with 0.0.0.0:8080
+            address: SocketAddr::V4(SocketAddrV4::new(
+                Ipv4Addr::new(0, 0, 0, 0),
+                REST_API_SERVICE_PORT as u16,
+            )),
+            ..ApiConfig::default()
+        },
+        ..NodeConfig::default()
+    }
+}
+
+/// Create a PFN stateful set workload
+/// This function assumes that the swarm has already been set up (e.g. there are already validators running) as it borrows
+/// some artifacts such as genesis from the 0th validator
+/// The given NodeConfig will be merged with the default PFN NodeConfig for Forge
+pub async fn install_public_fullnode<'a>(
+    stateful_set_api: Arc>,
+    configmap_api: Arc>,
+    persistent_volume_claim_api: Arc>,
+    service_api: Arc>,
+    version: &'a Version,
+    node_config: &'a NodeConfig,
+    era: String,
+    namespace: String,
+    use_port_forward: bool,
+) -> Result<(PeerId, K8sNode)> {
+    let default_node_config = get_default_pfn_node_config();
+
+    let merged_node_config =
+        merge_node_config(default_node_config, serde_yaml::to_value(node_config)?)?;
+
+    let node_peer_id = node_config.get_peer_id().unwrap_or_else(PeerId::random);
+    let fullnode_name = format!("fullnode-{}", node_peer_id.short_str());
+
+    // create the NodeConfig configmap
+    let fullnode_node_config_config_map_name = format!("{}-config", fullnode_name.clone());
+    let fullnode_node_config_config_map = create_node_config_configmap(
+        fullnode_node_config_config_map_name.clone(),
+        &merged_node_config,
+    )
+    .await?;
+    configmap_api
+        .create(&PostParams::default(), &fullnode_node_config_config_map)
+        .await?;
+
+    // assume that the validator workload (val0) has already been created (not necessarily running yet)
+    // get its spec so we can inherit some of its properties
+    let validator_stateful_set = stateful_set_api.get(VALIDATOR_0_STATEFUL_SET_NAME).await?;
+
+    // get the fullnode image
+    let fullnode_image_full =
+        get_fullnode_image_from_validator_image(&validator_stateful_set, version)?;
+
+    // borrow genesis secret from the first validator. it follows this naming convention
+    let fullnode_genesis_secret_name = format!("{}-e{}", VALIDATOR_0_GENESIS_SECRET_PREFIX, era);
+    let validator_data_persistent_volume_claim_name = format!(
+        "{}-e{}",
+        VALIDATOR_0_DATA_PERSISTENT_VOLUME_CLAIM_PREFIX, era
+    );
+
+    // create the data volume
+    let validator_data_volume = persistent_volume_claim_api
+        .get(validator_data_persistent_volume_claim_name.as_str())
+        .await
+        .map_err(|e| {
+            anyhow::anyhow!(
+                "Could not get validator data volume to inherit from {:?}: {:?}",
+                validator_data_persistent_volume_claim_name,
+                e
+            )
+        })?;
+
+    let fullnode_stateful_set = create_fullnode_stateful_set(
+        fullnode_name.clone(),
+        fullnode_image_full,
+        fullnode_genesis_secret_name,
+        fullnode_node_config_config_map_name,
+        validator_stateful_set,
+        validator_data_volume,
+    )?;
+
+    // check that all the labels are the same
+    let fullnode_metadata_labels = fullnode_stateful_set
+        .metadata
+        .labels
+        .as_ref()
+        .context("Validator StatefulSet does not have metadata.labels")?;
+    let fullnode_spec_selector_match_labels = fullnode_stateful_set
+        .spec
+        .as_ref()
+        .context("Validator StatefulSet does not have spec")?
+        .selector
+        .match_labels
+        .as_ref()
+        .context("Validator StatefulSet does not have spec.selector.match_labels")?;
+    let fullnode_spec_template_metadata_labels = fullnode_stateful_set
+        .spec
+        .as_ref()
+        .context("Validator StatefulSet does not have spec")?
+        .template
+        .metadata
+        .as_ref()
+        .context("Validator StatefulSet does not have spec.template.metadata")?
+        .labels
+        .as_ref()
+        .context("Validator StatefulSet does not have spec.template.metadata.labels")?;
+
+    let labels = [
+        fullnode_metadata_labels,
+        fullnode_spec_selector_match_labels,
+        fullnode_spec_template_metadata_labels,
+    ];
+    for label1 in labels.into_iter() {
+        for label2 in labels.into_iter() {
+            assert_eq!(label1, label2);
+        }
+    }
+
+    let fullnode_service = create_fullnode_service(fullnode_name.clone())?;
+
+    // write the spec to file
+    let tmp_dir = TempDir::new().expect("Could not create temp dir");
+    let fullnode_config_path = tmp_dir.path().join("fullnode.yaml");
+    let fullnode_config_file = std::fs::File::create(&fullnode_config_path)
+        .with_context(|| format!("Could not create file {:?}", fullnode_config_path))?;
+    serde_yaml::to_writer(fullnode_config_file, &fullnode_stateful_set)?;
+
+    let fullnode_service_path = tmp_dir.path().join("service.yaml");
+    let fullnode_service_file = std::fs::File::create(&fullnode_service_path)
+        .with_context(|| format!("Could not create file {:?}", fullnode_service_path))?;
+    serde_yaml::to_writer(fullnode_service_file, &fullnode_service)?;
+    info!("Wrote fullnode k8s specs to path: {:?}", &tmp_dir);
+
+    // create the StatefulSet
+    stateful_set_api
+        .create(&PostParams::default(), &fullnode_stateful_set)
+        .await?;
+    let fullnode_stateful_set_str = serde_yaml::to_string(&fullnode_stateful_set)?;
+    info!(
+        "Created fullnode StatefulSet:\n---{}\n---",
+        &fullnode_stateful_set_str
+    );
+    // and its service
+    service_api
+        .create(&PostParams::default(), &fullnode_service)
+        .await?;
+    let fullnode_service_str = serde_yaml::to_string(&fullnode_service)?;
+    info!(
+        "Created fullnode Service:\n---{}\n---",
+        fullnode_service_str
+    );
+
+    let service_name = &fullnode_service
+        .metadata
+        .name
+        .context("Fullnode Service does not have metadata.name")?;
+
+    let full_service_name = format!("{}.{}.svc", service_name, &namespace); // this is the full name that includes the namespace
+
+    let ret_node = K8sNode {
+        name: fullnode_name.clone(),
+        stateful_set_name: fullnode_stateful_set
+            .metadata
+            .name
+            .context("Fullnode StatefulSet does not have metadata.name")?,
+        peer_id: node_peer_id,
+        index: 0,
+        service_name: full_service_name,
+        version: version.clone(),
+        namespace,
+        haproxy_enabled: false,
+
+        port_forward_enabled: use_port_forward,
+        rest_api_port: REST_API_SERVICE_PORT, // in the case of port-forward, this port will be changed at runtime
+    };
+
+    Ok((node_peer_id, ret_node))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::{
+        MockConfigMapApi, MockPersistentVolumeClaimApi, MockServiceApi, MockStatefulSetApi,
+    };
+    use aptos_config::config::Identity;
+    use aptos_sdk::crypto::{x25519::PrivateKey, Uniform};
+    use k8s_openapi::apimachinery::pkg::api::resource::Quantity;
+
+    /// Get a dummy validator persistent volume claim that looks like one created by terraform/helm/aptos-node/templates/validator.yaml
+    fn get_dummy_validator_persistent_volume_claim() -> PersistentVolumeClaim {
+        PersistentVolumeClaim {
+            metadata: ObjectMeta {
+                name: Some("aptos-node-0-validator-e42069".to_string()),
+                ..ObjectMeta::default()
+            },
+            spec: Some(PersistentVolumeClaimSpec {
+                access_modes: Some(vec!["ReadWriteOnce".to_string()]),
+                resources: Some(ResourceRequirements {
+                    requests: Some(
+                        [
+                            ("storage".to_string(), Quantity("1Gi".to_string())),
+                            ("storage2".to_string(), Quantity("2Gi".to_string())),
+                        ]
+                        .iter()
+                        .cloned()
+                        .collect(),
+                    ),
+                    ..ResourceRequirements::default()
+                }),
+                ..PersistentVolumeClaimSpec::default()
+            }),
+            ..PersistentVolumeClaim::default()
+        }
+    }
+
+    /// Get a dummy validator stateful set that looks like one created by terraform/helm/aptos-node/templates/validator.yaml
+    fn get_dummy_validator_stateful_set() -> StatefulSet {
+        let labels: BTreeMap = [
+            (
+                "app.kubernetes.io/name".to_string(),
+                "validator".to_string(),
+            ),
+            (
+                "app.kubernetes.io/instance".to_string(),
+                "aptos-node-0-validator-0".to_string(),
+            ),
+            (
+                "app.kubernetes.io/part-of".to_string(),
+                "forge-pfn".to_string(),
+            ),
+        ]
+        .iter()
+        .cloned()
+        .collect();
+        StatefulSet {
+            metadata: ObjectMeta {
+                name: Some("aptos-node-0-validator".to_string()),
+                labels: Some(labels.clone()),
+                ..ObjectMeta::default()
+            },
+            spec: Some(StatefulSetSpec {
+                replicas: Some(1),
+                template: PodTemplateSpec {
+                    metadata: Some(ObjectMeta {
+                        labels: Some(labels),
+                        ..ObjectMeta::default()
+                    }),
+                    spec: Some(PodSpec {
+                        containers: vec![Container {
+                            name: "validator".to_string(),
+                            image: Some(
+                                "banana.fruit.aptos/potato/validator:banana_image_tag".to_string(),
+                            ),
+                            command: Some(vec![
+                                "/usr/local/bin/aptos-node".to_string(),
+                                "-f".to_string(),
+                                "/opt/aptos/etc/validator.yaml".to_string(),
+                            ]),
+                            volume_mounts: Some(vec![
+                                VolumeMount {
+                                    mount_path: APTOS_CONFIG_VOLUME_PATH.to_string(),
+                                    name: APTOS_CONFIG_VOLUME_NAME.to_string(),
+                                    ..VolumeMount::default()
+                                },
+                                VolumeMount {
+                                    mount_path: APTOS_DATA_VOLUME_PATH.to_string(),
+                                    name: APTOS_DATA_VOLUME_NAME.to_string(),
+                                    ..VolumeMount::default()
+                                },
+                                VolumeMount {
+                                    mount_path: GENESIS_CONFIG_VOLUME_PATH.to_string(),
+                                    name: GENESIS_CONFIG_VOLUME_NAME.to_string(),
+                                    ..VolumeMount::default()
+                                },
+                            ]),
+                            ..Container::default()
+                        }],
+                        ..PodSpec::default()
+                    }),
+                },
+                ..StatefulSetSpec::default()
+            }),
+            ..StatefulSet::default()
+        }
+    }
+
+    #[tokio::test]
+    /// Test that we can create a node config configmap and that it contains the node config at a known data key
+    async fn test_create_node_config_map() {
+        let config_map_name = "aptos-node-0-validator-0-config".to_string();
+        let node_config = NodeConfig::default();
+
+        // expect that the one we get is the same as the one we created
+        let created_config_map =
+            create_node_config_configmap(config_map_name.clone(), &node_config)
+                .await
+                .unwrap();
+
+        let regenerated_node_config = serde_yaml::from_str::(
+            created_config_map
+                .data
+                .unwrap()
+                .get(FULLNODE_CONFIG_MAP_KEY)
+                .unwrap(),
+        )
+        .unwrap();
+        assert_eq!(regenerated_node_config, node_config);
+    }
+
+    #[test]
+    /// Test that we can create a data volume from an existing validator data volume, and that we inherit the resource requests
+    fn test_create_persistent_volume_claim() {
+        let requests = Some(
+            [
+                ("storage".to_string(), Quantity("1Gi".to_string())),
+                ("storage2".to_string(), Quantity("2Gi".to_string())),
+            ]
+            .iter()
+            .cloned()
+            .collect(),
+        );
+        let pvc = PersistentVolumeClaim {
+            metadata: ObjectMeta {
+                name: Some(APTOS_DATA_VOLUME_NAME.to_string()),
+                ..ObjectMeta::default()
+            },
+            spec: Some(PersistentVolumeClaimSpec {
+                access_modes: Some(vec!["ReadWriteOnce".to_string()]),
+                resources: Some(ResourceRequirements {
+                    requests,
+                    ..ResourceRequirements::default()
+                }),
+                ..PersistentVolumeClaimSpec::default()
+            }),
+            ..PersistentVolumeClaim::default()
+        };
+        let created_pvc = create_fullnode_persistent_volume_claim(pvc.clone());
+
+        // assert that the resources are the same
+        assert_eq!(
+            created_pvc.unwrap().spec.unwrap().resources,
+            pvc.spec.unwrap().resources
+        );
+    }
+
+    #[test]
+    /// Test that the created StatefulSet and Service are connected
+    fn test_create_fullnode_stateful_set_and_service_connected() {
+        // top level args
+        let era = 42069;
+        let peer_id = PeerId::random();
+        let fullnode_name = "fullnode-".to_string() + &peer_id.to_string(); // everything should be keyed on this
+        let fullnode_image = "fruit.com/banana:latest".to_string();
+        let fullnode_genesis_secret_name = format!("aptos-node-0-genesis-e{}", era);
+        let fullnode_node_config_config_map_name = format!("{}-config", fullnode_name);
+
+        let fullnode_stateful_set = create_fullnode_stateful_set(
+            fullnode_name.clone(),
+            fullnode_image,
+            fullnode_genesis_secret_name,
+            fullnode_node_config_config_map_name,
+            get_dummy_validator_stateful_set(),
+            get_dummy_validator_persistent_volume_claim(),
+        )
+        .unwrap();
+
+        let fullnode_service = create_fullnode_service(fullnode_name.clone()).unwrap();
+
+        // assert that the StatefulSet has the correct name
+        assert_eq!(
+            fullnode_stateful_set.metadata.name,
+            Some(fullnode_name.clone())
+        );
+        // assert that the Service has the correct name
+        assert_eq!(fullnode_service.metadata.name, Some(fullnode_name.clone()));
+        // assert that the StatefulSet has a serviceName that matches the Service
+        assert_eq!(
+            fullnode_stateful_set.spec.unwrap().service_name,
+            fullnode_name
+        );
+        // assert that the labels in the Service match the StatefulSet
+        assert_eq!(
+            fullnode_service.spec.unwrap().selector,
+            fullnode_stateful_set.metadata.labels
+        );
+    }
+
+    #[tokio::test]
+    /// Full PFN installation test, checking that the resulting resources created are as expected
+    async fn test_install_public_fullnode() {
+        // top level args
+        let peer_id = PeerId::random();
+        let version = Version::new(0, "banana".to_string());
+        let _fullnode_name = "fullnode-".to_string() + &peer_id.to_string();
+
+        // create APIs
+        let stateful_set_api = Arc::new(MockStatefulSetApi::from_stateful_set(
+            get_dummy_validator_stateful_set(),
+        ));
+        let configmap_api = Arc::new(MockConfigMapApi::from_config_map(ConfigMap::default()));
+        let persistent_volume_claim_api =
+            Arc::new(MockPersistentVolumeClaimApi::from_persistent_volume_claim(
+                get_dummy_validator_persistent_volume_claim(),
+            ));
+        let service_api = Arc::new(MockServiceApi::from_service(Service::default()));
+
+        // get the base config and mutate it
+        let mut node_config = get_default_pfn_node_config();
+        node_config.full_node_networks[0].identity =
+            Identity::from_config(PrivateKey::generate_for_testing(), peer_id);
+
+        let era = "42069".to_string();
+        let namespace = "forge42069".to_string();
+
+        let (created_peer_id, created_node) = install_public_fullnode(
+            stateful_set_api,
+            configmap_api,
+            persistent_volume_claim_api,
+            service_api,
+            &version,
+            &node_config,
+            era,
+            namespace,
+            false,
+        )
+        .await
+        .unwrap();
+
+        // assert the created resources match some patterns
+        assert_eq!(created_peer_id, peer_id);
+        assert_eq!(
+            created_node.name,
+            format!("fullnode-{}", &peer_id.short_str())
+        );
+        assert!(created_node.name.len() < 64); // This is a k8s limit
+    }
+}
diff --git a/testsuite/forge/src/backend/k8s/kube_api.rs b/testsuite/forge/src/backend/k8s/kube_api.rs
index 3576fb5ea44cd..3ff3103fdff28 100644
--- a/testsuite/forge/src/backend/k8s/kube_api.rs
+++ b/testsuite/forge/src/backend/k8s/kube_api.rs
@@ -38,31 +38,324 @@ where
 }
 
 #[async_trait]
-pub trait Get: Send + Sync {
+pub trait ReadWrite: Send + Sync {
     async fn get(&self, name: &str) -> Result;
-}
-
-#[async_trait]
-pub trait Create: Send + Sync {
     async fn create(&self, pp: &PostParams, k: &K) -> Result;
 }
 
+// Implement the traits for K8sApi
+
 #[async_trait]
-impl Get for K8sApi
+impl ReadWrite for K8sApi
 where
     K: k8s_openapi::Resource + Send + Sync + Clone + DeserializeOwned + Serialize + Debug,
 {
     async fn get(&self, name: &str) -> Result {
         self.api.get(name).await
     }
-}
 
-#[async_trait]
-impl Create for K8sApi
-where
-    K: k8s_openapi::Resource + Send + Sync + Clone + DeserializeOwned + Serialize + Debug,
-{
     async fn create(&self, pp: &PostParams, k: &K) -> Result {
         self.api.create(pp, k).await
     }
 }
+
+#[cfg(test)]
+pub mod mocks {
+    use super::*;
+    use crate::Result;
+    use async_trait::async_trait;
+    use hyper::StatusCode;
+    use k8s_openapi::api::{
+        apps::v1::StatefulSet,
+        core::v1::{ConfigMap, Namespace, PersistentVolumeClaim, Pod, Secret, Service},
+    };
+    use kube::{api::PostParams, error::ErrorResponse, Error as KubeError};
+
+    // Mock StatefulSet API
+
+    pub struct MockStatefulSetApi {
+        stateful_set: StatefulSet,
+    }
+
+    impl MockStatefulSetApi {
+        pub fn from_stateful_set(stateful_set: StatefulSet) -> Self {
+            MockStatefulSetApi { stateful_set }
+        }
+    }
+
+    #[async_trait]
+    impl ReadWrite for MockStatefulSetApi {
+        async fn get(&self, name: &str) -> Result {
+            if self.stateful_set.metadata.name == Some(name.to_string()) {
+                return Ok(self.stateful_set.clone());
+            }
+            return Err(KubeError::Api(ErrorResponse {
+                status: "failed".to_string(),
+                message: format!(
+                    "StatefulSet with name {} could not be found in {:?}",
+                    name, self.stateful_set
+                ),
+                reason: "not_found".to_string(),
+                code: 404,
+            }));
+        }
+
+        async fn create(
+            &self,
+            _pp: &PostParams,
+            stateful_set: &StatefulSet,
+        ) -> Result {
+            if self.stateful_set.metadata.name == stateful_set.metadata.name {
+                return Err(KubeError::Api(ErrorResponse {
+                    status: "failed".to_string(),
+                    message: format!(
+                        "StatefulSet with same name already exists in {:?}",
+                        self.stateful_set
+                    ),
+                    reason: "already_exists".to_string(),
+                    code: 409,
+                }));
+            }
+            Ok(self.stateful_set.clone())
+        }
+    }
+
+    // Mock Pod API
+
+    pub struct MockPodApi {
+        pod: Pod,
+    }
+
+    impl MockPodApi {
+        pub fn from_pod(pod: Pod) -> Self {
+            MockPodApi { pod }
+        }
+    }
+
+    #[async_trait]
+    impl ReadWrite for MockPodApi {
+        async fn get(&self, _name: &str) -> Result {
+            Ok(self.pod.clone())
+        }
+
+        async fn create(&self, _pp: &PostParams, _pod: &Pod) -> Result {
+            Ok(self.pod.clone())
+        }
+    }
+
+    // Mock ConfigMap API
+
+    pub struct MockConfigMapApi {
+        config_map: ConfigMap,
+    }
+
+    impl MockConfigMapApi {
+        pub fn from_config_map(config_map: ConfigMap) -> Self {
+            MockConfigMapApi { config_map }
+        }
+    }
+
+    #[async_trait]
+    impl ReadWrite for MockConfigMapApi {
+        async fn get(&self, name: &str) -> Result {
+            if self.config_map.metadata.name == Some(name.to_string()) {
+                return Ok(self.config_map.clone());
+            }
+            return Err(KubeError::Api(ErrorResponse {
+                status: "failed".to_string(),
+                message: format!(
+                    "ConfigMap with name {} could not be found in {:?}",
+                    name, self.config_map
+                ),
+                reason: "not_found".to_string(),
+                code: 404,
+            }));
+        }
+
+        async fn create(
+            &self,
+            _pp: &PostParams,
+            config_map: &ConfigMap,
+        ) -> Result {
+            if self.config_map.metadata.name == config_map.metadata.name {
+                return Err(KubeError::Api(ErrorResponse {
+                    status: "failed".to_string(),
+                    message: format!(
+                        "ConfigMap with same name already exists in {:?}",
+                        self.config_map
+                    ),
+                    reason: "already_exists".to_string(),
+                    code: 409,
+                }));
+            }
+            Ok(self.config_map.clone())
+        }
+    }
+
+    // Mock PersistentVolumeClaim API
+
+    pub struct MockPersistentVolumeClaimApi {
+        persistent_volume_claim: PersistentVolumeClaim,
+    }
+
+    impl MockPersistentVolumeClaimApi {
+        pub fn from_persistent_volume_claim(
+            persistent_volume_claim: PersistentVolumeClaim,
+        ) -> Self {
+            MockPersistentVolumeClaimApi {
+                persistent_volume_claim,
+            }
+        }
+    }
+
+    #[async_trait]
+    impl ReadWrite for MockPersistentVolumeClaimApi {
+        async fn get(&self, name: &str) -> Result {
+            if self.persistent_volume_claim.metadata.name == Some(name.to_string()) {
+                return Ok(self.persistent_volume_claim.clone());
+            }
+            return Err(KubeError::Api(ErrorResponse {
+                status: "failed".to_string(),
+                message: format!(
+                    "PersistentVolumeClaim with name {} could not be found in {:?}",
+                    name, self.persistent_volume_claim
+                ),
+                reason: "not_found".to_string(),
+                code: 404,
+            }));
+        }
+
+        async fn create(
+            &self,
+            _pp: &PostParams,
+            persistent_volume_claim: &PersistentVolumeClaim,
+        ) -> Result {
+            if self.persistent_volume_claim.metadata.name == persistent_volume_claim.metadata.name {
+                return Err(KubeError::Api(ErrorResponse {
+                    status: "failed".to_string(),
+                    message: format!(
+                        "PersistentVolumeClaim with same name already exists in {:?}",
+                        self.persistent_volume_claim
+                    ),
+                    reason: "already_exists".to_string(),
+                    code: 409,
+                }));
+            }
+            Ok(self.persistent_volume_claim.clone())
+        }
+    }
+
+    // Mock Service API
+
+    pub struct MockServiceApi {
+        service: Service,
+    }
+
+    impl MockServiceApi {
+        pub fn from_service(service: Service) -> Self {
+            MockServiceApi { service }
+        }
+    }
+
+    #[async_trait]
+    impl ReadWrite for MockServiceApi {
+        async fn get(&self, name: &str) -> Result {
+            if self.service.metadata.name == Some(name.to_string()) {
+                return Ok(self.service.clone());
+            }
+            return Err(KubeError::Api(ErrorResponse {
+                status: "failed".to_string(),
+                message: format!(
+                    "Service with name {} could not be found in {:?}",
+                    name, self.service
+                ),
+                reason: "not_found".to_string(),
+                code: 404,
+            }));
+        }
+
+        async fn create(&self, _pp: &PostParams, service: &Service) -> Result {
+            if self.service.metadata.name == service.metadata.name {
+                return Err(KubeError::Api(ErrorResponse {
+                    status: "failed".to_string(),
+                    message: format!(
+                        "Service with same name already exists in {:?}",
+                        self.service
+                    ),
+                    reason: "already_exists".to_string(),
+                    code: 409,
+                }));
+            }
+            Ok(self.service.clone())
+        }
+    }
+
+    // Mock Service API
+    pub struct MockSecretApi {
+        secret: Option,
+    }
+
+    impl MockSecretApi {
+        pub fn from_secret(secret: Option) -> Self {
+            MockSecretApi { secret }
+        }
+    }
+
+    #[async_trait]
+    impl ReadWrite for MockSecretApi {
+        async fn get(&self, _name: &str) -> Result {
+            match self.secret {
+                Some(ref s) => Ok(s.clone()),
+                None => Err(KubeError::Api(ErrorResponse {
+                    status: "status".to_string(),
+                    message: "message".to_string(),
+                    reason: "reason".to_string(),
+                    code: 404,
+                })),
+            }
+        }
+
+        async fn create(&self, _pp: &PostParams, secret: &Secret) -> Result {
+            return Ok(secret.clone());
+        }
+    }
+
+    // Mock API that always fails to create a new Namespace
+
+    pub struct FailedNamespacesApi {
+        status_code: u16,
+    }
+
+    impl FailedNamespacesApi {
+        pub fn from_status_code(status_code: u16) -> Self {
+            FailedNamespacesApi { status_code }
+        }
+    }
+
+    #[async_trait]
+    impl ReadWrite for FailedNamespacesApi {
+        async fn get(&self, _name: &str) -> Result {
+            let status = StatusCode::from_u16(self.status_code).unwrap();
+            Err(KubeError::Api(ErrorResponse {
+                status: status.to_string(),
+                code: status.as_u16(),
+                message: "Failed to get namespace".to_string(),
+                reason: "Failed to parse error data".into(),
+            }))
+        }
+
+        async fn create(
+            &self,
+            _pp: &PostParams,
+            _namespace: &Namespace,
+        ) -> Result {
+            let status = StatusCode::from_u16(self.status_code).unwrap();
+            Err(KubeError::Api(ErrorResponse {
+                status: status.to_string(),
+                code: status.as_u16(),
+                message: "Failed to create namespace".to_string(),
+                reason: "Failed to parse error data".into(),
+            }))
+        }
+    }
+}
diff --git a/testsuite/forge/src/backend/k8s/mod.rs b/testsuite/forge/src/backend/k8s/mod.rs
index 929fb00b9ad2f..1f0f0057fd734 100644
--- a/testsuite/forge/src/backend/k8s/mod.rs
+++ b/testsuite/forge/src/backend/k8s/mod.rs
@@ -11,6 +11,7 @@ use std::{convert::TryInto, num::NonZeroUsize, time::Duration};
 pub mod chaos;
 mod cluster_helper;
 pub mod constants;
+mod fullnode;
 pub mod kube_api;
 pub mod node;
 pub mod prometheus;
@@ -20,6 +21,9 @@ mod swarm;
 use aptos_sdk::crypto::ed25519::ED25519_PRIVATE_KEY_LENGTH;
 pub use cluster_helper::*;
 pub use constants::*;
+pub use fullnode::*;
+#[cfg(test)]
+pub use kube_api::mocks::*;
 pub use kube_api::*;
 pub use node::K8sNode;
 pub use stateful_set::*;
@@ -111,8 +115,8 @@ impl Factory for K8sFactory {
         };
 
         let kube_client = create_k8s_client().await?;
-        let (validators, fullnodes) = if self.reuse {
-            match collect_running_nodes(
+        let (new_era, validators, fullnodes) = if self.reuse {
+            let (validators, fullnodes) = match collect_running_nodes(
                 &kube_client,
                 self.kube_namespace.clone(),
                 self.use_port_forward,
@@ -124,7 +128,9 @@ impl Factory for K8sFactory {
                 Err(e) => {
                     bail!(e);
                 },
-            }
+            };
+            let new_era = None; // TODO: get the actual era
+            (new_era, validators, fullnodes)
         } else {
             // clear the cluster of resources
             delete_k8s_resources(kube_client.clone(), &self.kube_namespace).await?;
@@ -162,7 +168,7 @@ impl Factory for K8sFactory {
             )
             .await
             {
-                Ok(res) => res,
+                Ok(res) => (Some(res.0), res.1, res.2),
                 Err(e) => {
                     uninstall_testnet_resources(self.kube_namespace.clone()).await?;
                     bail!(e);
@@ -178,6 +184,8 @@ impl Factory for K8sFactory {
             validators,
             fullnodes,
             self.keep,
+            new_era,
+            self.use_port_forward,
         )
         .await
         .unwrap();
diff --git a/testsuite/forge/src/backend/k8s/prometheus.rs b/testsuite/forge/src/backend/k8s/prometheus.rs
index fd8b67400ae0c..b4ac6e4cdfb75 100644
--- a/testsuite/forge/src/backend/k8s/prometheus.rs
+++ b/testsuite/forge/src/backend/k8s/prometheus.rs
@@ -1,7 +1,7 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
-use crate::{create_k8s_client, Get, K8sApi, Result};
+use crate::{create_k8s_client, K8sApi, ReadWrite, Result};
 use anyhow::bail;
 use aptos_logger::info;
 use k8s_openapi::api::core::v1::Secret;
@@ -20,7 +20,7 @@ pub async fn get_prometheus_client() -> Result {
 }
 
 async fn create_prometheus_client_from_environment(
-    secrets_api: Arc>,
+    secrets_api: Arc>,
 ) -> Result {
     let prom_url_env = std::env::var("PROMETHEUS_URL");
     let prom_token_env = std::env::var("PROMETHEUS_TOKEN");
@@ -135,40 +135,15 @@ pub async fn query_with_metadata(
 #[cfg(test)]
 mod tests {
     use super::*;
-    use async_trait::async_trait;
+    use crate::MockSecretApi;
     use k8s_openapi::ByteString;
-    use kube::{api::ObjectMeta, error::ErrorResponse, Error as KubeError};
+    use kube::api::ObjectMeta;
     use prometheus_http_query::Error as PrometheusError;
     use std::{
         env,
         time::{SystemTime, UNIX_EPOCH},
     };
 
-    struct MockSecretApi {
-        secret: Option,
-    }
-
-    impl MockSecretApi {
-        fn from_secret(secret: Option) -> Self {
-            MockSecretApi { secret }
-        }
-    }
-
-    #[async_trait]
-    impl Get for MockSecretApi {
-        async fn get(&self, _name: &str) -> Result {
-            match self.secret {
-                Some(ref s) => Ok(s.clone()),
-                None => Err(KubeError::Api(ErrorResponse {
-                    status: "status".to_string(),
-                    message: "message".to_string(),
-                    reason: "reason".to_string(),
-                    code: 404,
-                })),
-            }
-        }
-    }
-
     #[tokio::test]
     async fn test_create_client_secret() {
         let secret_api = Arc::new(MockSecretApi::from_secret(Some(Secret {
diff --git a/testsuite/forge/src/backend/k8s/stateful_set.rs b/testsuite/forge/src/backend/k8s/stateful_set.rs
index 74cb9d0e770df..46079e451162d 100644
--- a/testsuite/forge/src/backend/k8s/stateful_set.rs
+++ b/testsuite/forge/src/backend/k8s/stateful_set.rs
@@ -1,11 +1,10 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
-use crate::{create_k8s_client, Get, K8sApi, Result, KUBECTL_BIN};
+use crate::{create_k8s_client, k8s_wait_nodes_strategy, K8sApi, ReadWrite, Result, KUBECTL_BIN};
 use again::RetryPolicy;
 use anyhow::bail;
 use aptos_logger::info;
-use aptos_retrier::ExponentWithLimitDelay;
 use json_patch::{Patch as JsonPatch, PatchOperation, ReplaceOperation};
 use k8s_openapi::api::{apps::v1::StatefulSet, core::v1::Pod};
 use kube::{
@@ -86,8 +85,8 @@ pub async fn wait_stateful_set(
 
 /// Checks the status of a single K8s StatefulSet. Also inspects the pods to make sure they are all ready.
 async fn check_stateful_set_status(
-    stateful_set_api: Arc>,
-    pod_api: Arc>,
+    stateful_set_api: Arc>,
+    pod_api: Arc>,
     sts_name: &str,
     desired_replicas: u64,
 ) -> Result<(), WorkloadScalingError> {
@@ -283,81 +282,46 @@ pub async fn check_for_container_restart(
     kube_namespace: &str,
     sts_name: &str,
 ) -> Result<()> {
-    aptos_retrier::retry_async(
-        ExponentWithLimitDelay::new(1000, 10 * 1000, 60 * 1000),
-        || {
-            let pod_api: Api = Api::namespaced(kube_client.clone(), kube_namespace);
-            Box::pin(async move {
-                // Get the StatefulSet's Pod status
-                let pod_name = format!("{}-0", sts_name);
-                if let Some(status) = pod_api.get_status(&pod_name).await?.status {
-                    if let Some(container_statuses) = status.container_statuses {
-                        for container_status in container_statuses {
-                            if container_status.restart_count > 0 {
-                                bail!(
-                                    "Container {} in pod {} restarted {} times ",
-                                    container_status.name,
-                                    &pod_name,
-                                    container_status.restart_count
-                                );
-                            }
+    aptos_retrier::retry_async(k8s_wait_nodes_strategy(), || {
+        let pod_api: Api = Api::namespaced(kube_client.clone(), kube_namespace);
+        Box::pin(async move {
+            // Get the StatefulSet's Pod status
+            let pod_name = format!("{}-0", sts_name);
+            if let Some(status) = pod_api.get_status(&pod_name).await?.status {
+                if let Some(container_statuses) = status.container_statuses {
+                    for container_status in container_statuses {
+                        if container_status.restart_count > 0 {
+                            bail!(
+                                "Container {} in pod {} restarted {} times ",
+                                container_status.name,
+                                &pod_name,
+                                container_status.restart_count
+                            );
                         }
-                        return Ok(());
                     }
-                    // In case of no restarts, k8 apis returns no container statuses
-                    Ok(())
-                } else {
-                    bail!("Can't query the pod status for {}", sts_name)
+                    return Ok(());
                 }
-            })
-        },
-    )
+                // In case of no restarts, k8 apis returns no container statuses
+                Ok(())
+            } else {
+                bail!("Can't query the pod status for {}", sts_name)
+            }
+        })
+    })
     .await
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
-    use async_trait::async_trait;
-    use k8s_openapi::api::{
-        apps::v1::{StatefulSet, StatefulSetSpec, StatefulSetStatus},
-        core::v1::{ContainerState, ContainerStateWaiting, ContainerStatus, PodStatus},
+    use crate::{MockPodApi, MockStatefulSetApi};
+    use k8s_openapi::{
+        api::{
+            apps::v1::{StatefulSet, StatefulSetSpec, StatefulSetStatus},
+            core::v1::{ContainerState, ContainerStateWaiting, ContainerStatus, PodStatus},
+        },
+        apimachinery::pkg::apis::meta::v1::ObjectMeta,
     };
-    use kube::{api::ObjectMeta, Error as KubeError};
-
-    struct MockStatefulSetApi {
-        stateful_set: StatefulSet,
-    }
-
-    impl MockStatefulSetApi {
-        fn from_stateful_set(stateful_set: StatefulSet) -> Self {
-            MockStatefulSetApi { stateful_set }
-        }
-    }
-
-    #[async_trait]
-    impl Get for MockStatefulSetApi {
-        async fn get(&self, _name: &str) -> Result {
-            Ok(self.stateful_set.clone())
-        }
-    }
-
-    struct MockPodApi {
-        pod: Pod,
-    }
-
-    impl MockPodApi {
-        fn from_pod(pod: Pod) -> Self {
-            MockPodApi { pod }
-        }
-    }
-
-    #[async_trait]
-    impl Get for MockPodApi {
-        async fn get(&self, _name: &str) -> Result {
-            Ok(self.pod.clone())
-        }
-    }
 
     #[tokio::test]
     async fn test_check_stateful_set_status() {
diff --git a/testsuite/forge/src/backend/k8s/swarm.rs b/testsuite/forge/src/backend/k8s/swarm.rs
index c2b3d2b92d252..580b4bea9f1f6 100644
--- a/testsuite/forge/src/backend/k8s/swarm.rs
+++ b/testsuite/forge/src/backend/k8s/swarm.rs
@@ -3,25 +3,28 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::{
-    check_for_container_restart, create_k8s_client, delete_all_chaos, get_free_port,
-    get_stateful_set_image,
+    check_for_container_restart, create_k8s_client, delete_all_chaos, get_default_pfn_node_config,
+    get_free_port, get_stateful_set_image, install_public_fullnode,
     interface::system_metrics::{query_prometheus_system_metrics, SystemMetricsThreshold},
     node::K8sNode,
     prometheus::{self, query_with_metadata},
     query_sequence_number, set_stateful_set_image_tag, uninstall_testnet_resources, ChainInfo,
-    FullNode, Node, Result, Swarm, SwarmChaos, Validator, Version, HAPROXY_SERVICE_SUFFIX,
+    FullNode, K8sApi, Node, Result, Swarm, SwarmChaos, Validator, Version, HAPROXY_SERVICE_SUFFIX,
     REST_API_HAPROXY_SERVICE_PORT, REST_API_SERVICE_PORT,
 };
 use ::aptos_logger::*;
 use anyhow::{anyhow, bail, format_err};
 use aptos_config::config::NodeConfig;
-use aptos_retrier::ExponentWithLimitDelay;
+use aptos_retrier::fixed_retry_strategy;
 use aptos_sdk::{
     crypto::ed25519::Ed25519PrivateKey,
     move_types::account_address::AccountAddress,
     types::{chain_id::ChainId, AccountKey, LocalAccount, PeerId},
 };
-use k8s_openapi::api::apps::v1::StatefulSet;
+use k8s_openapi::api::{
+    apps::v1::StatefulSet,
+    core::v1::{ConfigMap, PersistentVolumeClaim, Service},
+};
 use kube::{
     api::{Api, ListParams},
     client::Client as K8sClient,
@@ -47,6 +50,8 @@ pub struct K8sSwarm {
     keep: bool,
     chaoses: HashSet,
     prom_client: Option,
+    era: Option,
+    use_port_forward: bool,
 }
 
 impl K8sSwarm {
@@ -58,6 +63,8 @@ impl K8sSwarm {
         validators: HashMap,
         fullnodes: HashMap,
         keep: bool,
+        era: Option,
+        use_port_forward: bool,
     ) -> Result {
         let kube_client = create_k8s_client().await?;
 
@@ -99,6 +106,8 @@ impl K8sSwarm {
             keep,
             chaoses: HashSet::new(),
             prom_client,
+            era,
+            use_port_forward,
         };
 
         // test hitting the configured prometheus endpoint
@@ -134,6 +143,49 @@ impl K8sSwarm {
     fn get_kube_client(&self) -> K8sClient {
         self.kube_client.clone()
     }
+
+    /// Installs a PFN with the given version and node config
+    async fn install_public_fullnode_resources<'a>(
+        &mut self,
+        version: &'a Version,
+        node_config: &'a NodeConfig,
+    ) -> Result<(PeerId, K8sNode)> {
+        // create APIs
+        let stateful_set_api: Arc> = Arc::new(K8sApi::::from_client(
+            self.get_kube_client(),
+            Some(self.kube_namespace.clone()),
+        ));
+        let configmap_api: Arc> = Arc::new(K8sApi::::from_client(
+            self.get_kube_client(),
+            Some(self.kube_namespace.clone()),
+        ));
+        let persistent_volume_claim_api: Arc> =
+            Arc::new(K8sApi::::from_client(
+                self.get_kube_client(),
+                Some(self.kube_namespace.clone()),
+            ));
+        let service_api: Arc> = Arc::new(K8sApi::::from_client(
+            self.get_kube_client(),
+            Some(self.kube_namespace.clone()),
+        ));
+        let (peer_id, mut k8snode) = install_public_fullnode(
+            stateful_set_api,
+            configmap_api,
+            persistent_volume_claim_api,
+            service_api,
+            version,
+            node_config,
+            self.era
+                .as_ref()
+                .expect("Installing PFN requires acquiring the current chain era")
+                .clone(),
+            self.kube_namespace.clone(),
+            self.use_port_forward,
+        )
+        .await?;
+        k8snode.start().await?; // actually start the node. if port-forward is enabled, this is when it gets its ephemeral port
+        Ok((peer_id, k8snode))
+    }
 }
 
 #[async_trait::async_trait]
@@ -245,8 +297,13 @@ impl Swarm for K8sSwarm {
         todo!()
     }
 
-    fn add_full_node(&mut self, _version: &Version, _template: NodeConfig) -> Result {
-        todo!()
+    async fn add_full_node(&mut self, version: &Version, template: NodeConfig) -> Result {
+        self.install_public_fullnode_resources(version, &template)
+            .await
+            .map(|(peer_id, node)| {
+                self.fullnodes.insert(peer_id, node);
+                peer_id
+            })
     }
 
     fn remove_full_node(&mut self, _id: PeerId) -> Result<()> {
@@ -374,17 +431,22 @@ impl Swarm for K8sSwarm {
             self.chain_id,
         )
     }
+
+    fn get_default_pfn_node_config(&self) -> NodeConfig {
+        get_default_pfn_node_config()
+    }
 }
 
 /// Amount of time to wait for genesis to complete
 pub fn k8s_wait_genesis_strategy() -> impl Iterator {
-    // FIXME: figure out why Genesis doesn't finish in 10 minutes, increasing timeout to 20.
-    ExponentWithLimitDelay::new(1000, 10 * 1000, 20 * 60 * 1000)
+    // retry every 10 seconds for 10 minutes
+    fixed_retry_strategy(10 * 1000, 60)
 }
 
-/// Amount of time to wait for nodes to respond on the REST API
+/// Amount of time to wait for nodes to spin up, from provisioning to API ready
 pub fn k8s_wait_nodes_strategy() -> impl Iterator {
-    ExponentWithLimitDelay::new(1000, 10 * 1000, 15 * 60 * 1000)
+    // retry every 10 seconds for 20 minutes
+    fixed_retry_strategy(10 * 1000, 120)
 }
 
 async fn list_stateful_sets(client: K8sClient, kube_namespace: &str) -> Result> {
diff --git a/testsuite/forge/src/backend/local/swarm.rs b/testsuite/forge/src/backend/local/swarm.rs
index 9dc64f1c018a1..96da051759711 100644
--- a/testsuite/forge/src/backend/local/swarm.rs
+++ b/testsuite/forge/src/backend/local/swarm.rs
@@ -548,7 +548,7 @@ impl Swarm for LocalSwarm {
         self.add_validator_fullnode(version, template, id)
     }
 
-    fn add_full_node(&mut self, version: &Version, template: NodeConfig) -> Result {
+    async fn add_full_node(&mut self, version: &Version, template: NodeConfig) -> Result {
         self.add_fullnode(version, template)
     }
 
@@ -649,6 +649,10 @@ impl Swarm for LocalSwarm {
             self.chain_id,
         )
     }
+
+    fn get_default_pfn_node_config(&self) -> NodeConfig {
+        todo!()
+    }
 }
 
 #[derive(Debug)]
diff --git a/testsuite/forge/src/interface/node.rs b/testsuite/forge/src/interface/node.rs
index d969e04190d10..12abb066843bd 100644
--- a/testsuite/forge/src/interface/node.rs
+++ b/testsuite/forge/src/interface/node.rs
@@ -217,8 +217,10 @@ pub trait NodeExt: Node {
     }
 
     async fn wait_until_healthy(&mut self, deadline: Instant) -> Result<()> {
+        let mut healthcheck_error =
+            HealthCheckError::Unknown(anyhow::anyhow!("No healthcheck performed yet"));
         while Instant::now() < deadline {
-            match self.health_check().await {
+            healthcheck_error = match self.health_check().await {
                 Ok(()) => return Ok(()),
                 Err(HealthCheckError::NotRunning(error)) => {
                     return Err(anyhow::anyhow!(
@@ -228,16 +230,17 @@ pub trait NodeExt: Node {
                         error,
                     ))
                 },
-                Err(_) => {}, // For other errors we'll retry
-            }
+                Err(e) => e, // For other errors we'll retry
+            };
 
             tokio::time::sleep(Duration::from_millis(500)).await;
         }
 
         Err(anyhow::anyhow!(
-            "Timed out waiting for Node {}:{} to be healthy",
+            "Timed out waiting for Node {}:{} to be healthy: Error: {:?}",
             self.name(),
-            self.peer_id()
+            self.peer_id(),
+            healthcheck_error
         ))
     }
 }
diff --git a/testsuite/forge/src/interface/swarm.rs b/testsuite/forge/src/interface/swarm.rs
index 9fb1f653b1f53..ed9d2258c2e5d 100644
--- a/testsuite/forge/src/interface/swarm.rs
+++ b/testsuite/forge/src/interface/swarm.rs
@@ -64,7 +64,7 @@ pub trait Swarm: Sync {
     ) -> Result;
 
     /// Adds a FullNode to the swarm and returns the PeerId
-    fn add_full_node(&mut self, version: &Version, template: NodeConfig) -> Result;
+    async fn add_full_node(&mut self, version: &Version, template: NodeConfig) -> Result;
 
     /// Removes the FullNode with the provided PeerId
     fn remove_full_node(&mut self, id: PeerId) -> Result<()>;
@@ -109,6 +109,8 @@ pub trait Swarm: Sync {
     fn aptos_public_info_for_node(&mut self, idx: usize) -> AptosPublicInfo<'_> {
         self.chain_info_for_node(idx).into_aptos_public_info()
     }
+
+    fn get_default_pfn_node_config(&self) -> NodeConfig;
 }
 
 impl SwarmExt for T where T: Swarm {}
diff --git a/testsuite/smoke-test/src/full_nodes.rs b/testsuite/smoke-test/src/full_nodes.rs
index bf4daa01549b9..7abff7eafdf0f 100644
--- a/testsuite/smoke-test/src/full_nodes.rs
+++ b/testsuite/smoke-test/src/full_nodes.rs
@@ -29,6 +29,7 @@ async fn test_full_node_basic_flow() {
     let version = swarm.versions().max().unwrap();
     let pfn_peer_id = swarm
         .add_full_node(&version, NodeConfig::get_default_pfn_config())
+        .await
         .unwrap();
     for fullnode in swarm.full_nodes_mut() {
         fullnode
@@ -213,7 +214,7 @@ async fn test_private_full_node() {
         NetworkId::Public,
         PeerRole::PreferredUpstream,
     );
-    let private = swarm.add_full_node(&version, private_config).unwrap();
+    let private = swarm.add_full_node(&version, private_config).await.unwrap();
 
     // And connect the user to the private swarm
     add_node_to_seeds(
@@ -222,7 +223,7 @@ async fn test_private_full_node() {
         NetworkId::Public,
         PeerRole::PreferredUpstream,
     );
-    let user = swarm.add_full_node(&version, user_config).unwrap();
+    let user = swarm.add_full_node(&version, user_config).await.unwrap();
 
     swarm
         .wait_for_connectivity(Instant::now() + Duration::from_secs(MAX_CONNECTIVITY_WAIT_SECS))
diff --git a/testsuite/smoke-test/src/fullnode.rs b/testsuite/smoke-test/src/fullnode.rs
index 0895a6e24bcbb..fd7828b5db477 100644
--- a/testsuite/smoke-test/src/fullnode.rs
+++ b/testsuite/smoke-test/src/fullnode.rs
@@ -20,6 +20,7 @@ async fn test_indexer() {
     let version = swarm.versions().max().unwrap();
     let fullnode_peer_id = swarm
         .add_full_node(&version, NodeConfig::get_default_pfn_config())
+        .await
         .unwrap();
     let validator_peer_id = swarm.validators().next().unwrap().peer_id();
     let _vfn_peer_id = swarm
diff --git a/testsuite/smoke-test/src/network.rs b/testsuite/smoke-test/src/network.rs
index 7b0fcf4941430..ed945499f95de 100644
--- a/testsuite/smoke-test/src/network.rs
+++ b/testsuite/smoke-test/src/network.rs
@@ -75,6 +75,7 @@ async fn test_connection_limiting() {
                 peer_set,
             ),
         )
+        .await
         .unwrap();
     swarm
         .fullnode_mut(pfn_peer_id)
@@ -115,6 +116,7 @@ async fn test_connection_limiting() {
                 peer_set,
             ),
         )
+        .await
         .unwrap();
 
     // This node should fail to connect
@@ -155,7 +157,10 @@ async fn test_rest_discovery() {
 
     // Start a new node that should connect to the previous node only via REST
     // The startup wait time should check if it connects successfully
-    swarm.add_full_node(&version, full_node_config).unwrap();
+    swarm
+        .add_full_node(&version, full_node_config)
+        .await
+        .unwrap();
 }
 
 // Currently this test seems flaky: https://github.com/aptos-labs/aptos-core/issues/670
diff --git a/testsuite/testcases/src/forge_setup_test.rs b/testsuite/testcases/src/forge_setup_test.rs
index f7b1613529d65..e662810be507a 100644
--- a/testsuite/testcases/src/forge_setup_test.rs
+++ b/testsuite/testcases/src/forge_setup_test.rs
@@ -1,6 +1,8 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
+use crate::generate_traffic;
+use anyhow::Context;
 use aptos_forge::{NetworkContext, NetworkTest, Result, Test};
 use aptos_logger::info;
 use rand::{
@@ -8,7 +10,7 @@ use rand::{
     seq::IteratorRandom,
     Rng, SeedableRng,
 };
-use std::thread;
+use std::{thread, time::Duration};
 use tokio::runtime::Runtime;
 
 const STATE_SYNC_VERSION_COUNTER_NAME: &str = "aptos_state_sync_version";
@@ -34,6 +36,7 @@ impl NetworkTest for ForgeSetupTest {
         info!("Pick one fullnode to stop and wipe");
         let fullnode = swarm.full_node_mut(*fullnode_id).unwrap();
         runtime.block_on(fullnode.clear_storage())?;
+        runtime.block_on(fullnode.start())?;
 
         let fullnode = swarm.full_node(*fullnode_id).unwrap();
         let fullnode_name = fullnode.name();
@@ -56,6 +59,25 @@ impl NetworkTest for ForgeSetupTest {
             thread::sleep(std::time::Duration::from_secs(5));
         }
 
+        // add some PFNs and send load to them
+        let mut pfns = Vec::new();
+        let num_pfns = 5;
+        for _ in 0..num_pfns {
+            let pfn_version = swarm.versions().max().unwrap();
+            let pfn_node_config = swarm.get_default_pfn_node_config();
+            let pfn_peer_id =
+                runtime.block_on(swarm.add_full_node(&pfn_version, pfn_node_config))?;
+
+            let _pfn = swarm.full_node(pfn_peer_id).context("pfn not found")?;
+            pfns.push(pfn_peer_id);
+        }
+
+        let duration = Duration::from_secs(10 * num_pfns);
+        let txn_stat = generate_traffic(ctx, &pfns, duration)?;
+
+        ctx.report
+            .report_txn_stats(self.name().to_string(), &txn_stat);
+
         Ok(())
     }
 }

From 0e8f96dc9301a483d9a2a9c078be20d4c5d9cd57 Mon Sep 17 00:00:00 2001
From: igor-aptos <110557261+igor-aptos@users.noreply.github.com>
Date: Thu, 8 Jun 2023 23:01:12 -0700
Subject: [PATCH 123/200] Add realistic_env_load_sweep forge test, to check
 latency across TPS (#8578)

---
 .github/workflows/forge-stable.yaml           |  15 ++-
 .../src/emitter/mod.rs                        |  14 ++-
 .../src/emitter/submission_worker.rs          |   6 +-
 testsuite/forge-cli/src/main.rs               | 107 +++++++++++++-----
 testsuite/forge/src/report.rs                 |   2 +
 testsuite/forge/src/success_criteria.rs       |  81 ++++++++++---
 .../testcases/src/load_vs_perf_benchmark.rs   | 102 +++++++++++------
 .../testcases/src/state_sync_performance.rs   |   2 +-
 testsuite/testcases/src/two_traffics_test.rs  |  45 ++------
 9 files changed, 250 insertions(+), 124 deletions(-)

diff --git a/.github/workflows/forge-stable.yaml b/.github/workflows/forge-stable.yaml
index 2e5eed5c8d212..475655abe3a41 100644
--- a/.github/workflows/forge-stable.yaml
+++ b/.github/workflows/forge-stable.yaml
@@ -293,11 +293,24 @@ jobs:
     secrets: inherit
     with:
       IMAGE_TAG: ${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
-      FORGE_NAMESPACE: forge-land-blocking-new-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
+      FORGE_NAMESPACE: forge-realistic-env-max-throughput-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
       FORGE_RUNNER_DURATION_SECS: 600
       FORGE_TEST_SUITE: realistic_env_max_throughput
       POST_TO_SLACK: true
 
+  run-forge-realistic-env-load-sweep:
+    if: ${{ github.event_name != 'pull_request' }}
+    needs: determine-test-metadata
+    uses: aptos-labs/aptos-core/.github/workflows/workflow-run-forge.yaml@main
+    secrets: inherit
+    with:
+      IMAGE_TAG: ${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
+      FORGE_NAMESPACE: forge-realistic-env-load-sweep-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
+      # 5 tests, each 300s
+      FORGE_RUNNER_DURATION_SECS: 1500
+      FORGE_TEST_SUITE: realistic_env_load_sweep
+      POST_TO_SLACK: true
+
   run-forge-three-region-graceful-overload:
     if: ${{ github.event_name != 'pull_request' }}
     needs: determine-test-metadata
diff --git a/crates/transaction-emitter-lib/src/emitter/mod.rs b/crates/transaction-emitter-lib/src/emitter/mod.rs
index 489de880ab8c3..6a199ccd12457 100644
--- a/crates/transaction-emitter-lib/src/emitter/mod.rs
+++ b/crates/transaction-emitter-lib/src/emitter/mod.rs
@@ -68,7 +68,7 @@ pub struct EmitModeParams {
     pub worker_offset_mode: WorkerOffsetMode,
     pub wait_millis: u64,
     pub check_account_sequence_only_once_fraction: f32,
-    pub check_account_sequence_sleep_millis: u64,
+    pub check_account_sequence_sleep: Duration,
 }
 
 #[derive(Clone, Debug)]
@@ -140,6 +140,8 @@ pub struct EmitJobRequest {
     prompt_before_spending: bool,
 
     coordination_delay_between_instances: Duration,
+
+    latency_polling_interval: Duration,
 }
 
 impl Default for EmitJobRequest {
@@ -163,6 +165,7 @@ impl Default for EmitJobRequest {
             expected_gas_per_txn: aptos_global_constants::MAX_GAS_AMOUNT,
             prompt_before_spending: false,
             coordination_delay_between_instances: Duration::from_secs(0),
+            latency_polling_interval: Duration::from_millis(300),
         }
     }
 }
@@ -257,6 +260,11 @@ impl EmitJobRequest {
         self
     }
 
+    pub fn latency_polling_interval(mut self, latency_polling_interval: Duration) -> Self {
+        self.latency_polling_interval = latency_polling_interval;
+        self
+    }
+
     pub fn calculate_mode_params(&self) -> EmitModeParams {
         let clients_count = self.rest_clients.len();
 
@@ -294,7 +302,7 @@ impl EmitJobRequest {
                     workers_per_endpoint: num_workers_per_endpoint,
                     endpoints: clients_count,
                     check_account_sequence_only_once_fraction: 0.0,
-                    check_account_sequence_sleep_millis: 300,
+                    check_account_sequence_sleep: self.latency_polling_interval,
                 }
             },
             EmitJobMode::ConstTps { tps }
@@ -382,7 +390,7 @@ impl EmitJobRequest {
                     workers_per_endpoint: num_workers_per_endpoint,
                     endpoints: clients_count,
                     check_account_sequence_only_once_fraction: 1.0 - sample_latency_fraction,
-                    check_account_sequence_sleep_millis: 300,
+                    check_account_sequence_sleep: self.latency_polling_interval,
                 }
             },
         }
diff --git a/crates/transaction-emitter-lib/src/emitter/submission_worker.rs b/crates/transaction-emitter-lib/src/emitter/submission_worker.rs
index 2215c6834fd55..47903e2cc35ca 100644
--- a/crates/transaction-emitter-lib/src/emitter/submission_worker.rs
+++ b/crates/transaction-emitter-lib/src/emitter/submission_worker.rs
@@ -159,10 +159,8 @@ impl SubmissionWorker {
                 // generally, we should never need to recheck, as we wait enough time
                 // before calling here, but in case of shutdown/or client we are talking
                 // to being stale (having stale transaction_version), we might need to wait.
-                Duration::from_millis(
-                    if self.skip_latency_stats { 10 } else { 1 }
-                        * self.params.check_account_sequence_sleep_millis,
-                ),
+                if self.skip_latency_stats { 10 } else { 1 }
+                    * self.params.check_account_sequence_sleep,
                 loop_stats,
             )
             .await;
diff --git a/testsuite/forge-cli/src/main.rs b/testsuite/forge-cli/src/main.rs
index 8401b9316c4c9..a9147872d90f0 100644
--- a/testsuite/forge-cli/src/main.rs
+++ b/testsuite/forge-cli/src/main.rs
@@ -263,7 +263,7 @@ fn main() -> Result<()> {
             match test_cmd {
                 TestCommand::LocalSwarm(local_cfg) => {
                     // Loosen all criteria for local runs
-                    test_suite.get_success_criteria_mut().avg_tps = 400;
+                    test_suite.get_success_criteria_mut().min_avg_tps = 400;
                     let previous_emit_job = test_suite.get_emit_job().clone();
                     let test_suite =
                         test_suite.with_emit_job(previous_emit_job.mode(EmitJobMode::MaxLoad {
@@ -492,6 +492,7 @@ fn single_test_suite(test_name: &str, duration: Duration) -> Result
         "compat" => compat(),
         "framework_upgrade" => upgrade(),
         // Rest of the tests:
+        "realistic_env_load_sweep" => realistic_env_load_sweep_test(),
         "epoch_changer_performance" => epoch_changer_performance(),
         "state_sync_perf_fullnodes_apply_outputs" => state_sync_perf_fullnodes_apply_outputs(),
         "state_sync_perf_fullnodes_execute_transactions" => {
@@ -591,8 +592,9 @@ fn run_consensus_only_perf_test() -> ForgeConfig {
     config
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
         .add_network_test(LoadVsPerfBenchmark {
-            test: &PerformanceBenchmark,
+            test: Box::new(PerformanceBenchmark),
             workloads: Workloads::TPS(&[30000]),
+            criteria: vec![],
         })
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             // no epoch change.
@@ -757,15 +759,65 @@ fn consensus_stress_test() -> ForgeConfig {
     })
 }
 
+fn realistic_env_load_sweep_test() -> ForgeConfig {
+    ForgeConfig::default()
+        .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
+        .with_initial_fullnode_count(10)
+        .add_network_test(CompositeNetworkTest::new_with_two_wrappers(
+            MultiRegionNetworkEmulationTest {
+                override_config: None,
+            },
+            CpuChaosTest {
+                override_config: None,
+            },
+            LoadVsPerfBenchmark {
+                test: Box::new(PerformanceBenchmark),
+                workloads: Workloads::TPS(&[10, 100, 1000, 3000, 5000]),
+                criteria: [
+                    (9, 1.5, 3.),
+                    (95, 1.5, 3.),
+                    (950, 2., 3.),
+                    (2900, 2.5, 4.),
+                    (4900, 3., 5.),
+                ]
+                .into_iter()
+                .map(|(min_tps, max_lat_p50, max_lat_p99)| {
+                    SuccessCriteria::new(min_tps)
+                        .add_latency_threshold(max_lat_p50, LatencyType::P50)
+                        .add_latency_threshold(max_lat_p99, LatencyType::P99)
+                })
+                .collect(),
+            },
+        ))
+        // Test inherits the main EmitJobRequest, so update here for more precise latency measurements
+        .with_emit_job(
+            EmitJobRequest::default().latency_polling_interval(Duration::from_millis(100)),
+        )
+        .with_genesis_helm_config_fn(Arc::new(|helm_values| {
+            // no epoch change.
+            helm_values["chain"]["epoch_duration_secs"] = (24 * 3600).into();
+        }))
+        .with_success_criteria(
+            SuccessCriteria::new(0)
+                .add_no_restarts()
+                .add_wait_for_catchup_s(60)
+                .add_chain_progress(StateProgressThreshold {
+                    max_no_progress_secs: 30.0,
+                    max_round_gap: 10,
+                }),
+        )
+}
+
 fn load_vs_perf_benchmark() -> ForgeConfig {
     ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
         .with_initial_fullnode_count(10)
         .add_network_test(LoadVsPerfBenchmark {
-            test: &PerformanceBenchmark,
+            test: Box::new(PerformanceBenchmark),
             workloads: Workloads::TPS(&[
                 200, 1000, 3000, 5000, 7000, 7500, 8000, 9000, 10000, 12000, 15000,
             ]),
+            criteria: Vec::new(),
         })
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             // no epoch change.
@@ -794,7 +846,7 @@ fn workload_vs_perf_benchmark() -> ForgeConfig {
         //     mempool_backlog: 10000,
         // }))
         .add_network_test(LoadVsPerfBenchmark {
-            test: &PerformanceBenchmark,
+            test: Box::new(PerformanceBenchmark),
             workloads: Workloads::TRANSACTIONS(&[
                 TransactionWorkload {
                     transaction_type: TransactionTypeArg::NoOp,
@@ -837,6 +889,7 @@ fn workload_vs_perf_benchmark() -> ForgeConfig {
                     unique_senders: true,
                 },
             ]),
+            criteria: Vec::new(),
         })
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             // no epoch change.
@@ -863,15 +916,14 @@ fn graceful_overload() -> ForgeConfig {
         // So having VFNs for all validators
         .with_initial_fullnode_count(10)
         .add_network_test(TwoTrafficsTest {
-            inner_mode: EmitJobMode::ConstTps { tps: 15000 },
-            inner_gas_price: aptos_global_constants::GAS_UNIT_PRICE,
-            inner_init_gas_price_multiplier: 20,
-            inner_transaction_type: TransactionTypeArg::CoinTransfer.materialize_default(),
+            inner_traffic: EmitJobRequest::default()
+                .mode(EmitJobMode::ConstTps { tps: 15000 })
+                .init_gas_price_multiplier(20),
+
             // Additionally - we are not really gracefully handling overlaods,
             // setting limits based on current reality, to make sure they
             // don't regress, but something to investigate
-            avg_tps: 3400,
-            latency_thresholds: &[],
+            inner_success_criteria: SuccessCriteria::new(3400),
         })
         // First start higher gas-fee traffic, to not cause issues with TxnEmitter setup - account creation
         .with_emit_job(
@@ -913,19 +965,13 @@ fn three_region_sim_graceful_overload() -> ForgeConfig {
         .add_network_test(CompositeNetworkTest::new(
             ThreeRegionSameCloudSimulationTest,
             TwoTrafficsTest {
-                inner_mode: EmitJobMode::ConstTps { tps: 15000 },
-                inner_gas_price: aptos_global_constants::GAS_UNIT_PRICE,
-                inner_init_gas_price_multiplier: 20,
-                // Cannot use TransactionTypeArg::materialize, as this needs to be static
-                inner_transaction_type: TransactionType::CoinTransfer {
-                    invalid_transaction_ratio: 0,
-                    sender_use_account_pool: false,
-                },
+                inner_traffic: EmitJobRequest::default()
+                    .mode(EmitJobMode::ConstTps { tps: 15000 })
+                    .init_gas_price_multiplier(20),
                 // Additionally - we are not really gracefully handling overlaods,
                 // setting limits based on current reality, to make sure they
                 // don't regress, but something to investigate
-                avg_tps: 1200,
-                latency_thresholds: &[],
+                inner_success_criteria: SuccessCriteria::new(3400),
             },
         ))
         // First start higher gas-fee traffic, to not cause issues with TxnEmitter setup - account creation
@@ -1333,14 +1379,12 @@ fn realistic_env_max_throughput_test_suite(duration: Duration) -> ForgeConfig {
                 override_config: None,
             },
             TwoTrafficsTest {
-                inner_mode: EmitJobMode::MaxLoad {
-                    mempool_backlog: 40000,
-                },
-                inner_gas_price: aptos_global_constants::GAS_UNIT_PRICE,
-                inner_init_gas_price_multiplier: 20,
-                inner_transaction_type: TransactionTypeArg::CoinTransfer.materialize_default(),
-                avg_tps: 5000,
-                latency_thresholds: &[],
+                inner_traffic: EmitJobRequest::default()
+                    .mode(EmitJobMode::MaxLoad {
+                        mempool_backlog: 40000,
+                    })
+                    .init_gas_price_multiplier(20),
+                inner_success_criteria: SuccessCriteria::new(5000),
             },
         ))
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
@@ -1351,7 +1395,8 @@ fn realistic_env_max_throughput_test_suite(duration: Duration) -> ForgeConfig {
         .with_emit_job(
             EmitJobRequest::default()
                 .mode(EmitJobMode::ConstTps { tps: 100 })
-                .gas_price(5 * aptos_global_constants::GAS_UNIT_PRICE),
+                .gas_price(5 * aptos_global_constants::GAS_UNIT_PRICE)
+                .latency_polling_interval(Duration::from_millis(100)),
         )
         .with_success_criteria(
             SuccessCriteria::new(95)
@@ -1366,8 +1411,8 @@ fn realistic_env_max_throughput_test_suite(duration: Duration) -> ForgeConfig {
                     // Check that we don't use more than 10 GB of memory for 30% of the time.
                     MetricsThreshold::new(10 * 1024 * 1024 * 1024, 30),
                 ))
-                .add_latency_threshold(4.0, LatencyType::P50)
-                .add_latency_threshold(8.0, LatencyType::P90)
+                .add_latency_threshold(3.0, LatencyType::P50)
+                .add_latency_threshold(5.0, LatencyType::P90)
                 .add_chain_progress(StateProgressThreshold {
                     max_no_progress_secs: 10.0,
                     max_round_gap: 4,
diff --git a/testsuite/forge/src/report.rs b/testsuite/forge/src/report.rs
index b32aa9fb45a6b..aabaa849a09ec 100644
--- a/testsuite/forge/src/report.rs
+++ b/testsuite/forge/src/report.rs
@@ -2,6 +2,7 @@
 // Parts of the project are originally copyright © Meta Platforms, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
+use aptos_logger::info;
 use aptos_transaction_emitter_lib::emitter::stats::TxnStats;
 use serde::Serialize;
 use std::fmt;
@@ -37,6 +38,7 @@ impl TestReport {
             self.text.push('\n');
         }
         self.text.push_str(&text);
+        info!("{}", text);
     }
 
     pub fn report_txn_stats(&mut self, test_name: String, stats: &TxnStats) {
diff --git a/testsuite/forge/src/success_criteria.rs b/testsuite/forge/src/success_criteria.rs
index c843ff8fb0b0a..e4683e4f9c443 100644
--- a/testsuite/forge/src/success_criteria.rs
+++ b/testsuite/forge/src/success_criteria.rs
@@ -24,9 +24,10 @@ pub enum LatencyType {
 
 #[derive(Default, Clone, Debug)]
 pub struct SuccessCriteria {
-    pub avg_tps: usize,
+    pub min_avg_tps: usize,
     latency_thresholds: Vec<(Duration, LatencyType)>,
     check_no_restarts: bool,
+    max_expired_tps: Option,
     wait_for_all_nodes_to_catchup: Option,
     // Maximum amount of CPU cores and memory bytes used by the nodes.
     system_metrics_threshold: Option,
@@ -34,11 +35,12 @@ pub struct SuccessCriteria {
 }
 
 impl SuccessCriteria {
-    pub fn new(tps: usize) -> Self {
+    pub fn new(min_avg_tps: usize) -> Self {
         Self {
-            avg_tps: tps,
+            min_avg_tps,
             latency_thresholds: Vec::new(),
             check_no_restarts: false,
+            max_expired_tps: None,
             wait_for_all_nodes_to_catchup: None,
             system_metrics_threshold: None,
             chain_progress_check: None,
@@ -50,6 +52,11 @@ impl SuccessCriteria {
         self
     }
 
+    pub fn add_max_expired_tps(mut self, max_expired_tps: usize) -> Self {
+        self.max_expired_tps = Some(max_expired_tps);
+        self
+    }
+
     pub fn add_wait_for_catchup_s(mut self, duration_secs: u64) -> Self {
         self.wait_for_all_nodes_to_catchup = Some(Duration::from_secs(duration_secs));
         self
@@ -75,6 +82,28 @@ impl SuccessCriteria {
 pub struct SuccessCriteriaChecker {}
 
 impl SuccessCriteriaChecker {
+    pub fn check_core_for_success(
+        success_criteria: &SuccessCriteria,
+        _report: &mut TestReport,
+        stats_rate: &TxnStatsRate,
+        traffic_name: Option,
+    ) -> anyhow::Result<()> {
+        let traffic_name_addition = traffic_name
+            .map(|n| format!(" for {}", n))
+            .unwrap_or_else(|| "".to_string());
+        Self::check_tps(
+            success_criteria.min_avg_tps,
+            stats_rate,
+            &traffic_name_addition,
+        )?;
+        Self::check_latency(
+            &success_criteria.latency_thresholds,
+            stats_rate,
+            &traffic_name_addition,
+        )?;
+        Ok(())
+    }
+
     pub async fn check_for_success(
         success_criteria: &SuccessCriteria,
         swarm: &mut dyn Swarm,
@@ -92,17 +121,13 @@ impl SuccessCriteriaChecker {
             stats.lasted.as_secs()
         );
         let stats_rate = stats.rate();
-        // TODO: Add more success criteria like expired transactions, CPU, memory usage etc
-        let avg_tps = stats_rate.committed;
-        if avg_tps < success_criteria.avg_tps as u64 {
-            bail!(
-                "TPS requirement failed. Average TPS {}, minimum TPS requirement {}",
-                avg_tps,
-                success_criteria.avg_tps,
-            )
-        }
 
-        Self::check_latency(&success_criteria.latency_thresholds, &stats_rate)?;
+        Self::check_tps(success_criteria.min_avg_tps, &stats_rate, &"".to_string())?;
+        Self::check_latency(
+            &success_criteria.latency_thresholds,
+            &stats_rate,
+            &"".to_string(),
+        )?;
 
         if let Some(timeout) = success_criteria.wait_for_all_nodes_to_catchup {
             swarm
@@ -243,9 +268,33 @@ impl SuccessCriteriaChecker {
         Ok(())
     }
 
+    pub fn check_tps(
+        min_avg_tps: usize,
+        stats_rate: &TxnStatsRate,
+        traffic_name_addition: &String,
+    ) -> anyhow::Result<()> {
+        let avg_tps = stats_rate.committed;
+        if avg_tps < min_avg_tps as u64 {
+            bail!(
+                "TPS requirement{} failed. Average TPS {}, minimum TPS requirement {}. Full stats: {}",
+                traffic_name_addition,
+                avg_tps,
+                min_avg_tps,
+                stats_rate,
+            )
+        } else {
+            println!(
+                "TPS is {} and is within limit of {}",
+                stats_rate.committed, min_avg_tps
+            );
+            Ok(())
+        }
+    }
+
     pub fn check_latency(
         latency_thresholds: &[(Duration, LatencyType)],
         stats_rate: &TxnStatsRate,
+        traffic_name_addition: &String,
     ) -> anyhow::Result<()> {
         let mut failures = Vec::new();
         for (latency_threshold, latency_type) in latency_thresholds {
@@ -259,8 +308,9 @@ impl SuccessCriteriaChecker {
             if latency > *latency_threshold {
                 failures.push(
                     format!(
-                        "{:?} latency is {}s and exceeds limit of {}s",
+                        "{:?} latency{} is {}s and exceeds limit of {}s",
                         latency_type,
+                        traffic_name_addition,
                         latency.as_secs_f32(),
                         latency_threshold.as_secs_f32()
                     )
@@ -268,8 +318,9 @@ impl SuccessCriteriaChecker {
                 );
             } else {
                 println!(
-                    "{:?} latency is {}s and is within limit of {}s",
+                    "{:?} latency{} is {}s and is within limit of {}s",
                     latency_type,
+                    traffic_name_addition,
                     latency.as_secs_f32(),
                     latency_threshold.as_secs_f32()
                 );
diff --git a/testsuite/testcases/src/load_vs_perf_benchmark.rs b/testsuite/testcases/src/load_vs_perf_benchmark.rs
index e716713dc69f4..f75a69e7253ad 100644
--- a/testsuite/testcases/src/load_vs_perf_benchmark.rs
+++ b/testsuite/testcases/src/load_vs_perf_benchmark.rs
@@ -3,8 +3,9 @@
 
 use crate::NetworkLoadTest;
 use aptos_forge::{
-    args::TransactionTypeArg, EmitJobMode, EmitJobRequest, NetworkContext, NetworkTest, Result,
-    Test, TxnStats,
+    args::TransactionTypeArg,
+    success_criteria::{SuccessCriteria, SuccessCriteriaChecker},
+    EmitJobMode, EmitJobRequest, NetworkContext, NetworkTest, Result, Test, TxnStats,
 };
 use aptos_logger::info;
 use rand::SeedableRng;
@@ -84,8 +85,9 @@ impl Display for TransactionWorkload {
 }
 
 pub struct LoadVsPerfBenchmark {
-    pub test: &'static dyn NetworkLoadTest,
+    pub test: Box,
     pub workloads: Workloads,
+    pub criteria: Vec,
 }
 
 impl Test for LoadVsPerfBenchmark {
@@ -140,6 +142,13 @@ impl LoadVsPerfBenchmark {
 
 impl NetworkTest for LoadVsPerfBenchmark {
     fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> Result<()> {
+        assert!(
+            self.criteria.is_empty() || self.criteria.len() == self.workloads.len(),
+            "Invalid config, {} criteria and {} workloads given",
+            self.criteria.len(),
+            self.workloads.len(),
+        );
+
         let _runtime = Runtime::new().unwrap();
         let individual_with_buffer = ctx
             .global_duration
@@ -167,38 +176,65 @@ impl NetworkTest for LoadVsPerfBenchmark {
             // let mut aptos_info = ctx.swarm().aptos_public_info();
             // runtime.block_on(aptos_info.reconfig());
 
-            println!(
-                "{: <30} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12}",
-                "workload",
-                "submitted/s",
-                "committed/s",
-                "expired/s",
-                "rejected/s",
-                "chain txn/s",
-                "latency",
-                "p50 lat",
-                "p90 lat",
-                "p99 lat",
-                "actual dur"
-            );
-            for result in &results {
-                let rate = result.stats.rate();
-                println!(
-                    "{: <30} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12}",
-                    result.name,
-                    rate.submitted,
-                    rate.committed,
-                    rate.expired,
-                    rate.failed_submission,
-                    result.ledger_transactions / result.actual_duration.as_secs(),
-                    rate.latency,
-                    rate.p50_latency,
-                    rate.p90_latency,
-                    rate.p99_latency,
-                    result.actual_duration.as_secs()
-                )
+            let table = to_table(&results);
+            for line in table {
+                info!("{}", line);
+            }
+        }
+
+        let table = to_table(&results);
+        for line in table {
+            ctx.report.report_text(line);
+        }
+        for (index, result) in results.iter().enumerate() {
+            let rate = result.stats.rate();
+            if let Some(criteria) = self.criteria.get(index) {
+                SuccessCriteriaChecker::check_core_for_success(
+                    criteria,
+                    ctx.report,
+                    &rate,
+                    Some(result.name.clone()),
+                )?;
             }
         }
         Ok(())
     }
 }
+
+fn to_table(results: &[SingleRunStats]) -> Vec {
+    let mut table = Vec::new();
+    table.push(format!(
+        "{: <30} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12}",
+        "workload",
+        "submitted/s",
+        "committed/s",
+        "expired/s",
+        "rejected/s",
+        "chain txn/s",
+        "latency",
+        "p50 lat",
+        "p90 lat",
+        "p99 lat",
+        "actual dur"
+    ));
+
+    for result in results {
+        let rate = result.stats.rate();
+        table.push(format!(
+            "{: <30} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12} | {: <12}",
+            result.name,
+            rate.submitted,
+            rate.committed,
+            rate.expired,
+            rate.failed_submission,
+            result.ledger_transactions / result.actual_duration.as_secs(),
+            rate.latency,
+            rate.p50_latency,
+            rate.p90_latency,
+            rate.p99_latency,
+            result.actual_duration.as_secs()
+        ));
+    }
+
+    table
+}
diff --git a/testsuite/testcases/src/state_sync_performance.rs b/testsuite/testcases/src/state_sync_performance.rs
index c14af8e4f7cf7..8fbf771657790 100644
--- a/testsuite/testcases/src/state_sync_performance.rs
+++ b/testsuite/testcases/src/state_sync_performance.rs
@@ -361,7 +361,7 @@ fn ensure_state_sync_transaction_throughput(
     // TODO: we fetch the TPS requirement from the given success criteria.
     // But, we should probably make it more generic to avoid this.
     // Ensure we meet the success criteria.
-    let min_expected_tps = ctx.success_criteria.avg_tps as u64;
+    let min_expected_tps = ctx.success_criteria.min_avg_tps as u64;
     if state_sync_throughput < min_expected_tps {
         let error_message = format!(
             "State sync TPS requirement failed. Average TPS: {}, minimum required TPS: {}",
diff --git a/testsuite/testcases/src/two_traffics_test.rs b/testsuite/testcases/src/two_traffics_test.rs
index 33445364db473..1d52eb467d726 100644
--- a/testsuite/testcases/src/two_traffics_test.rs
+++ b/testsuite/testcases/src/two_traffics_test.rs
@@ -4,26 +4,17 @@
 use crate::{
     create_emitter_and_request, traffic_emitter_runtime, LoadDestination, NetworkLoadTest,
 };
-use anyhow::{bail, Ok};
 use aptos_forge::{
-    success_criteria::{LatencyType, SuccessCriteriaChecker},
-    EmitJobMode, EmitJobRequest, NetworkContext, NetworkTest, Result, Swarm, Test, TestReport,
-    TransactionType,
+    success_criteria::{SuccessCriteria, SuccessCriteriaChecker},
+    EmitJobRequest, NetworkContext, NetworkTest, Result, Swarm, Test, TestReport,
 };
 use aptos_logger::info;
 use rand::{rngs::OsRng, Rng, SeedableRng};
 use std::time::{Duration, Instant};
 
 pub struct TwoTrafficsTest {
-    // cannot have 'static EmitJobRequest, like below, so need to have inner fields
-    // pub inner_emit_job_request: EmitJobRequest,
-    pub inner_mode: EmitJobMode,
-    pub inner_gas_price: u64,
-    pub inner_init_gas_price_multiplier: u64,
-    pub inner_transaction_type: TransactionType,
-
-    pub avg_tps: usize,
-    pub latency_thresholds: &'static [(f32, LatencyType)],
+    pub inner_traffic: EmitJobRequest,
+    pub inner_success_criteria: SuccessCriteria,
 }
 
 impl Test for TwoTrafficsTest {
@@ -49,11 +40,7 @@ impl NetworkLoadTest for TwoTrafficsTest {
 
         let (emitter, emit_job_request) = create_emitter_and_request(
             swarm,
-            EmitJobRequest::default()
-                .mode(self.inner_mode.clone())
-                .gas_price(self.inner_gas_price)
-                .init_gas_price_multiplier(self.inner_init_gas_price_multiplier)
-                .transaction_type(self.inner_transaction_type),
+            self.inner_traffic.clone(),
             &nodes_to_send_load_to,
             rng,
         )?;
@@ -76,29 +63,15 @@ impl NetworkLoadTest for TwoTrafficsTest {
         );
 
         let rate = stats.rate();
-        info!("Inner traffic: {:?}", rate);
-
-        let avg_tps = rate.committed;
-        if avg_tps < self.avg_tps as u64 {
-            bail!(
-                "TPS requirement for inner traffic failed. Average TPS {}, minimum TPS requirement {}. Full inner stats: {:?}",
-                avg_tps,
-                self.avg_tps,
-                rate,
-            )
-        }
 
         report.report_txn_stats(format!("{}: inner traffic", self.name()), &stats);
 
-        SuccessCriteriaChecker::check_latency(
-            &self
-                .latency_thresholds
-                .iter()
-                .map(|(s, t)| (Duration::from_secs_f32(*s), t.clone()))
-                .collect::>(),
+        SuccessCriteriaChecker::check_core_for_success(
+            &self.inner_success_criteria,
+            report,
             &rate,
+            Some("inner traffic".to_string()),
         )?;
-
         Ok(())
     }
 }

From d14e596b3d08a6da6e0452a43cbd25decd254c2e Mon Sep 17 00:00:00 2001
From: Guoteng Rao <3603304+grao1991@users.noreply.github.com>
Date: Thu, 8 Jun 2023 23:54:19 -0700
Subject: [PATCH 124/200] [Storage][Sharding] Split ledger commit into multiple
 batches. (#8478)

---
 storage/aptosdb/src/backup/restore_utils.rs   |   3 +-
 storage/aptosdb/src/ledger_store/mod.rs       |  12 +-
 .../src/ledger_store/transaction_info_test.rs |  18 ++-
 storage/aptosdb/src/lib.rs                    | 119 ++++++++++++++----
 .../src/pruner/transaction_store/test.rs      |  13 +-
 storage/aptosdb/src/test_helper.rs            |   2 +-
 6 files changed, 133 insertions(+), 34 deletions(-)

diff --git a/storage/aptosdb/src/backup/restore_utils.rs b/storage/aptosdb/src/backup/restore_utils.rs
index 17b8164586284..5307b2be579ff 100644
--- a/storage/aptosdb/src/backup/restore_utils.rs
+++ b/storage/aptosdb/src/backup/restore_utils.rs
@@ -223,10 +223,11 @@ pub(crate) fn save_transactions_impl(
     state_kv_batches: &mut ShardedStateKvSchemaBatch,
     kv_replay: bool,
 ) -> Result<()> {
+    // TODO(grao): Support splited ledger db here.
     for (idx, txn) in txns.iter().enumerate() {
         transaction_store.put_transaction(first_version + idx as Version, txn, batch)?;
     }
-    ledger_store.put_transaction_infos(first_version, txn_infos, batch)?;
+    ledger_store.put_transaction_infos(first_version, txn_infos, batch, batch)?;
     event_store.put_events_multiple_versions(first_version, events, batch)?;
     // insert changes in write set schema batch
     for (idx, ws) in write_sets.iter().enumerate() {
diff --git a/storage/aptosdb/src/ledger_store/mod.rs b/storage/aptosdb/src/ledger_store/mod.rs
index a413843c61227..e471f0e801e99 100644
--- a/storage/aptosdb/src/ledger_store/mod.rs
+++ b/storage/aptosdb/src/ledger_store/mod.rs
@@ -288,13 +288,15 @@ impl LedgerStore {
         &self,
         first_version: u64,
         txn_infos: &[TransactionInfo],
-        batch: &SchemaBatch,
+        // TODO(grao): Consider split this function to two functions.
+        transaction_info_batch: &SchemaBatch,
+        transaction_accumulator_batch: &SchemaBatch,
     ) -> Result {
         // write txn_info
         (first_version..first_version + txn_infos.len() as u64)
             .zip_eq(txn_infos.iter())
             .try_for_each(|(version, txn_info)| {
-                batch.put::(&version, txn_info)
+                transaction_info_batch.put::(&version, txn_info)
             })?;
 
         // write hash of txn_info into the accumulator
@@ -304,9 +306,9 @@ impl LedgerStore {
             first_version, /* num_existing_leaves */
             &txn_hashes,
         )?;
-        writes
-            .iter()
-            .try_for_each(|(pos, hash)| batch.put::(pos, hash))?;
+        writes.iter().try_for_each(|(pos, hash)| {
+            transaction_accumulator_batch.put::(pos, hash)
+        })?;
         Ok(root_hash)
     }
 
diff --git a/storage/aptosdb/src/ledger_store/transaction_info_test.rs b/storage/aptosdb/src/ledger_store/transaction_info_test.rs
index 92c53a6070b4e..dd2f31875b26f 100644
--- a/storage/aptosdb/src/ledger_store/transaction_info_test.rs
+++ b/storage/aptosdb/src/ledger_store/transaction_info_test.rs
@@ -37,15 +37,27 @@ fn verify(
 }
 
 fn save(store: &LedgerStore, first_version: Version, txn_infos: &[TransactionInfo]) -> HashValue {
-    let batch = SchemaBatch::new();
+    let transaction_info_batch = SchemaBatch::new();
+    let transaction_accumulator_batch = SchemaBatch::new();
     let root_hash = store
-        .put_transaction_infos(first_version, txn_infos, &batch)
+        .put_transaction_infos(
+            first_version,
+            txn_infos,
+            &transaction_info_batch,
+            &transaction_accumulator_batch,
+        )
         .unwrap();
     store
         .ledger_db
         .transaction_info_db()
-        .write_schemas(batch)
+        .write_schemas(transaction_info_batch)
         .unwrap();
+    store
+        .ledger_db
+        .transaction_accumulator_db()
+        .write_schemas(transaction_accumulator_batch)
+        .unwrap();
+
     root_hash
 }
 
diff --git a/storage/aptosdb/src/lib.rs b/storage/aptosdb/src/lib.rs
index ac7db9bd2d6a4..d43f1741d0e91 100644
--- a/storage/aptosdb/src/lib.rs
+++ b/storage/aptosdb/src/lib.rs
@@ -277,6 +277,16 @@ impl Drop for RocksdbPropertyReporter {
     }
 }
 
+#[derive(Default)]
+struct LedgerSchemaBatches {
+    ledger_metadata_batch: SchemaBatch,
+    event_batch: SchemaBatch,
+    transaction_batch: SchemaBatch,
+    transaction_info_batch: SchemaBatch,
+    transaction_accumulator_batch: SchemaBatch,
+    write_set_batch: SchemaBatch,
+}
+
 /// This holds a handle to the underlying DB responsible for physical storage and provides APIs for
 /// access to the core Aptos data structures.
 pub struct AptosDB {
@@ -833,12 +843,13 @@ impl AptosDB {
         first_version: u64,
         expected_state_db_usage: StateStorageUsage,
         sharded_state_cache: Option<&ShardedStateCache>,
-    ) -> Result<(SchemaBatch, ShardedStateKvSchemaBatch, HashValue)> {
+    ) -> Result<(LedgerSchemaBatches, ShardedStateKvSchemaBatch, HashValue)> {
         let _timer = OTHER_TIMERS_SECONDS
             .with_label_values(&["save_transactions_impl"])
             .start_timer();
 
-        let ledger_batch = SchemaBatch::new();
+        let ledger_schema_batches = LedgerSchemaBatches::default();
+
         let sharded_state_kv_batches = new_sharded_kv_schema_batch();
 
         let last_version = first_version + txns_to_commit.len() as u64 - 1;
@@ -861,7 +872,7 @@ impl AptosDB {
                     first_version,
                     expected_state_db_usage,
                     sharded_state_cache,
-                    &ledger_batch,
+                    &ledger_schema_batches.ledger_metadata_batch,
                     &sharded_state_kv_batches,
                 )
             });
@@ -876,7 +887,7 @@ impl AptosDB {
                         self.event_store.put_events(
                             ver,
                             txn_to_commit.borrow().events(),
-                            &ledger_batch,
+                            &ledger_schema_batches.event_batch,
                         )
                     })
                     .collect::>>()
@@ -892,12 +903,12 @@ impl AptosDB {
                         self.transaction_store.put_transaction(
                             ver,
                             txn_to_commit.borrow().transaction(),
-                            &ledger_batch,
+                            &ledger_schema_batches.transaction_batch,
                         )?;
                         self.transaction_store.put_write_set(
                             ver,
                             txn_to_commit.borrow().write_set(),
-                            &ledger_batch,
+                            &ledger_schema_batches.write_set_batch,
                         )
                     },
                 )?;
@@ -907,14 +918,23 @@ impl AptosDB {
                     .map(|t| t.borrow().transaction_info())
                     .cloned()
                     .collect();
-                self.ledger_store
-                    .put_transaction_infos(first_version, &txn_infos, &ledger_batch)
+                self.ledger_store.put_transaction_infos(
+                    first_version,
+                    &txn_infos,
+                    &ledger_schema_batches.transaction_info_batch,
+                    &ledger_schema_batches.transaction_accumulator_batch,
+                )
             });
             t0.join().unwrap()?;
             t1.join().unwrap()?;
             t2.join().unwrap()
         });
-        Ok((ledger_batch, sharded_state_kv_batches, new_root_hash?))
+
+        Ok((
+            ledger_schema_batches,
+            sharded_state_kv_batches,
+            new_root_hash?,
+        ))
     }
 
     fn get_table_info_option(&self, handle: TableHandle) -> Result> {
@@ -995,7 +1015,7 @@ impl AptosDB {
     fn commit_ledger_and_state_kv_db(
         &self,
         last_version: Version,
-        ledger_batch: SchemaBatch,
+        ledger_schema_batches: LedgerSchemaBatches,
         sharded_state_kv_batches: ShardedStateKvSchemaBatch,
         new_root_hash: HashValue,
         ledger_info_with_sigs: Option<&LedgerInfoWithSignatures>,
@@ -1005,10 +1025,6 @@ impl AptosDB {
         let _timer = OTHER_TIMERS_SECONDS
             .with_label_values(&["save_transactions_commit"])
             .start_timer();
-        ledger_batch.put::(
-            &DbMetadataKey::LedgerCommitProgress,
-            &DbMetadataValue::Version(last_version),
-        )?;
 
         COMMIT_POOL.scope(|s| {
             // TODO(grao): Consider propagating the error instead of panic, if necessary.
@@ -1020,16 +1036,70 @@ impl AptosDB {
                     .commit(last_version, sharded_state_kv_batches)
                     .unwrap();
             });
-            // To the best of our current understanding, these tasks are scheduled in
-            // LIFO order, so put the ledger commit at the end since it's slower.
             s.spawn(|_| {
                 let _timer = OTHER_TIMERS_SECONDS
-                    .with_label_values(&["save_transactions_commit___ledger_commit"])
+                    .with_label_values(&["save_transactions_commit___ledger_metadata_commit"])
                     .start_timer();
-                // TODO(grao): Support splitted ledger DBs here.
+                ledger_schema_batches
+                    .ledger_metadata_batch
+                    .put::(
+                        &DbMetadataKey::LedgerCommitProgress,
+                        &DbMetadataValue::Version(last_version),
+                    )
+                    .unwrap();
                 self.ledger_db
                     .metadata_db()
-                    .write_schemas(ledger_batch)
+                    .write_schemas(ledger_schema_batches.ledger_metadata_batch)
+                    .unwrap();
+            });
+
+            // TODO(grao): Write progress for each of the following databases, and handle the
+            // inconsistency at the startup time.
+            s.spawn(|_| {
+                let _timer = OTHER_TIMERS_SECONDS
+                    .with_label_values(&["save_transactions_commit___event_commit"])
+                    .start_timer();
+                self.ledger_db
+                    .event_db()
+                    .write_schemas(ledger_schema_batches.event_batch)
+                    .unwrap();
+            });
+            s.spawn(|_| {
+                let _timer = OTHER_TIMERS_SECONDS
+                    .with_label_values(&["save_transactions_commit___write_set_commit"])
+                    .start_timer();
+                self.ledger_db
+                    .write_set_db()
+                    .write_schemas(ledger_schema_batches.write_set_batch)
+                    .unwrap();
+            });
+            s.spawn(|_| {
+                let _timer = OTHER_TIMERS_SECONDS
+                    .with_label_values(&["save_transactions_commit___transaction_commit"])
+                    .start_timer();
+                self.ledger_db
+                    .transaction_db()
+                    .write_schemas(ledger_schema_batches.transaction_batch)
+                    .unwrap();
+            });
+            s.spawn(|_| {
+                let _timer = OTHER_TIMERS_SECONDS
+                    .with_label_values(&["save_transactions_commit___transaction_info_commit"])
+                    .start_timer();
+                self.ledger_db
+                    .transaction_info_db()
+                    .write_schemas(ledger_schema_batches.transaction_info_batch)
+                    .unwrap();
+            });
+            s.spawn(|_| {
+                let _timer = OTHER_TIMERS_SECONDS
+                    .with_label_values(&[
+                        "save_transactions_commit___transaction_accumulator_commit",
+                    ])
+                    .start_timer();
+                self.ledger_db
+                    .transaction_accumulator_db()
+                    .write_schemas(ledger_schema_batches.transaction_accumulator_batch)
                     .unwrap();
             });
         });
@@ -1911,7 +1981,7 @@ impl DbWriter for AptosDB {
                 &latest_in_memory_state,
             )?;
 
-            let (ledger_batch, sharded_state_kv_batches, new_root_hash) = self
+            let (ledger_schema_batches, sharded_state_kv_batches, new_root_hash) = self
                 .save_transactions_impl(
                     txns_to_commit,
                     first_version,
@@ -1924,7 +1994,7 @@ impl DbWriter for AptosDB {
                 let last_version = first_version + txns_to_commit.len() as u64 - 1;
                 self.commit_ledger_and_state_kv_db(
                     last_version,
-                    ledger_batch,
+                    ledger_schema_batches,
                     sharded_state_kv_batches,
                     new_root_hash,
                     ledger_info_with_sigs,
@@ -1978,7 +2048,9 @@ impl DbWriter for AptosDB {
                 &latest_in_memory_state,
             )?;
 
-            let (ledger_batch, sharded_state_kv_batches, new_root_hash) = self
+            // TODO(grao): Schedule tasks in save_transactions_impl and
+            // commit_ledger_and_state_kv_db in a different way to make them more parallelizable.
+            let (ledger_schema_batches, sharded_state_kv_batches, new_root_hash) = self
                 .save_transactions_impl(
                     txns_to_commit,
                     first_version,
@@ -1989,9 +2061,10 @@ impl DbWriter for AptosDB {
             {
                 let mut buffered_state = self.state_store.buffered_state().lock();
                 let last_version = first_version + txns_to_commit.len() as u64 - 1;
+
                 self.commit_ledger_and_state_kv_db(
                     last_version,
-                    ledger_batch,
+                    ledger_schema_batches,
                     sharded_state_kv_batches,
                     new_root_hash,
                     ledger_info_with_sigs,
diff --git a/storage/aptosdb/src/pruner/transaction_store/test.rs b/storage/aptosdb/src/pruner/transaction_store/test.rs
index 084b76f66b363..da113075b5b27 100644
--- a/storage/aptosdb/src/pruner/transaction_store/test.rs
+++ b/storage/aptosdb/src/pruner/transaction_store/test.rs
@@ -246,14 +246,25 @@ fn put_txn_in_store(
         .write_schemas(transaction_batch)
         .unwrap();
     let transaction_info_batch = SchemaBatch::new();
+    let transaction_accumulator_batch = SchemaBatch::new();
     ledger_store
-        .put_transaction_infos(0, txn_infos, &transaction_info_batch)
+        .put_transaction_infos(
+            0,
+            txn_infos,
+            &transaction_info_batch,
+            &transaction_accumulator_batch,
+        )
         .unwrap();
     aptos_db
         .ledger_db
         .transaction_info_db()
         .write_schemas(transaction_info_batch)
         .unwrap();
+    aptos_db
+        .ledger_db
+        .transaction_accumulator_db()
+        .write_schemas(transaction_accumulator_batch)
+        .unwrap();
 }
 
 fn verify_transaction_in_transaction_store(
diff --git a/storage/aptosdb/src/test_helper.rs b/storage/aptosdb/src/test_helper.rs
index 2b33189e03064..f0d9f1eefd5bc 100644
--- a/storage/aptosdb/src/test_helper.rs
+++ b/storage/aptosdb/src/test_helper.rs
@@ -868,7 +868,7 @@ pub fn verify_committed_transactions(
 pub fn put_transaction_info(db: &AptosDB, version: Version, txn_info: &TransactionInfo) {
     let batch = SchemaBatch::new();
     db.ledger_store
-        .put_transaction_infos(version, &[txn_info.clone()], &batch)
+        .put_transaction_infos(version, &[txn_info.clone()], &batch, &batch)
         .unwrap();
     db.ledger_db.transaction_db().write_schemas(batch).unwrap();
 }

From e95ef24f1d0ac908593c4e9840aa31f787b48585 Mon Sep 17 00:00:00 2001
From: "Daniel Porteous (dport)" 
Date: Fri, 9 Jun 2023 16:17:01 +0100
Subject: [PATCH 125/200] Revert "Revert "[CLI] Add customer header checking to
 e2e (#8460)" (#8496)" (#8517)

This reverts commit 56aee8ba47c1f0dbd4ad8cd11bfc1fc3eddd7d8e.
---
 crates/aptos/e2e/cases/init.py | 9 +++++++++
 crates/aptos/e2e/main.py       | 5 ++++-
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/crates/aptos/e2e/cases/init.py b/crates/aptos/e2e/cases/init.py
index 39ebf830c9c17..096e628ada6ad 100644
--- a/crates/aptos/e2e/cases/init.py
+++ b/crates/aptos/e2e/cases/init.py
@@ -51,3 +51,12 @@ def test_metrics_accessible(run_helper: RunHelper, test_name=None):
     # JSON this will throw an exception which will be caught as a test failure.
     metrics_url = run_helper.get_metrics_url(json=True)
     requests.get(metrics_url).json()
+
+
+@test_case
+def test_aptos_header_included(run_helper: RunHelper, test_name=None):
+    # Make sure the aptos-cli header is included on the original request
+    response = requests.get(run_helper.get_metrics_url())
+
+    if 'request_source_client="aptos-cli' not in response.text:
+        raise TestError("Request should contain the correct aptos header: aptos-cli")
diff --git a/crates/aptos/e2e/main.py b/crates/aptos/e2e/main.py
index 040262871efc1..07461283c7e22 100644
--- a/crates/aptos/e2e/main.py
+++ b/crates/aptos/e2e/main.py
@@ -34,7 +34,7 @@
     test_account_fund_with_faucet,
     test_account_lookup_address,
 )
-from cases.init import test_init, test_metrics_accessible
+from cases.init import test_aptos_header_included, test_init, test_metrics_accessible
 from common import Network
 from local_testnet import run_node, stop_node, wait_for_startup
 from test_helpers import RunHelper
@@ -111,6 +111,9 @@ def run_tests(run_helper):
     test_account_create(run_helper)
     test_account_lookup_address(run_helper)
 
+    # Make sure the aptos-cli header is included on the original request
+    test_aptos_header_included(run_helper)
+
 
 def main():
     args = parse_args()

From 455ef1c19a32f828f493e3d30830128b6ac75288 Mon Sep 17 00:00:00 2001
From: "Daniel Porteous (dport)" 
Date: Fri, 9 Jun 2023 16:40:58 +0100
Subject: [PATCH 126/200] [CLI][E2E] Improve reliability of framework, checkout
 correct code in CI (#8588)

---
 .github/workflows/cli-e2e-tests.yaml     |  2 ++
 .github/workflows/docker-build-test.yaml |  4 +--
 crates/aptos/e2e/main.py                 | 44 ++++++++++++++----------
 crates/aptos/e2e/test_helpers.py         | 12 +++++--
 4 files changed, 39 insertions(+), 23 deletions(-)

diff --git a/.github/workflows/cli-e2e-tests.yaml b/.github/workflows/cli-e2e-tests.yaml
index 066e582f80d18..e71476396b751 100644
--- a/.github/workflows/cli-e2e-tests.yaml
+++ b/.github/workflows/cli-e2e-tests.yaml
@@ -24,6 +24,8 @@ jobs:
       id-token: write
     steps:
       - uses: actions/checkout@v3
+        with:
+          ref: ${{ env.GIT_SHA }}
 
       - uses: aptos-labs/aptos-core/.github/actions/docker-setup@main
         with:
diff --git a/.github/workflows/docker-build-test.yaml b/.github/workflows/docker-build-test.yaml
index f6c50e8c0f417..3764a3f094af0 100644
--- a/.github/workflows/docker-build-test.yaml
+++ b/.github/workflows/docker-build-test.yaml
@@ -187,14 +187,14 @@ jobs:
   cli-e2e-tests:
     needs: [permission-check, rust-images, determine-docker-build-metadata] # runs with the default release docker build variant "rust-images"
     if: |
-      !contains(github.event.pull_request.labels.*.name, 'CICD:skip-sdk-integration-test') && (
+      (
         github.event_name == 'push' ||
         github.event_name == 'workflow_dispatch' ||
         contains(github.event.pull_request.labels.*.name, 'CICD:run-e2e-tests') ||
         github.event.pull_request.auto_merge != null) ||
         contains(github.event.pull_request.body, '#e2e'
       )
-    uses: ./.github/workflows/cli-e2e-tests.yaml
+    uses: aptos-labs/aptos-core/.github/workflows/cli-e2e-tests.yaml@main
     secrets: inherit
     with:
       GIT_SHA: ${{ needs.determine-docker-build-metadata.outputs.gitSha }}
diff --git a/crates/aptos/e2e/main.py b/crates/aptos/e2e/main.py
index 07461283c7e22..5403d01473382 100644
--- a/crates/aptos/e2e/main.py
+++ b/crates/aptos/e2e/main.py
@@ -124,30 +124,36 @@ def main():
     else:
         logging.getLogger().setLevel(logging.INFO)
 
-    # Run a node + faucet and wait for them to start up.
-    container_name = run_node(args.base_network, args.image_repo_with_project)
-    wait_for_startup(container_name, args.base_startup_timeout)
-
     # Create the dir the test CLI will run from.
     shutil.rmtree(args.working_directory, ignore_errors=True)
     pathlib.Path(args.working_directory).mkdir(parents=True, exist_ok=True)
 
-    # Build the RunHelper object.
-    run_helper = RunHelper(
-        host_working_directory=args.working_directory,
-        image_repo_with_project=args.image_repo_with_project,
-        image_tag=args.test_cli_tag,
-        cli_path=args.test_cli_path,
-    )
-
-    # Prepare the run helper. This ensures in advance that everything needed is there.
-    run_helper.prepare()
-
-    # Run tests.
-    run_tests(run_helper)
+    # Run a node + faucet and wait for them to start up.
+    container_name = run_node(args.base_network, args.image_repo_with_project)
 
-    # Stop the node + faucet.
-    stop_node(container_name)
+    # We run these in a try finally so that if something goes wrong, such as the
+    # local testnet not starting up correctly or some unexpected error in the
+    # test framework, we still stop the node + faucet.
+    try:
+        wait_for_startup(container_name, args.base_startup_timeout)
+
+        # Build the RunHelper object.
+        run_helper = RunHelper(
+            host_working_directory=args.working_directory,
+            image_repo_with_project=args.image_repo_with_project,
+            image_tag=args.test_cli_tag,
+            cli_path=args.test_cli_path,
+            base_network=args.base_network,
+        )
+
+        # Prepare the run helper. This ensures in advance that everything needed is there.
+        run_helper.prepare()
+
+        # Run tests.
+        run_tests(run_helper)
+    finally:
+        # Stop the node + faucet.
+        stop_node(container_name)
 
     # Print out the results.
     if test_results.passed:
diff --git a/crates/aptos/e2e/test_helpers.py b/crates/aptos/e2e/test_helpers.py
index 750eb9c251dbe..b668d2682589b 100644
--- a/crates/aptos/e2e/test_helpers.py
+++ b/crates/aptos/e2e/test_helpers.py
@@ -9,7 +9,7 @@
 from dataclasses import dataclass
 
 from aptos_sdk.client import RestClient
-from common import METRICS_PORT, NODE_PORT, AccountInfo, build_image_name
+from common import METRICS_PORT, NODE_PORT, AccountInfo, Network, build_image_name
 
 LOG = logging.getLogger(__name__)
 
@@ -23,13 +23,20 @@ class RunHelper:
     image_repo_with_project: str
     image_tag: str
     cli_path: str
+    base_network: Network
+
     test_count: int
 
     # This can be used by the tests to query the local testnet node.
     api_client: RestClient
 
     def __init__(
-        self, host_working_directory, image_repo_with_project, image_tag, cli_path
+        self,
+        host_working_directory,
+        image_repo_with_project,
+        image_tag,
+        cli_path,
+        base_network,
     ):
         if image_tag and cli_path:
             raise RuntimeError("Cannot specify both image_tag and cli_path")
@@ -39,6 +46,7 @@ def __init__(
         self.image_repo_with_project = image_repo_with_project
         self.image_tag = image_tag
         self.cli_path = os.path.abspath(cli_path) if cli_path else cli_path
+        self.base_network = base_network
         self.test_count = 0
         self.api_client = RestClient(f"http://127.0.0.1:{NODE_PORT}/v1")
 

From 3b8913b2bed1d5cc5dba9591ad00187380a112e5 Mon Sep 17 00:00:00 2001
From: Sital Kedia 
Date: Fri, 9 Jun 2023 08:48:00 -0700
Subject: [PATCH 127/200] [Sharding] [ Execution] Remote Executor service
 support (#8545)

---
 Cargo.lock                                    |  25 ++
 Cargo.toml                                    |   2 +
 .../aptos-transaction-benchmarks/Cargo.toml   |   1 +
 .../aptos-transaction-benchmarks/src/main.rs  |  10 +-
 .../src/transactions.rs                       |  31 ++-
 aptos-move/aptos-vm/src/block_executor/mod.rs |   1 -
 .../block_executor_client.rs                  |  62 +++++
 .../sharded_block_executor/executor_shard.rs  |  29 +--
 .../src/sharded_block_executor/mod.rs         |  28 ++-
 aptos-move/e2e-tests/src/data_store.rs        |   6 +-
 aptos-move/e2e-tests/src/executor.rs          |   4 +
 execution/executor-service/Cargo.toml         |  32 +++
 execution/executor-service/src/error.rs       |  27 +++
 execution/executor-service/src/lib.rs         |  38 +++
 execution/executor-service/src/main.rs        |  25 ++
 .../src/process_executor_service.rs           |  54 +++++
 .../src/remote_executor_client.rs             |  75 ++++++
 .../src/remote_executor_service.rs            | 224 ++++++++++++++++++
 .../src/thread_executor_service.rs            |  62 +++++
 execution/executor/Cargo.toml                 |   1 +
 .../executor/src/components/chunk_output.rs   |  12 +-
 .../state-view/src/in_memory_state_view.rs    |  43 ++++
 storage/state-view/src/lib.rs                 |  10 +-
 23 files changed, 757 insertions(+), 45 deletions(-)
 create mode 100644 aptos-move/aptos-vm/src/sharded_block_executor/block_executor_client.rs
 create mode 100644 execution/executor-service/Cargo.toml
 create mode 100644 execution/executor-service/src/error.rs
 create mode 100644 execution/executor-service/src/lib.rs
 create mode 100644 execution/executor-service/src/main.rs
 create mode 100644 execution/executor-service/src/process_executor_service.rs
 create mode 100644 execution/executor-service/src/remote_executor_client.rs
 create mode 100644 execution/executor-service/src/remote_executor_service.rs
 create mode 100644 execution/executor-service/src/thread_executor_service.rs
 create mode 100644 storage/state-view/src/in_memory_state_view.rs

diff --git a/Cargo.lock b/Cargo.lock
index 455ab65f742d9..c81d6ccd5edce 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1038,6 +1038,7 @@ dependencies = [
  "fail 0.5.0",
  "itertools",
  "move-core-types",
+ "num_cpus",
  "once_cell",
  "proptest",
  "rand 0.7.3",
@@ -1088,6 +1089,29 @@ dependencies = [
  "toml 0.5.9",
 ]
 
+[[package]]
+name = "aptos-executor-service"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "aptos-config",
+ "aptos-crypto",
+ "aptos-executor-types",
+ "aptos-language-e2e-tests",
+ "aptos-logger",
+ "aptos-retrier",
+ "aptos-secure-net",
+ "aptos-state-view",
+ "aptos-types",
+ "aptos-vm",
+ "bcs 0.1.4",
+ "clap 3.2.23",
+ "itertools",
+ "serde 1.0.149",
+ "serde_json",
+ "thiserror",
+]
+
 [[package]]
 name = "aptos-executor-test-helpers"
 version = "0.1.0"
@@ -3159,6 +3183,7 @@ version = "0.1.0"
 dependencies = [
  "aptos-bitvec",
  "aptos-crypto",
+ "aptos-executor-service",
  "aptos-gas",
  "aptos-language-e2e-tests",
  "aptos-logger",
diff --git a/Cargo.toml b/Cargo.toml
index f297ab54bd82f..ba32a6fad3c61 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -104,6 +104,7 @@ members = [
     "execution/db-bootstrapper",
     "execution/executor",
     "execution/executor-benchmark",
+    "execution/executor-service",
     "execution/executor-test-helpers",
     "execution/executor-types",
     "mempool",
@@ -276,6 +277,7 @@ aptos-event-notifications = { path = "state-sync/inter-component/event-notificat
 aptos-executable-store = { path = "storage/executable-store" }
 aptos-executor = { path = "execution/executor" }
 aptos-block-partitioner = { path = "execution/block-partitioner" }
+aptos-executor-service = { path = "execution/executor-service" }
 aptos-executor-test-helpers = { path = "execution/executor-test-helpers" }
 aptos-executor-types = { path = "execution/executor-types" }
 aptos-faucet-cli = { path = "crates/aptos-faucet/cli" }
diff --git a/aptos-move/aptos-transaction-benchmarks/Cargo.toml b/aptos-move/aptos-transaction-benchmarks/Cargo.toml
index 26553f2b7f7e3..65991ae4c701e 100644
--- a/aptos-move/aptos-transaction-benchmarks/Cargo.toml
+++ b/aptos-move/aptos-transaction-benchmarks/Cargo.toml
@@ -15,6 +15,7 @@ rust-version = { workspace = true }
 [dependencies]
 aptos-bitvec = { workspace = true }
 aptos-crypto = { workspace = true }
+aptos-executor-service = { workspace = true }
 aptos-gas = { workspace = true, features = ["testing"] }
 aptos-language-e2e-tests = { workspace = true }
 aptos-logger = { workspace = true }
diff --git a/aptos-move/aptos-transaction-benchmarks/src/main.rs b/aptos-move/aptos-transaction-benchmarks/src/main.rs
index 022493cac8535..5c3dbde34ecc3 100755
--- a/aptos-move/aptos-transaction-benchmarks/src/main.rs
+++ b/aptos-move/aptos-transaction-benchmarks/src/main.rs
@@ -9,7 +9,10 @@ use aptos_push_metrics::MetricsPusher;
 use aptos_transaction_benchmarks::transactions::TransactionBencher;
 use clap::{Parser, Subcommand};
 use proptest::prelude::*;
-use std::time::{SystemTime, UNIX_EPOCH};
+use std::{
+    net::SocketAddr,
+    time::{SystemTime, UNIX_EPOCH},
+};
 
 /// This is needed for filters on the Grafana dashboard working as its used to populate the filter
 /// variables.
@@ -72,6 +75,9 @@ struct ExecuteOpt {
     #[clap(long, default_value = "1")]
     pub num_executor_shards: usize,
 
+    #[clap(long, min_values = 1, conflicts_with = "num_executor_shards")]
+    pub remote_executor_addresses: Option>,
+
     #[clap(long, default_value = "true")]
     pub no_conflict_txns: bool,
 
@@ -109,6 +115,7 @@ fn param_sweep(opt: ParamSweepOpt) {
                 opt.num_runs,
                 1,
                 concurrency_level,
+                None,
                 false,
                 maybe_block_gas_limit,
             );
@@ -170,6 +177,7 @@ fn execute(opt: ExecuteOpt) {
         opt.num_blocks,
         opt.num_executor_shards,
         opt.concurrency_level_per_shard,
+        opt.remote_executor_addresses,
         opt.no_conflict_txns,
         opt.maybe_block_gas_limit,
     );
diff --git a/aptos-move/aptos-transaction-benchmarks/src/transactions.rs b/aptos-move/aptos-transaction-benchmarks/src/transactions.rs
index a1ce63d35f2ef..133cce21ebd68 100644
--- a/aptos-move/aptos-transaction-benchmarks/src/transactions.rs
+++ b/aptos-move/aptos-transaction-benchmarks/src/transactions.rs
@@ -4,6 +4,7 @@
 
 use aptos_bitvec::BitVec;
 use aptos_crypto::HashValue;
+use aptos_executor_service::remote_executor_client::RemoteExecutorClient;
 use aptos_language_e2e_tests::{
     account_universe::{AUTransactionGen, AccountPickStyle, AccountUniverse, AccountUniverseGen},
     data_store::FakeDataStore,
@@ -15,14 +16,17 @@ use aptos_types::{
     on_chain_config::{OnChainConfig, ValidatorSet},
     transaction::Transaction,
 };
-use aptos_vm::{data_cache::AsMoveResolver, sharded_block_executor::ShardedBlockExecutor};
+use aptos_vm::{
+    data_cache::AsMoveResolver,
+    sharded_block_executor::{block_executor_client::LocalExecutorClient, ShardedBlockExecutor},
+};
 use criterion::{measurement::Measurement, BatchSize, Bencher};
 use proptest::{
     collection::vec,
     strategy::{Strategy, ValueTree},
     test_runner::TestRunner,
 };
-use std::{sync::Arc, time::Instant};
+use std::{net::SocketAddr, sync::Arc, time::Instant};
 
 /// Benchmarking support for transactions.
 #[derive(Clone)]
@@ -72,6 +76,7 @@ where
                     self.num_accounts,
                     self.num_transactions,
                     1,
+                    None,
                     AccountPickStyle::Unlimited,
                 )
             },
@@ -90,6 +95,7 @@ where
                     self.num_accounts,
                     self.num_transactions,
                     1,
+                    None,
                     AccountPickStyle::Unlimited,
                 )
             },
@@ -110,6 +116,7 @@ where
         num_runs: usize,
         num_executor_shards: usize,
         concurrency_level_per_shard: usize,
+        remote_executor_addresses: Option>,
         no_conflict_txn: bool,
         maybe_block_gas_limit: Option,
     ) -> (Vec, Vec) {
@@ -135,6 +142,7 @@ where
             num_accounts,
             num_txn,
             num_executor_shards,
+            remote_executor_addresses,
             account_pick_style,
         );
 
@@ -186,6 +194,7 @@ where
         num_accounts: usize,
         num_transactions: usize,
         num_executor_shards: usize,
+        remote_executor_addresses: Option>,
         account_pick_style: AccountPickStyle,
     ) -> Self {
         Self::with_universe(
@@ -193,6 +202,7 @@ where
             universe_strategy(num_accounts, num_transactions, account_pick_style),
             num_transactions,
             num_executor_shards,
+            remote_executor_addresses,
         )
     }
 
@@ -203,6 +213,7 @@ where
         universe_strategy: impl Strategy,
         num_transactions: usize,
         num_executor_shards: usize,
+        remote_executor_addresses: Option>,
     ) -> Self {
         let mut runner = TestRunner::default();
         let universe_gen = universe_strategy
@@ -218,8 +229,20 @@ where
 
         let state_view = Arc::new(executor.get_state_view().clone());
         let parallel_block_executor =
-            Arc::new(ShardedBlockExecutor::new(num_executor_shards, None));
-        let sequential_block_executor = Arc::new(ShardedBlockExecutor::new(1, Some(1)));
+            if let Some(remote_executor_addresses) = remote_executor_addresses {
+                let remote_executor_clients = remote_executor_addresses
+                    .into_iter()
+                    .map(|addr| RemoteExecutorClient::new(addr, 10000))
+                    .collect::>();
+                Arc::new(ShardedBlockExecutor::new(remote_executor_clients))
+            } else {
+                let local_executor_client =
+                    LocalExecutorClient::create_local_clients(num_executor_shards, None);
+                Arc::new(ShardedBlockExecutor::new(local_executor_client))
+            };
+        let sequential_executor_client = LocalExecutorClient::create_local_clients(1, Some(1));
+        let sequential_block_executor =
+            Arc::new(ShardedBlockExecutor::new(sequential_executor_client));
 
         let validator_set = ValidatorSet::fetch_config(
             &FakeExecutor::from_head_genesis()
diff --git a/aptos-move/aptos-vm/src/block_executor/mod.rs b/aptos-move/aptos-vm/src/block_executor/mod.rs
index 0b9596886f11a..e1c8d68f959e1 100644
--- a/aptos-move/aptos-vm/src/block_executor/mod.rs
+++ b/aptos-move/aptos-vm/src/block_executor/mod.rs
@@ -176,7 +176,6 @@ impl BlockAptosVM {
         );
 
         let ret = executor.execute_block(state_view, signature_verified_block, state_view);
-
         match ret {
             Ok(outputs) => {
                 let output_vec: Vec = outputs
diff --git a/aptos-move/aptos-vm/src/sharded_block_executor/block_executor_client.rs b/aptos-move/aptos-vm/src/sharded_block_executor/block_executor_client.rs
new file mode 100644
index 0000000000000..289aeb4730471
--- /dev/null
+++ b/aptos-move/aptos-vm/src/sharded_block_executor/block_executor_client.rs
@@ -0,0 +1,62 @@
+// Copyright © Aptos Foundation
+
+use crate::block_executor::BlockAptosVM;
+use aptos_state_view::StateView;
+use aptos_types::transaction::{Transaction, TransactionOutput};
+use move_core_types::vm_status::VMStatus;
+use std::sync::Arc;
+
+pub trait BlockExecutorClient {
+    fn execute_block(
+        &self,
+        transactions: Vec,
+        state_view: &S,
+        concurrency_level: usize,
+        maybe_block_gas_limit: Option,
+    ) -> Result, VMStatus>;
+}
+
+impl BlockExecutorClient for LocalExecutorClient {
+    fn execute_block(
+        &self,
+        transactions: Vec,
+        state_view: &S,
+        concurrency_level: usize,
+        maybe_block_gas_limit: Option,
+    ) -> Result, VMStatus> {
+        BlockAptosVM::execute_block(
+            self.executor_thread_pool.clone(),
+            transactions,
+            state_view,
+            concurrency_level,
+            maybe_block_gas_limit,
+        )
+    }
+}
+
+pub struct LocalExecutorClient {
+    executor_thread_pool: Arc,
+}
+
+impl LocalExecutorClient {
+    pub fn new(num_threads: usize) -> Self {
+        let executor_thread_pool = Arc::new(
+            rayon::ThreadPoolBuilder::new()
+                .num_threads(num_threads)
+                .build()
+                .unwrap(),
+        );
+
+        Self {
+            executor_thread_pool,
+        }
+    }
+
+    pub fn create_local_clients(num_shards: usize, num_threads: Option) -> Vec {
+        let num_threads = num_threads
+            .unwrap_or_else(|| (num_cpus::get() as f64 / num_shards as f64).ceil() as usize);
+        (0..num_shards)
+            .map(|_| LocalExecutorClient::new(num_threads))
+            .collect()
+    }
+}
diff --git a/aptos-move/aptos-vm/src/sharded_block_executor/executor_shard.rs b/aptos-move/aptos-vm/src/sharded_block_executor/executor_shard.rs
index 2f3d5b427a6b0..db525cadacb4a 100644
--- a/aptos-move/aptos-vm/src/sharded_block_executor/executor_shard.rs
+++ b/aptos-move/aptos-vm/src/sharded_block_executor/executor_shard.rs
@@ -2,41 +2,33 @@
 // Parts of the project are originally copyright © Meta Platforms, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-use crate::{block_executor::BlockAptosVM, sharded_block_executor::ExecutorShardCommand};
+use crate::sharded_block_executor::{
+    block_executor_client::BlockExecutorClient, ExecutorShardCommand,
+};
 use aptos_logger::trace;
 use aptos_state_view::StateView;
 use aptos_types::transaction::TransactionOutput;
 use aptos_vm_logging::disable_speculative_logging;
 use move_core_types::vm_status::VMStatus;
-use std::sync::{
-    mpsc::{Receiver, Sender},
-    Arc,
-};
+use std::sync::mpsc::{Receiver, Sender};
 
 /// A remote block executor that receives transactions from a channel and executes them in parallel.
 /// Currently it runs in the local machine and it will be further extended to run in a remote machine.
-pub struct ExecutorShard {
+pub struct ExecutorShard {
     shard_id: usize,
-    executor_thread_pool: Arc,
+    executor_client: E,
     command_rx: Receiver>,
     result_tx: Sender, VMStatus>>,
 }
 
-impl ExecutorShard {
+impl ExecutorShard {
     pub fn new(
         num_executor_shards: usize,
+        executor_client: E,
         shard_id: usize,
-        num_executor_threads: usize,
         command_rx: Receiver>,
         result_tx: Sender, VMStatus>>,
     ) -> Self {
-        let executor_thread_pool = Arc::new(
-            rayon::ThreadPoolBuilder::new()
-                .num_threads(num_executor_threads)
-                .build()
-                .unwrap(),
-        );
-
         if num_executor_shards > 1 {
             // todo: speculative logging is not yet compatible with sharded block executor.
             disable_speculative_logging();
@@ -44,7 +36,7 @@ impl ExecutorShard {
 
         Self {
             shard_id,
-            executor_thread_pool,
+            executor_client,
             command_rx,
             result_tx,
         }
@@ -65,8 +57,7 @@ impl ExecutorShard {
                         self.shard_id,
                         transactions.len()
                     );
-                    let ret = BlockAptosVM::execute_block(
-                        self.executor_thread_pool.clone(),
+                    let ret = self.executor_client.execute_block(
                         transactions,
                         state_view.as_ref(),
                         concurrency_level_per_shard,
diff --git a/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs b/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs
index 5bd0b0fb4b986..7efd7f9578b17 100644
--- a/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs
+++ b/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs
@@ -7,6 +7,7 @@ use aptos_block_partitioner::{BlockPartitioner, UniformPartitioner};
 use aptos_logger::{error, info, trace};
 use aptos_state_view::StateView;
 use aptos_types::transaction::{Transaction, TransactionOutput};
+use block_executor_client::BlockExecutorClient;
 use move_core_types::vm_status::VMStatus;
 use std::{
     marker::PhantomData,
@@ -17,6 +18,7 @@ use std::{
     thread,
 };
 
+pub mod block_executor_client;
 mod executor_shard;
 
 /// A wrapper around sharded block executors that manages multiple shards and aggregates the results.
@@ -29,36 +31,33 @@ pub struct ShardedBlockExecutor {
     phantom: PhantomData,
 }
 
-pub enum ExecutorShardCommand {
+pub enum ExecutorShardCommand {
     ExecuteBlock(Arc, Vec, usize, Option),
     Stop,
 }
 
 impl ShardedBlockExecutor {
-    pub fn new(num_executor_shards: usize, executor_threads_per_shard: Option) -> Self {
-        assert!(num_executor_shards > 0, "num_executor_shards must be > 0");
-        let executor_threads_per_shard = executor_threads_per_shard.unwrap_or_else(|| {
-            (num_cpus::get() as f64 / num_executor_shards as f64).ceil() as usize
-        });
+    pub fn new(executor_clients: Vec) -> Self {
         let mut command_txs = vec![];
         let mut result_rxs = vec![];
         let mut shard_join_handles = vec![];
-        for i in 0..num_executor_shards {
+        let num_executor_shards = executor_clients.len();
+        for (i, executor_client) in executor_clients.into_iter().enumerate() {
             let (transactions_tx, transactions_rx) = std::sync::mpsc::channel();
             let (result_tx, result_rx) = std::sync::mpsc::channel();
             command_txs.push(transactions_tx);
             result_rxs.push(result_rx);
             shard_join_handles.push(spawn_executor_shard(
                 num_executor_shards,
+                executor_client,
                 i,
-                executor_threads_per_shard,
                 transactions_rx,
                 result_tx,
             ));
         }
         info!(
-            "Creating a new ShardedBlockExecutor with {} shards and concurrency per shard {}",
-            num_executor_shards, executor_threads_per_shard
+            "Creating a new ShardedBlockExecutor with {} shards",
+            num_executor_shards
         );
         Self {
             num_executor_shards,
@@ -123,10 +122,13 @@ impl Drop for ShardedBlockExecutor {
     }
 }
 
-fn spawn_executor_shard(
+fn spawn_executor_shard<
+    S: StateView + Sync + Send + 'static,
+    E: BlockExecutorClient + Sync + Send + 'static,
+>(
     num_executor_shards: usize,
+    executor_client: E,
     shard_id: usize,
-    concurrency_level: usize,
     command_rx: Receiver>,
     result_tx: Sender, VMStatus>>,
 ) -> thread::JoinHandle<()> {
@@ -136,8 +138,8 @@ fn spawn_executor_shard(
         .spawn(move || {
             let executor_shard = ExecutorShard::new(
                 num_executor_shards,
+                executor_client,
                 shard_id,
-                concurrency_level,
                 command_rx,
                 result_tx,
             );
diff --git a/aptos-move/e2e-tests/src/data_store.rs b/aptos-move/e2e-tests/src/data_store.rs
index b0571e3daaabd..d68f2cd6a9b4f 100644
--- a/aptos-move/e2e-tests/src/data_store.rs
+++ b/aptos-move/e2e-tests/src/data_store.rs
@@ -6,7 +6,7 @@
 
 use crate::account::AccountData;
 use anyhow::Result;
-use aptos_state_view::TStateView;
+use aptos_state_view::{in_memory_state_view::InMemoryStateView, TStateView};
 use aptos_types::{
     access_path::AccessPath,
     account_config::CoinInfoResource,
@@ -133,6 +133,10 @@ impl TStateView for FakeDataStore {
         }
         Ok(usage)
     }
+
+    fn as_in_memory_state_view(&self) -> InMemoryStateView {
+        InMemoryStateView::new(self.state_data.clone())
+    }
 }
 
 // This is used by aggregator tests.
diff --git a/aptos-move/e2e-tests/src/executor.rs b/aptos-move/e2e-tests/src/executor.rs
index 20e6be81d52cc..1277113e8632f 100644
--- a/aptos-move/e2e-tests/src/executor.rs
+++ b/aptos-move/e2e-tests/src/executor.rs
@@ -162,6 +162,10 @@ impl FakeExecutor {
         )
     }
 
+    pub fn data_store(&self) -> &FakeDataStore {
+        &self.data_store
+    }
+
     /// Creates an executor in which no genesis state has been applied yet.
     pub fn no_genesis() -> Self {
         let executor_thread_pool = Arc::new(
diff --git a/execution/executor-service/Cargo.toml b/execution/executor-service/Cargo.toml
new file mode 100644
index 0000000000000..7fcddb11b8db9
--- /dev/null
+++ b/execution/executor-service/Cargo.toml
@@ -0,0 +1,32 @@
+[package]
+name = "aptos-executor-service"
+description = "Aptos executor service"
+version = "0.1.0"
+
+# Workspace inherited keys
+authors = { workspace = true }
+edition = { workspace = true }
+homepage = { workspace = true }
+license = { workspace = true }
+publish = { workspace = true }
+repository = { workspace = true }
+rust-version = { workspace = true }
+
+[dependencies]
+anyhow = { workspace = true }
+aptos-config = { workspace = true }
+aptos-crypto = { workspace = true }
+aptos-executor-types = { workspace = true }
+aptos-language-e2e-tests = { workspace = true }
+aptos-logger = { workspace = true }
+aptos-retrier = { workspace = true }
+aptos-secure-net = { workspace = true }
+aptos-state-view = { workspace = true }
+aptos-types = { workspace = true }
+aptos-vm = { workspace = true }
+bcs = { workspace = true }
+clap = { workspace = true }
+itertools = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
diff --git a/execution/executor-service/src/error.rs b/execution/executor-service/src/error.rs
new file mode 100644
index 0000000000000..6901536f863cf
--- /dev/null
+++ b/execution/executor-service/src/error.rs
@@ -0,0 +1,27 @@
+// Copyright © Aptos Foundation
+// Parts of the project are originally copyright © Meta Platforms, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+use serde::{Deserialize, Serialize};
+use thiserror::Error;
+
+#[derive(Clone, Debug, Deserialize, Error, PartialEq, Eq, Serialize)]
+/// Different reasons for executor service fails to execute a block.
+pub enum Error {
+    #[error("Internal error: {0}")]
+    InternalError(String),
+    #[error("Serialization error: {0}")]
+    SerializationError(String),
+}
+
+impl From for Error {
+    fn from(error: bcs::Error) -> Self {
+        Self::SerializationError(format!("{}", error))
+    }
+}
+
+impl From for Error {
+    fn from(error: aptos_secure_net::Error) -> Self {
+        Self::InternalError(error.to_string())
+    }
+}
diff --git a/execution/executor-service/src/lib.rs b/execution/executor-service/src/lib.rs
new file mode 100644
index 0000000000000..ca39be9f052b2
--- /dev/null
+++ b/execution/executor-service/src/lib.rs
@@ -0,0 +1,38 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+use aptos_state_view::in_memory_state_view::InMemoryStateView;
+use aptos_types::{
+    transaction::{Transaction, TransactionOutput},
+    vm_status::VMStatus,
+};
+use serde::{Deserialize, Serialize};
+
+mod error;
+pub mod process_executor_service;
+pub mod remote_executor_client;
+pub mod remote_executor_service;
+#[cfg(test)]
+mod thread_executor_service;
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub struct BlockExecutionResult {
+    pub inner: Result, VMStatus>,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub enum BlockExecutionRequest {
+    ExecuteBlock(ExecuteBlockCommand),
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub struct ExecuteBlockCommand {
+    pub(crate) transactions: Vec,
+    // Currently we only support the state view backed by in-memory hashmap, which means that
+    // the controller needs to pre-read all the KV pairs from the storage and pass them to the
+    // executor service. In the future, we will support other types of state view, e.g., the
+    // state view backed by remote storage service, which will allow the executor service to read the KV pairs
+    // directly from the storage.
+    pub(crate) state_view: InMemoryStateView,
+    pub(crate) concurrency_level: usize,
+    pub(crate) maybe_block_gas_limit: Option,
+}
diff --git a/execution/executor-service/src/main.rs b/execution/executor-service/src/main.rs
new file mode 100644
index 0000000000000..fd978cfaf9734
--- /dev/null
+++ b/execution/executor-service/src/main.rs
@@ -0,0 +1,25 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use aptos_executor_service::process_executor_service::ProcessExecutorService;
+use clap::Parser;
+use std::net::{IpAddr, Ipv4Addr, SocketAddr};
+
+#[derive(Debug, Parser)]
+struct Args {
+    #[clap(long, default_value = "8080")]
+    pub server_port: u16,
+
+    #[clap(long, default_value = "8")]
+    pub num_executor_threads: usize,
+}
+
+fn main() {
+    let args = Args::parse();
+    aptos_logger::Logger::new().init();
+
+    let server_addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), args.server_port);
+    let executor_service =
+        ProcessExecutorService::new(server_addr, 1000, args.num_executor_threads);
+    executor_service.run();
+}
diff --git a/execution/executor-service/src/process_executor_service.rs b/execution/executor-service/src/process_executor_service.rs
new file mode 100644
index 0000000000000..f2c888be0b209
--- /dev/null
+++ b/execution/executor-service/src/process_executor_service.rs
@@ -0,0 +1,54 @@
+// Copyright © Aptos Foundation
+
+use crate::{
+    remote_executor_service,
+    remote_executor_service::{ExecutorService, RemoteExecutorService},
+};
+use aptos_logger::info;
+use aptos_secure_net::NetworkServer;
+use std::net::SocketAddr;
+
+/// An implementation of the remote executor service that runs in a standalone process.
+pub struct ProcessExecutorService {
+    server_addr: SocketAddr,
+    network_timeout_ms: u64,
+    num_executor_threads: usize,
+}
+
+impl ProcessExecutorService {
+    pub fn new(server_addr: SocketAddr, network_timeout: u64, num_executor_threads: usize) -> Self {
+        Self {
+            server_addr,
+            network_timeout_ms: network_timeout,
+            num_executor_threads,
+        }
+    }
+
+    pub fn run(&self) {
+        info!(
+            "Starting process remote executor service on {}",
+            self.server_addr
+        );
+        let network_server = NetworkServer::new(
+            "process-executor-service",
+            self.server_addr,
+            self.network_timeout_ms,
+        );
+        let executor_service = ExecutorService::new(self.num_executor_threads);
+        remote_executor_service::execute(network_server, executor_service);
+    }
+}
+
+impl RemoteExecutorService for ProcessExecutorService {
+    fn server_address(&self) -> SocketAddr {
+        self.server_addr
+    }
+
+    fn network_timeout_ms(&self) -> u64 {
+        self.network_timeout_ms
+    }
+
+    fn executor_threads(&self) -> usize {
+        self.num_executor_threads
+    }
+}
diff --git a/execution/executor-service/src/remote_executor_client.rs b/execution/executor-service/src/remote_executor_client.rs
new file mode 100644
index 0000000000000..a492bc58bbdfc
--- /dev/null
+++ b/execution/executor-service/src/remote_executor_client.rs
@@ -0,0 +1,75 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::{error::Error, BlockExecutionRequest, BlockExecutionResult, ExecuteBlockCommand};
+use aptos_logger::error;
+use aptos_retrier::{fixed_retry_strategy, retry};
+use aptos_secure_net::NetworkClient;
+use aptos_state_view::StateView;
+use aptos_types::{
+    transaction::{Transaction, TransactionOutput},
+    vm_status::VMStatus,
+};
+use aptos_vm::sharded_block_executor::block_executor_client::BlockExecutorClient;
+use std::{net::SocketAddr, sync::Mutex};
+
+/// An implementation of [`BlockExecutorClient`] that supports executing blocks remotely.
+pub struct RemoteExecutorClient {
+    network_client: Mutex,
+}
+
+impl RemoteExecutorClient {
+    pub fn new(server_address: SocketAddr, network_timeout_ms: u64) -> Self {
+        let network_client = NetworkClient::new(
+            "remote-executor-service",
+            server_address,
+            network_timeout_ms,
+        );
+        Self {
+            network_client: Mutex::new(network_client),
+        }
+    }
+
+    fn execute_block_inner(
+        &self,
+        execution_request: BlockExecutionRequest,
+    ) -> Result {
+        let input_message = bcs::to_bytes(&execution_request)?;
+        let mut network_client = self.network_client.lock().unwrap();
+        network_client.write(&input_message)?;
+        let bytes = network_client.read()?;
+        Ok(bcs::from_bytes(&bytes)?)
+    }
+
+    fn execute_block_with_retry(
+        &self,
+        execution_request: BlockExecutionRequest,
+    ) -> BlockExecutionResult {
+        retry(fixed_retry_strategy(5, 20), || {
+            let res = self.execute_block_inner(execution_request.clone());
+            if let Err(e) = &res {
+                error!("Failed to execute block: {:?}", e);
+            }
+            res
+        })
+        .unwrap()
+    }
+}
+
+impl BlockExecutorClient for RemoteExecutorClient {
+    fn execute_block(
+        &self,
+        transactions: Vec,
+        state_view: &S,
+        concurrency_level: usize,
+        maybe_block_gas_limit: Option,
+    ) -> Result, VMStatus> {
+        let input = BlockExecutionRequest::ExecuteBlock(ExecuteBlockCommand {
+            transactions,
+            state_view: S::as_in_memory_state_view(state_view),
+            concurrency_level,
+            maybe_block_gas_limit,
+        });
+        self.execute_block_with_retry(input).inner
+    }
+}
diff --git a/execution/executor-service/src/remote_executor_service.rs b/execution/executor-service/src/remote_executor_service.rs
new file mode 100644
index 0000000000000..236eb4be498c2
--- /dev/null
+++ b/execution/executor-service/src/remote_executor_service.rs
@@ -0,0 +1,224 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::{
+    error::Error, remote_executor_client::RemoteExecutorClient, BlockExecutionRequest,
+    BlockExecutionResult,
+};
+use aptos_logger::{error, info};
+use aptos_secure_net::NetworkServer;
+use aptos_vm::sharded_block_executor::block_executor_client::{
+    BlockExecutorClient, LocalExecutorClient,
+};
+use std::net::SocketAddr;
+
+/// A service that provides support for remote execution. Essentially, it reads a request from
+/// the remote executor client and executes the block locally and returns the result.
+pub struct ExecutorService {
+    client: LocalExecutorClient,
+}
+
+impl ExecutorService {
+    pub fn new(num_executor_threads: usize) -> Self {
+        Self {
+            client: LocalExecutorClient::new(num_executor_threads),
+        }
+    }
+
+    pub fn handle_message(&self, execution_message: Vec) -> Result, Error> {
+        let input = bcs::from_bytes(&execution_message)?;
+        let result = self.handle_execution_request(input)?;
+        Ok(bcs::to_bytes(&result)?)
+    }
+
+    pub fn handle_execution_request(
+        &self,
+        execution_request: BlockExecutionRequest,
+    ) -> Result {
+        let result = match execution_request {
+            BlockExecutionRequest::ExecuteBlock(command) => self.client.execute_block(
+                command.transactions,
+                &command.state_view,
+                command.concurrency_level,
+                command.maybe_block_gas_limit,
+            ),
+        };
+        Ok(BlockExecutionResult { inner: result })
+    }
+}
+
+pub trait RemoteExecutorService {
+    fn client(&self) -> RemoteExecutorClient {
+        RemoteExecutorClient::new(self.server_address(), self.network_timeout_ms())
+    }
+
+    fn server_address(&self) -> SocketAddr;
+
+    /// Network Timeout in milliseconds.
+    fn network_timeout_ms(&self) -> u64;
+
+    fn executor_threads(&self) -> usize;
+}
+
+pub fn execute(mut network_server: NetworkServer, executor_service: ExecutorService) {
+    loop {
+        if let Err(e) = process_one_message(&mut network_server, &executor_service) {
+            error!("Failed to process message: {}", e);
+        }
+    }
+}
+
+fn process_one_message(
+    network_server: &mut NetworkServer,
+    executor_service: &ExecutorService,
+) -> Result<(), Error> {
+    let request = network_server.read()?;
+    let response = executor_service.handle_message(request)?;
+    info!("server sending response");
+    network_server.write(&response)?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::{
+        remote_executor_service::RemoteExecutorService,
+        thread_executor_service::ThreadExecutorService,
+    };
+    use aptos_language_e2e_tests::{
+        account::AccountData, common_transactions::peer_to_peer_txn, executor::FakeExecutor,
+    };
+    use aptos_types::{
+        account_config::{DepositEvent, WithdrawEvent},
+        transaction::{ExecutionStatus, Transaction, TransactionOutput, TransactionStatus},
+    };
+    use aptos_vm::sharded_block_executor::{
+        block_executor_client::BlockExecutorClient, ShardedBlockExecutor,
+    };
+    use std::sync::Arc;
+
+    fn generate_transactions(executor: &mut FakeExecutor) -> (Vec, AccountData) {
+        let sender = executor.create_raw_account_data(3_000_000_000, 10);
+        let receiver = executor.create_raw_account_data(3_000_000_000, 10);
+        executor.add_account_data(&sender);
+        executor.add_account_data(&receiver);
+
+        let transfer_amount = 1_000;
+
+        // execute transaction
+        let txns: Vec = vec![
+            Transaction::UserTransaction(peer_to_peer_txn(
+                sender.account(),
+                receiver.account(),
+                10,
+                transfer_amount,
+                100,
+            )),
+            Transaction::UserTransaction(peer_to_peer_txn(
+                sender.account(),
+                receiver.account(),
+                11,
+                transfer_amount,
+                100,
+            )),
+            Transaction::UserTransaction(peer_to_peer_txn(
+                sender.account(),
+                receiver.account(),
+                12,
+                transfer_amount,
+                100,
+            )),
+            Transaction::UserTransaction(peer_to_peer_txn(
+                sender.account(),
+                receiver.account(),
+                13,
+                transfer_amount,
+                100,
+            )),
+        ];
+        (txns, receiver)
+    }
+
+    fn verify_txn_output(
+        transfer_amount: u64,
+        output: &[TransactionOutput],
+        executor: &mut FakeExecutor,
+        receiver: &AccountData,
+    ) {
+        for (idx, txn_output) in output.iter().enumerate() {
+            assert_eq!(
+                txn_output.status(),
+                &TransactionStatus::Keep(ExecutionStatus::Success)
+            );
+
+            // check events
+            for event in txn_output.events() {
+                if let Ok(payload) = WithdrawEvent::try_from(event) {
+                    assert_eq!(transfer_amount, payload.amount());
+                } else if let Ok(payload) = DepositEvent::try_from(event) {
+                    if payload.amount() == 0 {
+                        continue;
+                    }
+                    assert_eq!(transfer_amount, payload.amount());
+                } else {
+                    panic!("Unexpected Event Type")
+                }
+            }
+
+            let original_receiver_balance = executor
+                .read_coin_store_resource(receiver.account())
+                .expect("receiver balcne must exist");
+            executor.apply_write_set(txn_output.write_set());
+
+            // check that numbers in stored DB are correct
+            let receiver_balance = original_receiver_balance.coin() + transfer_amount;
+            let updated_receiver_balance = executor
+                .read_coin_store_resource(receiver.account())
+                .expect("receiver balance must exist");
+            assert_eq!(receiver_balance, updated_receiver_balance.coin());
+            assert_eq!(
+                idx as u64 + 1,
+                updated_receiver_balance.deposit_events().count()
+            );
+        }
+    }
+
+    #[test]
+    fn test_remote_block_execute() {
+        let executor_service = ThreadExecutorService::new(5000, 2);
+        // Uncomment for testing with a real server
+        // let server_addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 8080);
+        // let client = RemoteExecutorClient::new(server_addr, 1000);
+
+        let client = executor_service.client();
+        let mut executor = FakeExecutor::from_head_genesis();
+        for _ in 0..5 {
+            let (txns, receiver) = generate_transactions(&mut executor);
+
+            let output = client
+                .execute_block(txns, executor.data_store(), 2, None)
+                .unwrap();
+            verify_txn_output(1_000, &output, &mut executor, &receiver);
+        }
+    }
+
+    #[test]
+    fn test_sharded_remote_block_executor() {
+        let executor_service = ThreadExecutorService::new(5000, 2);
+        let client = executor_service.client();
+        // Uncomment for testing with a real server
+        // let server_addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 8080);
+        // let client = RemoteExecutorClient::new(server_addr, 1000);
+
+        let sharded_block_executor = ShardedBlockExecutor::new(vec![client]);
+        let mut executor = FakeExecutor::from_head_genesis();
+        for _ in 0..5 {
+            let (txns, receiver) = generate_transactions(&mut executor);
+
+            let output = sharded_block_executor
+                .execute_block(Arc::new(executor.data_store().clone()), txns, 2, None)
+                .unwrap();
+            verify_txn_output(1_000, &output, &mut executor, &receiver);
+        }
+    }
+}
diff --git a/execution/executor-service/src/thread_executor_service.rs b/execution/executor-service/src/thread_executor_service.rs
new file mode 100644
index 0000000000000..92e4672192d76
--- /dev/null
+++ b/execution/executor-service/src/thread_executor_service.rs
@@ -0,0 +1,62 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+use crate::{
+    remote_executor_service,
+    remote_executor_service::{ExecutorService, RemoteExecutorService},
+};
+use aptos_config::utils;
+use aptos_logger::info;
+use aptos_secure_net::NetworkServer;
+use std::{
+    net::{IpAddr, Ipv4Addr, SocketAddr},
+    thread,
+    thread::JoinHandle,
+};
+
+/// This is a simple implementation of RemoteExecutorService that runs the executor service in a
+/// separate thread. This should be used for testing only.
+pub struct ThreadExecutorService {
+    _child: JoinHandle<()>,
+    server_addr: SocketAddr,
+    network_timeout_ms: u64,
+    num_executor_threads: usize,
+}
+
+impl ThreadExecutorService {
+    pub fn new(network_timeout_ms: u64, num_executor_threads: usize) -> Self {
+        let listen_port = utils::get_available_port();
+        let listen_addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), listen_port);
+        let server_addr = listen_addr;
+        info!("Starting thread remote executor service on {}", listen_addr);
+
+        let network_server =
+            NetworkServer::new("thread-executor-service", listen_addr, network_timeout_ms);
+
+        let executor_service = ExecutorService::new(num_executor_threads);
+
+        let child = thread::spawn(move || {
+            remote_executor_service::execute(network_server, executor_service);
+        });
+
+        Self {
+            _child: child,
+            server_addr,
+            network_timeout_ms,
+            num_executor_threads,
+        }
+    }
+}
+
+impl RemoteExecutorService for ThreadExecutorService {
+    fn server_address(&self) -> SocketAddr {
+        self.server_addr
+    }
+
+    fn network_timeout_ms(&self) -> u64 {
+        self.network_timeout_ms
+    }
+
+    fn executor_threads(&self) -> usize {
+        self.num_executor_threads
+    }
+}
diff --git a/execution/executor/Cargo.toml b/execution/executor/Cargo.toml
index aae17baa701f9..8273dbf2ac591 100644
--- a/execution/executor/Cargo.toml
+++ b/execution/executor/Cargo.toml
@@ -33,6 +33,7 @@ dashmap = { workspace = true }
 fail = { workspace = true }
 itertools = { workspace = true }
 move-core-types = { workspace = true }
+num_cpus = { workspace = true }
 once_cell = { workspace = true }
 rayon = { workspace = true }
 serde = { workspace = true }
diff --git a/execution/executor/src/components/chunk_output.rs b/execution/executor/src/components/chunk_output.rs
index 04a625300dc17..859eeccd0ccfc 100644
--- a/execution/executor/src/components/chunk_output.rs
+++ b/execution/executor/src/components/chunk_output.rs
@@ -18,7 +18,10 @@ use aptos_types::{
     account_config::CORE_CODE_ADDRESS,
     transaction::{ExecutionStatus, Transaction, TransactionOutput, TransactionStatus},
 };
-use aptos_vm::{sharded_block_executor::ShardedBlockExecutor, AptosVM, VMExecutor};
+use aptos_vm::{
+    sharded_block_executor::{block_executor_client::LocalExecutorClient, ShardedBlockExecutor},
+    AptosVM, VMExecutor,
+};
 use fail::fail_point;
 use move_core_types::vm_status::StatusCode;
 use once_cell::sync::Lazy;
@@ -26,10 +29,9 @@ use std::{ops::Deref, sync::Arc, time::Duration};
 
 pub static SHARDED_BLOCK_EXECUTOR: Lazy>>> =
     Lazy::new(|| {
-        Arc::new(Mutex::new(ShardedBlockExecutor::new(
-            AptosVM::get_num_shards(),
-            None, // Defaults to num_cpus / num_shards
-        )))
+        let executor_clients =
+            LocalExecutorClient::create_local_clients(AptosVM::get_num_shards(), None);
+        Arc::new(Mutex::new(ShardedBlockExecutor::new(executor_clients)))
     });
 
 pub struct ChunkOutput {
diff --git a/storage/state-view/src/in_memory_state_view.rs b/storage/state-view/src/in_memory_state_view.rs
new file mode 100644
index 0000000000000..519a9b31c01b3
--- /dev/null
+++ b/storage/state-view/src/in_memory_state_view.rs
@@ -0,0 +1,43 @@
+// Copyright © Aptos Foundation
+// Parts of the project are originally copyright © Meta Platforms, Inc.
+// SPDX-License-Identifier: Apache-2.0
+#![forbid(unsafe_code)]
+use crate::TStateView;
+use anyhow::Result;
+use aptos_types::state_store::{
+    state_key::StateKey, state_storage_usage::StateStorageUsage, state_value::StateValue,
+};
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+
+// A State view backed by in-memory hashmap.
+#[derive(Clone, Debug, Eq, PartialEq, Deserialize, Serialize)]
+pub struct InMemoryStateView {
+    state_data: HashMap,
+}
+
+impl InMemoryStateView {
+    pub fn new(state_data: HashMap) -> Self {
+        Self { state_data }
+    }
+}
+
+impl TStateView for InMemoryStateView {
+    type Key = StateKey;
+
+    fn get_state_value(&self, state_key: &StateKey) -> Result> {
+        Ok(self.state_data.get(state_key).cloned())
+    }
+
+    fn is_genesis(&self) -> bool {
+        unimplemented!("is_genesis is not implemented for InMemoryStateView")
+    }
+
+    fn get_usage(&self) -> Result {
+        Ok(StateStorageUsage::new_untracked())
+    }
+
+    fn as_in_memory_state_view(&self) -> InMemoryStateView {
+        self.clone()
+    }
+}
diff --git a/storage/state-view/src/lib.rs b/storage/state-view/src/lib.rs
index 7fa8c53b7c0b7..f52017ef34cf9 100644
--- a/storage/state-view/src/lib.rs
+++ b/storage/state-view/src/lib.rs
@@ -6,7 +6,10 @@
 
 //! This crate defines [`trait StateView`](StateView).
 
-use crate::account_with_state_view::{AccountWithStateView, AsAccountWithStateView};
+use crate::{
+    account_with_state_view::{AccountWithStateView, AsAccountWithStateView},
+    in_memory_state_view::InMemoryStateView,
+};
 use anyhow::Result;
 use aptos_crypto::HashValue;
 use aptos_types::{
@@ -20,6 +23,7 @@ use std::ops::Deref;
 
 pub mod account_with_state_cache;
 pub mod account_with_state_view;
+pub mod in_memory_state_view;
 
 /// `StateView` is a trait that defines a read-only snapshot of the global state. It is passed to
 /// the VM for transaction execution, during which the VM is guaranteed to read anything at the
@@ -47,6 +51,10 @@ pub trait TStateView {
 
     /// Get state storage usage info at epoch ending.
     fn get_usage(&self) -> Result;
+
+    fn as_in_memory_state_view(&self) -> InMemoryStateView {
+        unreachable!("in-memory state view conversion not supported yet")
+    }
 }
 
 pub trait StateView: TStateView {}

From b8c62f3d36350520445d8cd11b376911a21b4f2c Mon Sep 17 00:00:00 2001
From: Daniel Porteous 
Date: Fri, 9 Jun 2023 17:35:06 +0100
Subject: [PATCH 128/200] Use inputs.GIT_SHA not env.GIT_SHA in CLI E2E tests

---
 .github/workflows/cli-e2e-tests.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/cli-e2e-tests.yaml b/.github/workflows/cli-e2e-tests.yaml
index e71476396b751..20c50ef37302e 100644
--- a/.github/workflows/cli-e2e-tests.yaml
+++ b/.github/workflows/cli-e2e-tests.yaml
@@ -25,7 +25,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
         with:
-          ref: ${{ env.GIT_SHA }}
+          ref: ${{ inputs.GIT_SHA }}
 
       - uses: aptos-labs/aptos-core/.github/actions/docker-setup@main
         with:

From d022b222b43c9682b586083d8a3345029c0d5eca Mon Sep 17 00:00:00 2001
From: Balaji Arun 
Date: Fri, 9 Jun 2023 10:27:56 -0700
Subject: [PATCH 129/200] [forge][fix] Track and remove chaos properly (#8598)

---
 testsuite/testcases/src/modifiers.rs          | 24 +++++++++----------
 .../src/multi_region_network_test.rs          | 24 ++++++++++---------
 2 files changed, 25 insertions(+), 23 deletions(-)

diff --git a/testsuite/testcases/src/modifiers.rs b/testsuite/testcases/src/modifiers.rs
index 33258ca15bdba..d8cb346dcf08a 100644
--- a/testsuite/testcases/src/modifiers.rs
+++ b/testsuite/testcases/src/modifiers.rs
@@ -217,6 +217,16 @@ pub struct CpuChaosTest {
     pub override_config: Option,
 }
 
+impl CpuChaosTest {
+    fn create_cpu_chaos(&self, swarm: &mut dyn Swarm) -> SwarmCpuStress {
+        let all_validators = swarm.validators().map(|v| v.peer_id()).collect::>();
+
+        let config = self.override_config.as_ref().cloned().unwrap_or_default();
+
+        create_cpu_stress_template(all_validators, &config)
+    }
+}
+
 impl Test for CpuChaosTest {
     fn name(&self) -> &'static str {
         "CpuChaosWrapper"
@@ -244,15 +254,8 @@ fn create_cpu_stress_template(
 
 impl NetworkLoadTest for CpuChaosTest {
     fn setup(&self, ctx: &mut NetworkContext) -> anyhow::Result {
-        let all_validators = ctx
-            .swarm()
-            .validators()
-            .map(|v| v.peer_id())
-            .collect::>();
-
-        let config = self.override_config.as_ref().cloned().unwrap_or_default();
+        let swarm_cpu_stress = self.create_cpu_chaos(ctx.swarm());
 
-        let swarm_cpu_stress = create_cpu_stress_template(all_validators, &config);
         ctx.swarm()
             .inject_chaos(SwarmChaos::CpuStress(swarm_cpu_stress))?;
 
@@ -260,11 +263,8 @@ impl NetworkLoadTest for CpuChaosTest {
     }
 
     fn finish(&self, swarm: &mut dyn Swarm) -> anyhow::Result<()> {
-        let all_validators = swarm.validators().map(|v| v.peer_id()).collect::>();
-
-        let config = self.override_config.as_ref().cloned().unwrap_or_default();
+        let swarm_cpu_stress = self.create_cpu_chaos(swarm);
 
-        let swarm_cpu_stress = create_cpu_stress_template(all_validators, &config);
         swarm.remove_chaos(SwarmChaos::CpuStress(swarm_cpu_stress))
     }
 }
diff --git a/testsuite/testcases/src/multi_region_network_test.rs b/testsuite/testcases/src/multi_region_network_test.rs
index 03868a03dd07a..cebdd616652b6 100644
--- a/testsuite/testcases/src/multi_region_network_test.rs
+++ b/testsuite/testcases/src/multi_region_network_test.rs
@@ -214,6 +214,16 @@ pub struct MultiRegionNetworkEmulationTest {
     pub override_config: Option,
 }
 
+impl MultiRegionNetworkEmulationTest {
+    fn create_netem_chaos(&self, swarm: &mut dyn Swarm) -> SwarmNetEm {
+        let all_validators = swarm.validators().map(|v| v.peer_id()).collect::>();
+
+        let config = self.override_config.clone().unwrap_or_default();
+
+        create_multi_region_swarm_network_chaos(all_validators, &config)
+    }
+}
+
 impl Test for MultiRegionNetworkEmulationTest {
     fn name(&self) -> &'static str {
         "network:multi-region-network-emulation"
@@ -241,23 +251,15 @@ fn create_multi_region_swarm_network_chaos(
 
 impl NetworkLoadTest for MultiRegionNetworkEmulationTest {
     fn setup(&self, ctx: &mut NetworkContext) -> anyhow::Result {
-        let all_validators = ctx
-            .swarm()
-            .validators()
-            .map(|v| v.peer_id())
-            .collect::>();
-
-        let config = self.override_config.as_ref().cloned().unwrap_or_default();
-
-        // inject netem chaos
-        let chaos = create_multi_region_swarm_network_chaos(all_validators, &config);
+        let chaos = self.create_netem_chaos(ctx.swarm());
         ctx.swarm().inject_chaos(SwarmChaos::NetEm(chaos))?;
 
         Ok(LoadDestination::FullnodesOtherwiseValidators)
     }
 
     fn finish(&self, swarm: &mut dyn Swarm) -> anyhow::Result<()> {
-        swarm.remove_all_chaos()
+        let chaos = self.create_netem_chaos(swarm);
+        swarm.remove_chaos(SwarmChaos::NetEm(chaos))
     }
 }
 

From f49d0508b45195a87beb73b583c24500b41b814a Mon Sep 17 00:00:00 2001
From: Balaji Arun 
Date: Fri, 9 Jun 2023 10:31:49 -0700
Subject: [PATCH 130/200] [telemetry-svc][bug-fix] Add timeouts for requests
 (#8451)

Co-authored-by: geekflyer 
---
 .../src/prometheus_push_metrics.rs            | 22 ++++++++++++-------
 crates/aptos-telemetry/src/sender.rs          | 12 +++++++---
 2 files changed, 23 insertions(+), 11 deletions(-)

diff --git a/crates/aptos-telemetry-service/src/prometheus_push_metrics.rs b/crates/aptos-telemetry-service/src/prometheus_push_metrics.rs
index 7cc4e92367517..50b1bc0966c1c 100644
--- a/crates/aptos-telemetry-service/src/prometheus_push_metrics.rs
+++ b/crates/aptos-telemetry-service/src/prometheus_push_metrics.rs
@@ -11,9 +11,12 @@ use crate::{
     types::{auth::Claims, common::NodeType},
 };
 use reqwest::{header::CONTENT_ENCODING, StatusCode};
+use std::time::Duration;
 use tokio::time::Instant;
 use warp::{filters::BoxedFilter, hyper::body::Bytes, reject, reply, Filter, Rejection, Reply};
 
+const MAX_METRICS_POST_WAIT_DURATION_SECS: u64 = 5;
+
 pub fn metrics_ingest(context: Context) -> BoxedFilter<(impl Reply,)> {
     warp::path!("ingest" / "metrics")
         .and(warp::post())
@@ -58,16 +61,18 @@ pub async fn handle_metrics_ingest(
     let start_timer = Instant::now();
 
     let post_futures = client.iter().map(|(name, client)| async {
-        let result = client
-            .post_prometheus_metrics(
+        let result = tokio::time::timeout(
+            Duration::from_secs(MAX_METRICS_POST_WAIT_DURATION_SECS),
+            client.post_prometheus_metrics(
                 metrics_body.clone(),
                 extra_labels.clone(),
                 encoding.clone().unwrap_or_default(),
-            )
-            .await;
+            ),
+        )
+        .await;
 
         match result {
-            Ok(res) => {
+            Ok(Ok(res)) => {
                 METRICS_INGEST_BACKEND_REQUEST_DURATION
                     .with_label_values(&[&claims.peer_id.to_string(), name, res.status().as_str()])
                     .observe(start_timer.elapsed().as_secs_f64());
@@ -82,7 +87,7 @@ pub async fn handle_metrics_ingest(
                     return Err(());
                 }
             },
-            Err(err) => {
+            Ok(Err(err)) => {
                 METRICS_INGEST_BACKEND_REQUEST_DURATION
                     .with_label_values(&[name, "Unknown"])
                     .observe(start_timer.elapsed().as_secs_f64());
@@ -93,6 +98,7 @@ pub async fn handle_metrics_ingest(
                 );
                 return Err(());
             },
+            Err(_) => return Err(()),
         }
         Ok(())
     });
@@ -267,7 +273,7 @@ mod test {
             handle_metrics_ingest(test_context.inner, claims, Some("gzip".into()), body).await;
 
         mock1.assert();
-        mock2.assert_hits(4);
+        assert!(mock2.hits_async().await >= 1);
         assert!(result.is_ok());
     }
 
@@ -302,7 +308,7 @@ mod test {
         let result =
             handle_metrics_ingest(test_context.inner, claims, Some("gzip".into()), body).await;
 
-        mock1.assert_hits(4);
+        assert!(mock1.hits_async().await >= 1);
         mock2.assert();
         assert!(result.is_err());
     }
diff --git a/crates/aptos-telemetry/src/sender.rs b/crates/aptos-telemetry/src/sender.rs
index 2c28206a1db8a..a9cb87bc93f36 100644
--- a/crates/aptos-telemetry/src/sender.rs
+++ b/crates/aptos-telemetry/src/sender.rs
@@ -21,11 +21,14 @@ use prometheus::{default_registry, Registry};
 use reqwest::{header::CONTENT_ENCODING, Response, StatusCode, Url};
 use reqwest_middleware::{ClientBuilder, ClientWithMiddleware, RequestBuilder};
 use reqwest_retry::{policies::ExponentialBackoff, RetryTransientMiddleware};
-use std::{io::Write, sync::Arc};
+use std::{io::Write, sync::Arc, time::Duration};
 use uuid::Uuid;
 
 pub const DEFAULT_VERSION_PATH_BASE: &str = "api/v1/";
 
+pub const PROMETHEUS_PUSH_METRICS_TIMEOUT_SECS: u64 = 8;
+pub const TELEMETRY_SERVICE_TOTAL_RETRY_DURATION_SECS: u64 = 10;
+
 struct AuthContext {
     noise_config: Option,
     token: RwLock>,
@@ -56,7 +59,9 @@ pub(crate) struct TelemetrySender {
 
 impl TelemetrySender {
     pub fn new(base_url: Url, chain_id: ChainId, node_config: &NodeConfig) -> Self {
-        let retry_policy = ExponentialBackoff::builder().build_with_max_retries(3);
+        let retry_policy = ExponentialBackoff::builder().build_with_total_retry_duration(
+            Duration::from_secs(TELEMETRY_SERVICE_TOTAL_RETRY_DURATION_SECS),
+        );
 
         let reqwest_client = reqwest::Client::new();
         let client = ClientBuilder::new(reqwest_client)
@@ -135,7 +140,8 @@ impl TelemetrySender {
                 self.client
                     .post(self.build_path("ingest/metrics")?)
                     .header(CONTENT_ENCODING, "gzip")
-                    .body(compressed_bytes),
+                    .body(compressed_bytes)
+                    .timeout(Duration::from_secs(PROMETHEUS_PUSH_METRICS_TIMEOUT_SECS)),
             )
             .await;
 

From 0a777f530ceb15354ebf1df7155e7adae3598a45 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 9 Jun 2023 11:08:43 -0700
Subject: [PATCH 131/200] [dashboards] sync grafana dashboards (#8505)

Co-authored-by: rustielin 
---
 dashboards/blockchain-health.json             |   36 +-
 dashboards/blockchain-health.json.gz          |  Bin 8760 -> 8756 bytes
 .../developer-platform-client-metrics.json    |  144 ++-
 .../developer-platform-client-metrics.json.gz |  Bin 1870 -> 2552 bytes
 dashboards/mempool.json                       |  431 ++-----
 dashboards/mempool.json.gz                    |  Bin 8752 -> 8803 bytes
 dashboards/overview.json                      |    5 +-
 dashboards/overview.json.gz                   |  Bin 9803 -> 9846 bytes
 dashboards/public-fullnodes.json              | 1124 +++++++++++++++++
 dashboards/public-fullnodes.json.gz           |  Bin 0 -> 3915 bytes
 dashboards/system.json                        |   36 +-
 dashboards/system.json.gz                     |  Bin 2561 -> 2585 bytes
 12 files changed, 1356 insertions(+), 420 deletions(-)
 create mode 100644 dashboards/public-fullnodes.json
 create mode 100644 dashboards/public-fullnodes.json.gz

diff --git a/dashboards/blockchain-health.json b/dashboards/blockchain-health.json
index 0d73d20d35541..fe5cc5a3afcab 100644
--- a/dashboards/blockchain-health.json
+++ b/dashboards/blockchain-health.json
@@ -1363,7 +1363,7 @@
           "refId": "A"
         }
       ],
-      "title": "(devnet/testnet) PFN-only Per Bucket Avg E2E Txn Commit Latency",
+      "title": "Aptos PFN-only Per Bucket Avg E2E Txn Commit Latency",
       "type": "timeseries"
     },
     {
@@ -1459,13 +1459,7 @@
             "thresholdsStyle": { "mode": "off" }
           },
           "mappings": [],
-          "thresholds": {
-            "mode": "absolute",
-            "steps": [
-              { "color": "green", "value": null },
-              { "color": "red", "value": 80 }
-            ]
-          }
+          "thresholds": { "mode": "absolute", "steps": [{ "color": "green" }, { "color": "red", "value": 80 }] }
         },
         "overrides": []
       },
@@ -1523,13 +1517,7 @@
             "thresholdsStyle": { "mode": "off" }
           },
           "mappings": [],
-          "thresholds": {
-            "mode": "absolute",
-            "steps": [
-              { "color": "green", "value": null },
-              { "color": "red", "value": 80 }
-            ]
-          }
+          "thresholds": { "mode": "absolute", "steps": [{ "color": "green" }, { "color": "red", "value": 80 }] }
         },
         "overrides": []
       },
@@ -1578,13 +1566,7 @@
             "thresholdsStyle": { "mode": "off" }
           },
           "mappings": [],
-          "thresholds": {
-            "mode": "absolute",
-            "steps": [
-              { "color": "green", "value": null },
-              { "color": "red", "value": 80 }
-            ]
-          }
+          "thresholds": { "mode": "absolute", "steps": [{ "color": "green" }, { "color": "red", "value": 80 }] }
         },
         "overrides": []
       },
@@ -1633,13 +1615,7 @@
             "thresholdsStyle": { "mode": "off" }
           },
           "mappings": [],
-          "thresholds": {
-            "mode": "absolute",
-            "steps": [
-              { "color": "green", "value": null },
-              { "color": "red", "value": 80 }
-            ]
-          }
+          "thresholds": { "mode": "absolute", "steps": [{ "color": "green" }, { "color": "red", "value": 80 }] }
         },
         "overrides": []
       },
@@ -3252,6 +3228,6 @@
   "timezone": "browser",
   "title": "blockchain-health",
   "uid": "JnOvNs4Vk",
-  "version": 11,
+  "version": 12,
   "weekStart": ""
 }
diff --git a/dashboards/blockchain-health.json.gz b/dashboards/blockchain-health.json.gz
index 2a35f103e68150d23ee233f48d0c3a69942e56ee..ffda3c34025a11ea8c92059b1073c547976bb9d1 100644
GIT binary patch
literal 8756
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

literal 8760
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∨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

diff --git a/dashboards/developer-platform-client-metrics.json b/dashboards/developer-platform-client-metrics.json
index 0ba62ecec90c0..c26e3cf32f0ce 100644
--- a/dashboards/developer-platform-client-metrics.json
+++ b/dashboards/developer-platform-client-metrics.json
@@ -28,7 +28,7 @@
         "content": "In order to view metrics for:\n- mainnet\n  - datasource: VictoriaMetrics Mainnet\n  - chain_name: mainnet\n- testnet\n  - datasource: VictoriaMetrics Global (Non-mainnet)\n  - chain_name: testnet\n- devnet\n  - datasource: VictoriaMetrics Global (Non-mainnet)\n  - chain_name: devnet",
         "mode": "markdown"
       },
-      "pluginVersion": "9.5.3-cloud.2.0cb5a501",
+      "pluginVersion": "10.0.0-cloud.3.b04cc88b",
       "title": "Guide",
       "type": "text"
     },
@@ -49,7 +49,7 @@
         "content": "This section contains queries that aggregate across all clients. This means the `source_client` variable above doesn't do anything.",
         "mode": "markdown"
       },
-      "pluginVersion": "9.5.3-cloud.2.0cb5a501",
+      "pluginVersion": "10.0.0-cloud.3.b04cc88b",
       "title": "Explanation",
       "type": "text"
     },
@@ -118,60 +118,116 @@
       "type": "piechart"
     },
     {
-      "collapsed": false,
-      "gridPos": { "h": 1, "w": 24, "x": 0, "y": 27 },
-      "id": 4,
-      "panels": [],
-      "repeat": "source_client",
-      "repeatDirection": "h",
-      "title": "Per client",
-      "type": "row"
-    },
-    {
-      "datasource": { "type": "prometheus", "uid": "fHo-R604z" },
-      "gridPos": { "h": 3, "w": 24, "x": 0, "y": 28 },
-      "id": 6,
-      "options": {
-        "code": { "language": "plaintext", "showLineNumbers": false, "showMiniMap": false },
-        "content": "This section contains queries that show data for a specific client. To select which client to view metrics for, select one in the `source_client` variable dropdown above.",
-        "mode": "markdown"
-      },
-      "pluginVersion": "9.5.3-cloud.2.0cb5a501",
-      "title": "Explanation",
-      "type": "text"
-    },
-    {
-      "datasource": { "type": "prometheus", "uid": "${datasource}" },
-      "description": "This shows what are the top 5 most common endpoints called by users of this client in the configured time window.",
+      "datasource": { "type": "grafana-falconlogscale-datasource", "uid": "b4f0e2cd-2eea-4ada-a4c0-261e41369ed5" },
       "fieldConfig": {
         "defaults": {
           "color": { "mode": "palette-classic" },
-          "custom": { "hideFrom": { "legend": false, "tooltip": false, "viz": false } },
-          "mappings": []
+          "custom": {
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "fillOpacity": 80,
+            "gradientMode": "none",
+            "hideFrom": { "legend": false, "tooltip": false, "viz": false },
+            "lineWidth": 1,
+            "scaleDistribution": { "type": "linear" },
+            "thresholdsStyle": { "mode": "off" }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              { "color": "green", "value": null },
+              { "color": "red", "value": 80 }
+            ]
+          }
         },
         "overrides": []
       },
-      "gridPos": { "h": 15, "w": 12, "x": 0, "y": 31 },
-      "id": 3,
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 27 },
+      "id": 10,
       "options": {
-        "legend": { "displayMode": "list", "placement": "bottom", "showLegend": true },
-        "pieType": "pie",
-        "reduceOptions": { "calcs": ["lastNotNull"], "fields": "", "values": false },
-        "tooltip": { "mode": "single", "sort": "none" }
+        "barRadius": 0,
+        "barWidth": 0.97,
+        "fullHighlight": false,
+        "groupWidth": 0.7,
+        "legend": { "calcs": [], "displayMode": "list", "placement": "bottom", "showLegend": true },
+        "orientation": "auto",
+        "showValue": "auto",
+        "stacking": "none",
+        "tooltip": { "mode": "single", "sort": "none" },
+        "xTickLabelRotation": 0,
+        "xTickLabelSpacing": 0
       },
-      "pluginVersion": "9.5.3-cloud.2.0cb5a501",
+      "pluginVersion": "10.0.0-cloud.3.b04cc88b",
       "targets": [
+        {
+          "datasource": { "type": "grafana-falconlogscale-datasource", "uid": "b4f0e2cd-2eea-4ada-a4c0-261e41369ed5" },
+          "lsql": "| #resource.type=cloud_run_revision\n| resource.labels.service_name=indexer-$chain_name \n| jsonPayload.method=* logName=*stdout\n| case {jsonPayload.aptos_client!=* | jsonPayload.aptos_client:=\"unknown\"; *}\n| top(jsonPayload.aptos_client)",
+          "refId": "A",
+          "repository": "gcp"
+        }
+      ],
+      "title": "Indexer API requests by client",
+      "type": "barchart"
+    },
+    {
+      "collapsed": true,
+      "gridPos": { "h": 1, "w": 24, "x": 0, "y": 35 },
+      "id": 4,
+      "panels": [
+        {
+          "datasource": { "type": "prometheus", "uid": "fHo-R604z" },
+          "gridPos": { "h": 3, "w": 24, "x": 0, "y": 36 },
+          "id": 6,
+          "options": {
+            "code": { "language": "plaintext", "showLineNumbers": false, "showMiniMap": false },
+            "content": "This section contains queries that show data for a specific client. To select which client to view metrics for, select one in the `source_client` variable dropdown above.",
+            "mode": "markdown"
+          },
+          "pluginVersion": "10.0.0-cloud.3.b04cc88b",
+          "title": "Explanation",
+          "type": "text"
+        },
         {
           "datasource": { "type": "prometheus", "uid": "${datasource}" },
-          "editorMode": "code",
-          "expr": "topk(5, sum by(operation_id) (increase(aptos_api_request_source_client{request_source_client=\"$source_client\", chain_name=\"$chain_name\"}[$__range])))",
-          "legendFormat": "__auto",
-          "range": true,
-          "refId": "A"
+          "description": "This shows what are the top 5 most common endpoints called by users of this client in the configured time window.",
+          "fieldConfig": {
+            "defaults": {
+              "color": { "mode": "palette-classic" },
+              "custom": { "hideFrom": { "legend": false, "tooltip": false, "viz": false } },
+              "mappings": []
+            },
+            "overrides": []
+          },
+          "gridPos": { "h": 15, "w": 12, "x": 0, "y": 39 },
+          "id": 3,
+          "options": {
+            "legend": { "displayMode": "list", "placement": "bottom", "showLegend": true },
+            "pieType": "pie",
+            "reduceOptions": { "calcs": ["lastNotNull"], "fields": "", "values": false },
+            "tooltip": { "mode": "single", "sort": "none" }
+          },
+          "pluginVersion": "9.5.3-cloud.2.0cb5a501",
+          "targets": [
+            {
+              "datasource": { "type": "prometheus", "uid": "${datasource}" },
+              "editorMode": "code",
+              "expr": "topk(5, sum by(operation_id) (increase(aptos_api_request_source_client{request_source_client=\"$source_client\", chain_name=\"$chain_name\"}[$__range])))",
+              "legendFormat": "__auto",
+              "range": true,
+              "refId": "A"
+            }
+          ],
+          "title": "Top 5 endpoints",
+          "type": "piechart"
         }
       ],
-      "title": "Top 5 endpoints",
-      "type": "piechart"
+      "repeat": "source_client",
+      "repeatDirection": "h",
+      "title": "Per client",
+      "type": "row"
     }
   ],
   "refresh": "",
@@ -244,6 +300,6 @@
   "timezone": "",
   "title": "Developer Platform Client Metrics",
   "uid": "be847ea3-c7cc-4048-b783-eb2fdb4f1abd",
-  "version": 48,
+  "version": 53,
   "weekStart": ""
 }
diff --git a/dashboards/developer-platform-client-metrics.json.gz b/dashboards/developer-platform-client-metrics.json.gz
index 06005e87e44aac93a266aaa48c55b68439932b39..b376418ea5182a892c47268764cdf687ff958305 100644
GIT binary patch
literal 2552
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

literal 8752
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
P1^!PkG{^N60q*|*09?MY

diff --git a/dashboards/overview.json b/dashboards/overview.json
index 19b2e8eb4337a..ad2bce7c6f04a 100644
--- a/dashboards/overview.json
+++ b/dashboards/overview.json
@@ -3106,6 +3106,7 @@
     },
     {
       "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "description": "Data on PFN nodes only. Unless clients send duplicate transactions, this is a reliable way to see E2E latency.",
       "fieldConfig": {
         "defaults": {
           "color": { "mode": "palette-classic" },
@@ -3178,7 +3179,7 @@
           "refId": "C"
         }
       ],
-      "title": "(devnet/testnet) PFN-only e2e latency",
+      "title": "Aptos PFN-only e2e latency",
       "type": "timeseries"
     },
     {
@@ -3912,6 +3913,6 @@
   "timezone": "",
   "title": "overview",
   "uid": "overview",
-  "version": 16,
+  "version": 17,
   "weekStart": ""
 }
diff --git a/dashboards/overview.json.gz b/dashboards/overview.json.gz
index 8cc1d37854f7cb6c20ce79c5685bba8c9a08eb65..9194fb0be2000b7bfb1885377a15e175e167018d 100644
GIT binary patch
delta 3141
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

delta 3083
zcmV+m4D|E%Ov_BLQ5t_+bJ|E2e$TJya(QaN0~pyMfrr_uP1c#s)+X`Tj`tyxQpwPO
z3Lz0m7<)Y4-#&f1TX%tx3`oK!53wy;Lfw5X-?{WTGt1Eow)(m;w<)oi+=f1-2Gy9d
zBh0ktE(Wq->}f4p*apCw}WTD~6
zWv-(9y2B%zQuCk@uQ=RTaSQ1E&<)*oWMWKTg{K)Hl#mgUwK}n98S)rSL`fvmncIQ!
zSJ~>srN#fCPUwF?ok{iLs0@({sb2*bd}_ho5(NGI4Ewm&=3x+0(>*<1PvVN*Gz^Ht
zi>2+)mtzc4qdNOOo7`HEItk-6$0gAQ_H2vh=D=w{)nth=f}u+LD0Orl5eFiU$WTNa
zh&VQkIQ;aG6vz>B{vqVpU=o0#O=s#gg`fL1@lTUaP?u{)UT{z>4>Ou>d6Z;rz%oh7=qsenemfMq3DVv$j^qh^0Onq7I5Q?$CVwxMlyHsyLX>#+gkMbST|0lRxBE68K7FG8WC_xG&#BFK*zD6}
z@TkhAFRKo=e4^@R!dj;o079&VSSuISvZ-GNim7vYr#kwd^nw4%Pl2)5o~o{E;CZhV
z7_Rxit9mX4b6Yyt^+{|Tfh~I>SZ)a(D__yd%_wxtf0ctU|MjW-*G}xSjpVD@d0lWjSwX;OoxMY83o@@ec_F76y
z32D>v<(taoh0v!Q{66U
zEYZu%67R~+637$C6VKy`URIuXzt-^&_HINj`d*&*DAIGUL@qotO(LV~{`Ct?lZf&H
zdhXG4pUHDSX2!BLvbCui)7(rQ*Fw6B-qHRXdVGpssCr{q{RuM$`WEC!-puOOzO
zJAzh1XGtZ+J8&6v`_|8SLan7~uk9ncl@!oH3fLwEbk>ON6iWe}Hd4SADInni*>bAZ
zJJ>2BHV(?Jh$xyrY_Fqyc2KIIx
z*qaT_*3pL08-tHi_5!9`Qip3v=8AuTx{?O!N}7c~*#R`5C75j}j^E*Kr`)3vg)KS)!oD1@ti?(CDJ*O8ro&jTzoH
zqZa~QK*qLZGDFTL%rdd&qw#F+lA7$b;*c5pKse*-p*n8p9gu_2J5Y#s0IPrA7Viky
zsKuYCv#+!}37fxNK-JszY<`Dru{gk6!K$|*u(P4Au0_;>jYfy!&0fEqne~>f+ULeSs_A1gcuo$c`2BevPNEtJPW}8+$gS$*Mm}&L}cJ?Z}+G&!CNmcMa7v<
zdB$yO!v&Ff3=M`=#_sbwRhAFx&*tjf(MGfoD7As?W)2ErfIcv&I(7cit%at$>^E?J
z9jYo!T=g$S0;C-@F3``JiKV$n#9j?I|0UfC-?7OOlsK~#Ra;8N-0P+)*X6+C}+HviW
z({l5WzhJ#yKT_Ijny>!cev01Uy&YSxaYhUD{rOk&6)2I^{tJH;O1_xJePR83(N2?t
z&`v`;4ehigQ}^t&0qsw2?p?a&a|9_?TK5#Kv}_{((|^n#A3sd5CwXxe2T|bpYwmrm680%LF5br)G8y#Py{BHV_TA>8A!hcC_vzyp?t@Xdr=BH_<5=%s^@gx
z1c-mt$R$?E-5;mF*aLjTiOcnIQ}U3
zGLTrUFhrU1+nDGd)2S9v+-X-__N?oHW>3UOR}<3ufR{08LS5Yh@mPjhXJFTwfyx)`
z9gu0Hp{1@2&p@a*!phJlqRA>K&1n`(;-ijK_nA@)TfPZlqciY
zyERqTOQ%REC
z916*6N$?@D7ni9K2paK!!M)Q*zr*x+aUYUgF}aT?>+a*SE%Wxp`@Sr@!eHW1GqvW8
zKH}G!gVfD^Vl&oX<7^AM7Ar@$IK<2m7WP4{`2WhlV;=q`e}aeDn}6WGgD}7*txgx>vgDlT#arJMr|^K^
Z!GhAsCD0Ck-mAw~e*;pCm|n><0swA!2x|ZU

diff --git a/dashboards/public-fullnodes.json b/dashboards/public-fullnodes.json
new file mode 100644
index 0000000000000..dbf6e412644f0
--- /dev/null
+++ b/dashboards/public-fullnodes.json
@@ -0,0 +1,1124 @@
+{
+  "annotations": {
+    "list": [
+      {
+        "builtIn": 1,
+        "datasource": { "type": "grafana", "uid": "-- Grafana --" },
+        "enable": true,
+        "hide": true,
+        "iconColor": "rgba(0, 211, 255, 1)",
+        "name": "Annotations & Alerts",
+        "target": { "limit": 100, "matchAny": false, "tags": [], "type": "dashboard" },
+        "type": "dashboard"
+      },
+      {
+        "datasource": { "type": "datasource", "uid": "grafana" },
+        "enable": true,
+        "expr": "",
+        "iconColor": "rgba(0, 211, 255, 1)",
+        "iconSize": 0,
+        "lineColor": "",
+        "name": "Annotations & Alerts",
+        "query": "",
+        "showLine": false,
+        "step": "",
+        "tagKeys": "",
+        "tagsField": "",
+        "target": { "limit": 100, "matchAny": false, "tags": [], "type": "dashboard" },
+        "textField": "",
+        "textFormat": "",
+        "titleFormat": "",
+        "type": "dashboard"
+      }
+    ]
+  },
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 1,
+  "links": [
+    {
+      "asDropdown": true,
+      "icon": "external link",
+      "includeVars": true,
+      "keepTime": true,
+      "title": "Other Dashboards",
+      "type": "dashboards"
+    }
+  ],
+  "liveNow": false,
+  "panels": [
+    {
+      "collapsed": false,
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "editable": false,
+      "error": false,
+      "gridPos": { "h": 1, "w": 24, "x": 0, "y": 0 },
+      "id": 7,
+      "panels": [],
+      "span": 0,
+      "title": "State Sync",
+      "type": "row"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "description": "The latest synced version of the node.",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": {
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "drawStyle": "line",
+            "fillOpacity": 0,
+            "gradientMode": "none",
+            "hideFrom": { "legend": false, "tooltip": false, "viz": false },
+            "lineInterpolation": "linear",
+            "lineWidth": 1,
+            "pointSize": 5,
+            "scaleDistribution": { "type": "linear" },
+            "showPoints": "auto",
+            "spanNulls": false,
+            "stacking": { "group": "A", "mode": "none" },
+            "thresholdsStyle": { "mode": "off" }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              { "color": "green", "value": null },
+              { "color": "red", "value": 80 }
+            ]
+          }
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 1 },
+      "id": 36,
+      "options": {
+        "legend": { "calcs": [], "displayMode": "list", "placement": "bottom", "showLegend": true },
+        "tooltip": { "mode": "single", "sort": "none" }
+      },
+      "targets": [
+        {
+          "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+          "editorMode": "code",
+          "expr": "aptos_state_sync_version{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", type=\"synced\", kubernetes_pod_name=~\"$kubernetes_pod_name\"}",
+          "hide": false,
+          "legendFormat": "{{kubernetes_pod_name}}-{{role}}",
+          "range": true,
+          "refId": "A"
+        }
+      ],
+      "title": "Latest synced version",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "description": "The latest synced version.",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "continuous-GrYlRd" },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              { "color": "green", "value": null },
+              { "color": "red", "value": 80 }
+            ]
+          }
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 1 },
+      "id": 37,
+      "options": {
+        "displayMode": "lcd",
+        "minVizHeight": 10,
+        "minVizWidth": 0,
+        "orientation": "horizontal",
+        "reduceOptions": { "calcs": ["lastNotNull"], "fields": "", "values": false },
+        "showUnfilled": true,
+        "valueMode": "color"
+      },
+      "pluginVersion": "10.0.1-cloud.1.d4a15e66",
+      "targets": [
+        {
+          "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+          "editorMode": "code",
+          "expr": "aptos_state_sync_version{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", type=\"synced\", kubernetes_pod_name=~\"$kubernetes_pod_name\"}",
+          "legendFormat": "{{kubernetes_pod_name}}-{{role}}",
+          "range": true,
+          "refId": "A"
+        }
+      ],
+      "title": "Latest synced version",
+      "type": "bargauge"
+    },
+    {
+      "aliasColors": {},
+      "bars": false,
+      "dashLength": 10,
+      "dashes": false,
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "description": "Rate at which the synced version is increasing",
+      "editable": false,
+      "error": false,
+      "fill": 0,
+      "fillGradient": 0,
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 9 },
+      "hiddenSeries": false,
+      "id": 2,
+      "legend": {
+        "alignAsTable": false,
+        "avg": false,
+        "current": false,
+        "hideEmpty": false,
+        "hideZero": false,
+        "max": false,
+        "min": false,
+        "rightSide": false,
+        "show": false,
+        "total": false,
+        "values": false
+      },
+      "lines": true,
+      "linewidth": 1,
+      "nullPointMode": "null",
+      "options": { "alertThreshold": true },
+      "percentage": false,
+      "pluginVersion": "10.0.1-cloud.1.d4a15e66",
+      "pointradius": 2,
+      "points": false,
+      "renderer": "flot",
+      "seriesOverrides": [],
+      "spaceLength": 10,
+      "span": 0,
+      "stack": false,
+      "steppedLine": false,
+      "targets": [
+        {
+          "datasource": { "type": "prometheus", "uid": "fHo-R604z" },
+          "editorMode": "code",
+          "expr": "rate(aptos_state_sync_version{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", type=\"synced\", kubernetes_pod_name=~\"$kubernetes_pod_name\"}[$interval])",
+          "legendFormat": "{{kubernetes_pod_name}}-{{kubernetes_pod_name}}",
+          "range": true,
+          "refId": "A"
+        }
+      ],
+      "thresholds": [],
+      "timeRegions": [],
+      "title": "State Sync Rate",
+      "tooltip": { "shared": true, "sort": 0, "value_type": "individual" },
+      "type": "graph",
+      "xaxis": { "format": "", "logBase": 0, "mode": "time", "show": true, "values": [] },
+      "yaxes": [
+        { "format": "short", "label": "/s", "logBase": 1, "show": true },
+        { "format": "short", "logBase": 1, "show": true }
+      ],
+      "yaxis": { "align": false }
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "description": "The difference between the highest advertised version and the currently synced version.",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": {
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "drawStyle": "line",
+            "fillOpacity": 0,
+            "gradientMode": "none",
+            "hideFrom": { "legend": false, "tooltip": false, "viz": false },
+            "lineInterpolation": "linear",
+            "lineWidth": 1,
+            "pointSize": 5,
+            "scaleDistribution": { "type": "linear" },
+            "showPoints": "auto",
+            "spanNulls": false,
+            "stacking": { "group": "A", "mode": "none" },
+            "thresholdsStyle": { "mode": "off" }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              { "color": "green", "value": null },
+              { "color": "red", "value": 80 }
+            ]
+          }
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 9 },
+      "id": 38,
+      "options": {
+        "legend": { "calcs": [], "displayMode": "list", "placement": "bottom", "showLegend": true },
+        "tooltip": { "mode": "single", "sort": "none" }
+      },
+      "pluginVersion": "8.5.2",
+      "targets": [
+        {
+          "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+          "editorMode": "code",
+          "expr": "clamp_min(aptos_data_client_highest_advertised_data{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\"$kubernetes_pod_name\", data_type=\"transactions\"} - on(kubernetes_pod_name, cluster, run_uuid) aptos_state_sync_version{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\"$kubernetes_pod_name\", type=\"synced\"}, 0)",
+          "hide": false,
+          "legendFormat": "{{kubernetes_pod_name}}-{{role}}",
+          "range": true,
+          "refId": "A"
+        }
+      ],
+      "title": "Sync lag (behind highest known)",
+      "type": "timeseries"
+    },
+    {
+      "collapsed": false,
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "editable": false,
+      "error": false,
+      "gridPos": { "h": 1, "w": 24, "x": 0, "y": 17 },
+      "id": 31,
+      "panels": [],
+      "span": 0,
+      "title": "Mempool",
+      "type": "row"
+    },
+    {
+      "aliasColors": {},
+      "bars": false,
+      "dashLength": 10,
+      "dashes": false,
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "description": "Number of uncommitted but still valid (not expired nor discarded) transactions in the nodes Mempool.",
+      "editable": false,
+      "error": false,
+      "fill": 0,
+      "fillGradient": 0,
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 18 },
+      "hiddenSeries": false,
+      "id": 26,
+      "legend": {
+        "alignAsTable": false,
+        "avg": false,
+        "current": false,
+        "hideEmpty": false,
+        "hideZero": false,
+        "max": false,
+        "min": false,
+        "rightSide": false,
+        "show": false,
+        "total": false,
+        "values": false
+      },
+      "lines": true,
+      "linewidth": 1,
+      "nullPointMode": "null",
+      "options": { "alertThreshold": true },
+      "percentage": false,
+      "pluginVersion": "10.0.1-cloud.1.d4a15e66",
+      "pointradius": 2,
+      "points": false,
+      "renderer": "flot",
+      "seriesOverrides": [],
+      "spaceLength": 10,
+      "span": 0,
+      "stack": false,
+      "steppedLine": false,
+      "targets": [
+        {
+          "expr": "aptos_core_mempool_index_size{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", index=\"system_ttl\", kubernetes_pod_name=~\".*fullnode.*\", kubernetes_pod_name=~\"$kubernetes_pod_name\"}",
+          "legendFormat": "{{kubernetes_pod_name}}-{{kubernetes_pod_name}}",
+          "refId": "A"
+        },
+        {
+          "expr": "aptos_core_mempool_index_size{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", index=\"system_ttl\", job=~\".*fullnode.*\", kubernetes_pod_name=~\"$kubernetes_pod_name\"}",
+          "legendFormat": "{{kubernetes_pod_name}}-{{job}}",
+          "refId": "B"
+        }
+      ],
+      "thresholds": [],
+      "timeRegions": [],
+      "title": "Mempool Pending transactions",
+      "tooltip": { "shared": true, "sort": 0, "value_type": "individual" },
+      "type": "graph",
+      "xaxis": { "format": "", "logBase": 0, "mode": "time", "show": true, "values": [] },
+      "yaxes": [
+        { "format": "short", "logBase": 1, "show": true },
+        { "format": "short", "logBase": 1, "show": true }
+      ],
+      "yaxis": { "align": false }
+    },
+    {
+      "aliasColors": {},
+      "bars": false,
+      "dashLength": 10,
+      "dashes": false,
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "description": "The time between Mempool receiving the transaction and time to be committed. Note: due to reliability mechanisms, this value can be lower than it really is.",
+      "editable": false,
+      "error": false,
+      "fill": 0,
+      "fillGradient": 0,
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 18 },
+      "hiddenSeries": false,
+      "id": 34,
+      "legend": {
+        "alignAsTable": false,
+        "avg": false,
+        "current": false,
+        "hideEmpty": false,
+        "hideZero": false,
+        "max": false,
+        "min": false,
+        "rightSide": false,
+        "show": false,
+        "total": false,
+        "values": false
+      },
+      "lines": true,
+      "linewidth": 1,
+      "nullPointMode": "null",
+      "options": { "alertThreshold": true },
+      "percentage": false,
+      "pluginVersion": "10.0.1-cloud.1.d4a15e66",
+      "pointradius": 2,
+      "points": false,
+      "renderer": "flot",
+      "seriesOverrides": [],
+      "spaceLength": 10,
+      "span": 0,
+      "stack": false,
+      "steppedLine": false,
+      "targets": [
+        {
+          "expr": "aptos_core_mempool_txn_commit_latency_sum{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\".*fullnode.*\", kubernetes_pod_name=~\"$kubernetes_pod_name\"} / aptos_core_mempool_txn_commit_latency_count{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\".*fullnode.*\", kubernetes_pod_name=~\"$kubernetes_pod_name\"}",
+          "legendFormat": "{{kubernetes_pod_name}}-{{kubernetes_pod_name}}",
+          "refId": "A"
+        },
+        {
+          "expr": "aptos_core_mempool_txn_commit_latency_sum{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", job=~\".*fullnode.*\", kubernetes_pod_name=~\"$kubernetes_pod_name\"} / aptos_core_mempool_txn_commit_latency_count{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", job=~\".*fullnode.*\", kubernetes_pod_name=~\"$kubernetes_pod_name\"}",
+          "legendFormat": "{{kubernetes_pod_name}}-{{job}}",
+          "refId": "B"
+        }
+      ],
+      "thresholds": [],
+      "timeRegions": [],
+      "title": "Mempool Txn Commit Latency",
+      "tooltip": { "shared": true, "sort": 0, "value_type": "individual" },
+      "type": "graph",
+      "xaxis": { "format": "", "logBase": 0, "mode": "time", "show": true, "values": [] },
+      "yaxes": [
+        { "format": "s", "logBase": 1, "show": true },
+        { "format": "short", "logBase": 1, "show": true }
+      ],
+      "yaxis": { "align": false }
+    },
+    {
+      "collapsed": false,
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "editable": false,
+      "error": false,
+      "gridPos": { "h": 1, "w": 24, "x": 0, "y": 26 },
+      "id": 22,
+      "panels": [],
+      "span": 0,
+      "title": "Networking",
+      "type": "row"
+    },
+    {
+      "aliasColors": {},
+      "bars": false,
+      "dashLength": 10,
+      "dashes": false,
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "description": "Number of Inbound Connections as measured by AptosNet",
+      "editable": false,
+      "error": false,
+      "fill": 0,
+      "fillGradient": 0,
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 27 },
+      "hiddenSeries": false,
+      "id": 24,
+      "legend": {
+        "alignAsTable": false,
+        "avg": false,
+        "current": false,
+        "hideEmpty": false,
+        "hideZero": false,
+        "max": false,
+        "min": false,
+        "rightSide": false,
+        "show": false,
+        "total": false,
+        "values": false
+      },
+      "lines": true,
+      "linewidth": 1,
+      "nullPointMode": "null",
+      "options": { "alertThreshold": true },
+      "percentage": false,
+      "pluginVersion": "10.0.1-cloud.1.d4a15e66",
+      "pointradius": 2,
+      "points": false,
+      "renderer": "flot",
+      "seriesOverrides": [],
+      "spaceLength": 10,
+      "span": 0,
+      "stack": false,
+      "steppedLine": false,
+      "targets": [
+        {
+          "expr": "sum by (kubernetes_pod_name,kubernetes_pod_name)(aptos_connections{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", direction=\"inbound\",network_id=\"Public\", kubernetes_pod_name=~\"$kubernetes_pod_name\"})",
+          "legendFormat": "{{kubernetes_pod_name}}-{{kubernetes_pod_name}}",
+          "refId": "A"
+        }
+      ],
+      "thresholds": [],
+      "timeRegions": [],
+      "title": "Network Connections (Incoming)",
+      "tooltip": { "shared": true, "sort": 0, "value_type": "individual" },
+      "type": "graph",
+      "xaxis": { "format": "", "logBase": 0, "mode": "time", "show": true, "values": [] },
+      "yaxes": [
+        { "format": "short", "logBase": 1, "show": true },
+        { "format": "short", "logBase": 1, "show": true }
+      ],
+      "yaxis": { "align": false }
+    },
+    {
+      "aliasColors": {},
+      "bars": false,
+      "dashLength": 10,
+      "dashes": false,
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "description": "Number of  Outbound Network Connections as measured by AptosNet",
+      "editable": false,
+      "error": false,
+      "fill": 0,
+      "fillGradient": 0,
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 27 },
+      "hiddenSeries": false,
+      "id": 35,
+      "legend": {
+        "alignAsTable": false,
+        "avg": false,
+        "current": false,
+        "hideEmpty": false,
+        "hideZero": false,
+        "max": false,
+        "min": false,
+        "rightSide": false,
+        "show": false,
+        "total": false,
+        "values": false
+      },
+      "lines": true,
+      "linewidth": 1,
+      "nullPointMode": "null",
+      "options": { "alertThreshold": true },
+      "percentage": false,
+      "pluginVersion": "10.0.1-cloud.1.d4a15e66",
+      "pointradius": 2,
+      "points": false,
+      "renderer": "flot",
+      "seriesOverrides": [],
+      "spaceLength": 10,
+      "span": 0,
+      "stack": false,
+      "steppedLine": false,
+      "targets": [
+        {
+          "expr": "sum by (kubernetes_pod_name, kubernetes_pod_name)(aptos_connections{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", direction=\"outbound\",network_id=\"Public\", kubernetes_pod_name=~\"$kubernetes_pod_name\"})",
+          "legendFormat": "{{kubernetes_pod_name}}-{{kubernetes_pod_name}}",
+          "refId": "A"
+        }
+      ],
+      "thresholds": [],
+      "timeRegions": [],
+      "title": "Network Connections (Outgoing)",
+      "tooltip": { "shared": true, "sort": 0, "value_type": "individual" },
+      "type": "graph",
+      "xaxis": { "format": "", "logBase": 0, "mode": "time", "show": true, "values": [] },
+      "yaxes": [
+        { "format": "short", "logBase": 1, "show": true },
+        { "format": "short", "logBase": 1, "show": true }
+      ],
+      "yaxis": { "align": false }
+    },
+    {
+      "aliasColors": {},
+      "bars": false,
+      "dashLength": 10,
+      "dashes": false,
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "editable": false,
+      "error": false,
+      "fill": 0,
+      "fillGradient": 0,
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 35 },
+      "hiddenSeries": false,
+      "id": 20,
+      "legend": {
+        "alignAsTable": false,
+        "avg": false,
+        "current": false,
+        "hideEmpty": false,
+        "hideZero": false,
+        "max": false,
+        "min": false,
+        "rightSide": false,
+        "show": false,
+        "total": false,
+        "values": false
+      },
+      "lines": true,
+      "linewidth": 1,
+      "nullPointMode": "null",
+      "options": { "alertThreshold": true },
+      "percentage": false,
+      "pluginVersion": "10.0.1-cloud.1.d4a15e66",
+      "pointradius": 2,
+      "points": false,
+      "renderer": "flot",
+      "seriesOverrides": [],
+      "spaceLength": 10,
+      "span": 0,
+      "stack": false,
+      "steppedLine": false,
+      "targets": [
+        {
+          "expr": "sum(irate(container_network_transmit_bytes_total{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", pod=~\"$kubernetes_pod_name.*fullnode.*\"}[$interval])) by (pod)",
+          "legendFormat": "{{pod}}",
+          "refId": "A"
+        },
+        {
+          "expr": "sum(irate(container_network_transmit_bytes_total{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", pod=~\"$kubernetes_pod_name.*fullnode.*\"}[$interval]))",
+          "legendFormat": "total",
+          "refId": "B"
+        }
+      ],
+      "thresholds": [],
+      "timeRegions": [],
+      "title": "Transmit Bandwidth",
+      "tooltip": { "shared": true, "sort": 0, "value_type": "individual" },
+      "type": "graph",
+      "xaxis": { "format": "", "logBase": 0, "mode": "time", "show": true, "values": [] },
+      "yaxes": [
+        { "format": "Bps", "logBase": 1, "show": true },
+        { "format": "short", "logBase": 1, "show": true }
+      ],
+      "yaxis": { "align": false }
+    },
+    {
+      "aliasColors": {},
+      "bars": false,
+      "dashLength": 10,
+      "dashes": false,
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "editable": false,
+      "error": false,
+      "fill": 0,
+      "fillGradient": 0,
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 35 },
+      "hiddenSeries": false,
+      "id": 19,
+      "legend": {
+        "alignAsTable": false,
+        "avg": false,
+        "current": false,
+        "hideEmpty": false,
+        "hideZero": false,
+        "max": false,
+        "min": false,
+        "rightSide": false,
+        "show": false,
+        "total": false,
+        "values": false
+      },
+      "lines": true,
+      "linewidth": 1,
+      "nullPointMode": "null",
+      "options": { "alertThreshold": true },
+      "percentage": false,
+      "pluginVersion": "10.0.1-cloud.1.d4a15e66",
+      "pointradius": 2,
+      "points": false,
+      "renderer": "flot",
+      "seriesOverrides": [],
+      "spaceLength": 10,
+      "span": 0,
+      "stack": false,
+      "steppedLine": false,
+      "targets": [
+        {
+          "expr": "sum(irate(container_network_receive_bytes_total{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", pod=~\"$kubernetes_pod_name.*fullnode.*\"}[$interval])) by (pod)",
+          "legendFormat": "{{pod}}",
+          "refId": "A"
+        },
+        {
+          "expr": "sum(irate(container_network_receive_bytes_total{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", pod=~\"$kubernetes_pod_name.*fullnode.*\"}[$interval]))",
+          "legendFormat": "total",
+          "refId": "B"
+        }
+      ],
+      "thresholds": [],
+      "timeRegions": [],
+      "title": "Receive Bandwidth",
+      "tooltip": { "shared": true, "sort": 0, "value_type": "individual" },
+      "type": "graph",
+      "xaxis": { "format": "", "logBase": 0, "mode": "time", "show": true, "values": [] },
+      "yaxes": [
+        { "format": "Bps", "logBase": 1, "show": true },
+        { "format": "short", "logBase": 1, "show": true }
+      ],
+      "yaxis": { "align": false }
+    },
+    {
+      "collapsed": false,
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "editable": false,
+      "error": false,
+      "gridPos": { "h": 1, "w": 24, "x": 0, "y": 43 },
+      "id": 9,
+      "panels": [],
+      "span": 0,
+      "title": "System",
+      "type": "row"
+    },
+    {
+      "aliasColors": {},
+      "bars": false,
+      "dashLength": 10,
+      "dashes": false,
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "editable": false,
+      "error": false,
+      "fill": 0,
+      "fillGradient": 0,
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 44 },
+      "hiddenSeries": false,
+      "id": 5,
+      "legend": {
+        "alignAsTable": false,
+        "avg": false,
+        "current": false,
+        "hideEmpty": false,
+        "hideZero": false,
+        "max": false,
+        "min": false,
+        "rightSide": false,
+        "show": false,
+        "total": false,
+        "values": false
+      },
+      "lines": true,
+      "linewidth": 1,
+      "nullPointMode": "null",
+      "options": { "alertThreshold": true },
+      "percentage": false,
+      "pluginVersion": "10.0.1-cloud.1.d4a15e66",
+      "pointradius": 2,
+      "points": false,
+      "renderer": "flot",
+      "seriesOverrides": [],
+      "spaceLength": 10,
+      "span": 0,
+      "stack": false,
+      "steppedLine": false,
+      "targets": [
+        {
+          "expr": "1 - kubelet_volume_stats_available_bytes{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", persistentvolumeclaim=~\"fn.$kubernetes_pod_name.*\", kubernetes_pod_name=~\"$kubernetes_pod_name\"} / kubelet_volume_stats_capacity_bytes{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", persistentvolumeclaim=~\"fn.$kubernetes_pod_name.*\", kubernetes_pod_name=~\"$kubernetes_pod_name\"}",
+          "legendFormat": "{{persistentvolumeclaim}}",
+          "refId": "A"
+        },
+        {
+          "expr": "1 - kubelet_volume_stats_available_bytes{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", persistentvolumeclaim=~\"$kubernetes_pod_name.*fullnode.*\", kubernetes_pod_name!~\"val.*\"} / kubelet_volume_stats_capacity_bytes{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", persistentvolumeclaim=~\"$kubernetes_pod_name.*fullnode.*\", kubernetes_pod_name!~\"val.*\"}",
+          "legendFormat": "{{persistentvolumeclaim}}",
+          "refId": "B"
+        }
+      ],
+      "thresholds": [],
+      "timeRegions": [],
+      "title": "Percentage Disk Used",
+      "tooltip": { "shared": true, "sort": 0, "value_type": "individual" },
+      "type": "graph",
+      "xaxis": { "format": "", "logBase": 0, "mode": "time", "show": true, "values": [] },
+      "yaxes": [
+        { "format": "percentunit", "logBase": 1, "show": true },
+        { "format": "short", "logBase": 1, "show": true }
+      ],
+      "yaxis": { "align": false }
+    },
+    {
+      "aliasColors": {},
+      "bars": false,
+      "dashLength": 10,
+      "dashes": false,
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "editable": false,
+      "error": false,
+      "fill": 0,
+      "fillGradient": 0,
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 44 },
+      "hiddenSeries": false,
+      "id": 11,
+      "legend": {
+        "alignAsTable": false,
+        "avg": false,
+        "current": false,
+        "hideEmpty": false,
+        "hideZero": false,
+        "max": false,
+        "min": false,
+        "rightSide": false,
+        "show": false,
+        "total": false,
+        "values": false
+      },
+      "lines": true,
+      "linewidth": 1,
+      "nullPointMode": "null",
+      "options": { "alertThreshold": true },
+      "percentage": false,
+      "pluginVersion": "10.0.1-cloud.1.d4a15e66",
+      "pointradius": 2,
+      "points": false,
+      "renderer": "flot",
+      "seriesOverrides": [],
+      "spaceLength": 10,
+      "span": 0,
+      "stack": false,
+      "steppedLine": false,
+      "targets": [
+        {
+          "datasource": { "type": "prometheus", "uid": "fHo-R604z" },
+          "editorMode": "code",
+          "expr": "container_memory_working_set_bytes{container=\"fullnode\", pod=~\"$kubernetes_pod_name.*\", job=\"kubernetes-cadvisor\", chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\"}",
+          "legendFormat": "{{pod}}",
+          "range": true,
+          "refId": "A"
+        }
+      ],
+      "thresholds": [],
+      "timeRegions": [],
+      "title": "Memory Usage",
+      "tooltip": { "shared": true, "sort": 0, "value_type": "individual" },
+      "type": "graph",
+      "xaxis": { "format": "", "logBase": 0, "mode": "time", "show": true, "values": [] },
+      "yaxes": [
+        { "format": "bytes", "logBase": 1, "show": true },
+        { "format": "short", "logBase": 1, "show": true }
+      ],
+      "yaxis": { "align": false }
+    },
+    {
+      "aliasColors": {},
+      "bars": false,
+      "dashLength": 10,
+      "dashes": false,
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "editable": false,
+      "error": false,
+      "fill": 0,
+      "fillGradient": 0,
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 52 },
+      "hiddenSeries": false,
+      "id": 17,
+      "legend": {
+        "alignAsTable": false,
+        "avg": false,
+        "current": false,
+        "hideEmpty": false,
+        "hideZero": false,
+        "max": false,
+        "min": false,
+        "rightSide": false,
+        "show": false,
+        "total": false,
+        "values": false
+      },
+      "lines": true,
+      "linewidth": 1,
+      "nullPointMode": "null",
+      "options": { "alertThreshold": true },
+      "percentage": false,
+      "pluginVersion": "10.0.1-cloud.1.d4a15e66",
+      "pointradius": 2,
+      "points": false,
+      "renderer": "flot",
+      "seriesOverrides": [],
+      "spaceLength": 10,
+      "span": 0,
+      "stack": false,
+      "steppedLine": false,
+      "targets": [
+        {
+          "datasource": { "type": "prometheus", "uid": "fHo-R604z" },
+          "editorMode": "code",
+          "expr": "rate(container_cpu_usage_seconds_total{container=\"fullnode\", kubernetes_pod_name=~\"$kubernetes_pod_name\", chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\"}[$interval])",
+          "legendFormat": "{{kubernetes_pod_name}}-{{pod}}",
+          "range": true,
+          "refId": "A"
+        },
+        {
+          "datasource": { "type": "prometheus", "uid": "fHo-R604z" },
+          "editorMode": "code",
+          "expr": "rate(container_cpu_usage_seconds_total{container=\"fullnode\", pod=~\"pfn.*\", chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\"}[$interval])",
+          "legendFormat": "{{pod}}",
+          "range": true,
+          "refId": "B"
+        }
+      ],
+      "thresholds": [],
+      "timeRegions": [],
+      "title": "CPU Usage",
+      "tooltip": { "shared": true, "sort": 0, "value_type": "individual" },
+      "type": "graph",
+      "xaxis": { "format": "", "logBase": 0, "mode": "time", "show": true, "values": [] },
+      "yaxes": [
+        { "format": "short", "logBase": 1, "show": true },
+        { "format": "short", "logBase": 1, "show": true }
+      ],
+      "yaxis": { "align": false }
+    },
+    {
+      "aliasColors": {},
+      "bars": false,
+      "dashLength": 10,
+      "dashes": false,
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "editable": false,
+      "error": false,
+      "fill": 0,
+      "fillGradient": 0,
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 52 },
+      "hiddenSeries": false,
+      "id": 15,
+      "legend": {
+        "alignAsTable": false,
+        "avg": false,
+        "current": false,
+        "hideEmpty": false,
+        "hideZero": false,
+        "max": false,
+        "min": false,
+        "rightSide": false,
+        "show": false,
+        "total": false,
+        "values": false
+      },
+      "lines": true,
+      "linewidth": 1,
+      "nullPointMode": "null",
+      "options": { "alertThreshold": true },
+      "percentage": false,
+      "pluginVersion": "10.0.1-cloud.1.d4a15e66",
+      "pointradius": 2,
+      "points": false,
+      "renderer": "flot",
+      "seriesOverrides": [],
+      "spaceLength": 10,
+      "span": 0,
+      "stack": false,
+      "steppedLine": false,
+      "targets": [
+        {
+          "datasource": { "type": "prometheus", "uid": "fHo-R604z" },
+          "editorMode": "code",
+          "expr": "time() - container_start_time_seconds{container=\"fullnode\", pod=~\"$kubernetes_pod_name.*\", job=\"kubernetes-cadvisor\", chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\"}",
+          "legendFormat": "{{pod}}",
+          "range": true,
+          "refId": "A"
+        }
+      ],
+      "thresholds": [],
+      "timeRegions": [],
+      "title": "Uptime",
+      "tooltip": { "shared": true, "sort": 0, "value_type": "individual" },
+      "type": "graph",
+      "xaxis": { "format": "", "logBase": 0, "mode": "time", "show": true, "values": [] },
+      "yaxes": [
+        { "format": "s", "logBase": 1, "show": true },
+        { "format": "short", "logBase": 1, "show": true }
+      ],
+      "yaxis": { "align": false }
+    }
+  ],
+  "refresh": "",
+  "schemaVersion": 38,
+  "style": "dark",
+  "tags": ["aptos-core"],
+  "templating": {
+    "list": [
+      {
+        "allFormat": "",
+        "allValue": "",
+        "current": {
+          "selected": true,
+          "text": "VictoriaMetrics Global (Non-mainnet)",
+          "value": "VictoriaMetrics Global (Non-mainnet)"
+        },
+        "hide": 0,
+        "includeAll": false,
+        "label": "",
+        "multi": false,
+        "multiFormat": "",
+        "name": "Datasource",
+        "options": [],
+        "query": "prometheus",
+        "queryValue": "",
+        "refresh": 1,
+        "regex": ".*Prometheus.*|.*Victoria.*|.*Telemetry.*",
+        "skipUrlSync": false,
+        "sort": 0,
+        "type": "datasource"
+      },
+      {
+        "current": { "selected": true, "text": ["vmagent"], "value": ["vmagent"] },
+        "hide": 0,
+        "includeAll": false,
+        "label": "",
+        "multi": true,
+        "name": "metrics_source",
+        "options": [{ "selected": true, "text": "vmagent", "value": "vmagent" }],
+        "query": "vmagent",
+        "queryValue": "",
+        "skipUrlSync": false,
+        "type": "custom"
+      },
+      {
+        "allFormat": "",
+        "allValue": "",
+        "current": { "selected": true, "text": "testnet", "value": "testnet" },
+        "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+        "definition": "",
+        "hide": 0,
+        "includeAll": false,
+        "label": "",
+        "multi": false,
+        "multiFormat": "",
+        "name": "chain_name",
+        "options": [],
+        "query": {
+          "query": "label_values(node_process_start_time{metrics_source=~\"$metrics_source\"}, chain_name)",
+          "refId": "StandardVariableQuery"
+        },
+        "refresh": 1,
+        "regex": "",
+        "skipUrlSync": false,
+        "sort": 1,
+        "type": "query"
+      },
+      {
+        "allFormat": "",
+        "allValue": ".*",
+        "current": { "selected": true, "text": ["gcp-testnet-pfn"], "value": ["gcp-testnet-pfn"] },
+        "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+        "definition": "label_values(node_process_start_time{metrics_source=~\"$metrics_source\", chain_name=~\"$chain_name\"},cluster)",
+        "hide": 0,
+        "includeAll": false,
+        "label": "",
+        "multi": true,
+        "multiFormat": "",
+        "name": "cluster",
+        "options": [],
+        "query": {
+          "query": "label_values(node_process_start_time{metrics_source=~\"$metrics_source\", chain_name=~\"$chain_name\"},cluster)",
+          "refId": "PrometheusVariableQueryEditor-VariableQuery"
+        },
+        "refresh": 1,
+        "regex": "^.*pfn.*$",
+        "skipUrlSync": false,
+        "sort": 0,
+        "type": "query"
+      },
+      {
+        "allFormat": "",
+        "allValue": ".*",
+        "current": { "selected": false, "text": "All", "value": "$__all" },
+        "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+        "definition": "",
+        "hide": 0,
+        "includeAll": true,
+        "label": "",
+        "multi": false,
+        "multiFormat": "",
+        "name": "namespace",
+        "options": [],
+        "query": {
+          "query": "label_values(node_process_start_time{metrics_source=~\"$metrics_source\", chain_name=~\"$chain_name\", cluster=~\"$cluster\"}, namespace)",
+          "refId": "StandardVariableQuery"
+        },
+        "refresh": 1,
+        "regex": "",
+        "skipUrlSync": false,
+        "sort": 1,
+        "type": "query"
+      },
+      {
+        "allFormat": "",
+        "allValue": ".*",
+        "current": { "selected": true, "text": ["All"], "value": ["$__all"] },
+        "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+        "definition": "",
+        "hide": 0,
+        "includeAll": true,
+        "label": "",
+        "multi": true,
+        "multiFormat": "",
+        "name": "kubernetes_pod_name",
+        "options": [],
+        "query": {
+          "query": "label_values(node_process_start_time{metrics_source=~\"$metrics_source\", chain_name=~\"$chain_name\", cluster=~\"$cluster\", namespace=~\"$namespace\"}, kubernetes_pod_name)",
+          "refId": "StandardVariableQuery"
+        },
+        "refresh": 1,
+        "regex": "",
+        "skipUrlSync": false,
+        "sort": 1,
+        "type": "query"
+      },
+      {
+        "allFormat": "",
+        "allValue": "",
+        "auto": true,
+        "auto_count": 30,
+        "auto_min": "10s",
+        "current": { "selected": false, "text": "auto", "value": "$__auto_interval_interval" },
+        "hide": 0,
+        "includeAll": false,
+        "label": "",
+        "multi": false,
+        "multiFormat": "",
+        "name": "interval",
+        "options": [
+          { "selected": true, "text": "auto", "value": "$__auto_interval_interval" },
+          { "selected": false, "text": "1m", "value": "1m" },
+          { "selected": false, "text": "5m", "value": "5m" },
+          { "selected": false, "text": "10m", "value": "10m" },
+          { "selected": false, "text": "30m", "value": "30m" },
+          { "selected": false, "text": "1h", "value": "1h" }
+        ],
+        "query": "1m,5m,10m,30m,1h",
+        "refresh": 2,
+        "regex": "",
+        "skipUrlSync": false,
+        "sort": 0,
+        "type": "interval"
+      }
+    ]
+  },
+  "time": { "from": "now-2d", "to": "now" },
+  "timepicker": { "refresh_intervals": ["5s", "10s", "30s", "1m", "5m", "15m", "30m", "1h", "2h", "1d"] },
+  "timezone": "",
+  "title": "public-fullnodes",
+  "uid": "de6aa860-0aed-4876-bd81-ec593d4bc252",
+  "version": 5,
+  "weekStart": ""
+}
diff --git a/dashboards/public-fullnodes.json.gz b/dashboards/public-fullnodes.json.gz
new file mode 100644
index 0000000000000000000000000000000000000000..8cee6149f1cf75fd5cc952c0a14ed1ea0c516886
GIT binary patch
literal 3915
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
Z&Iw~j2M8Eu$Vcao{txFxjAyr*003n?uZ92s

literal 0
HcmV?d00001

diff --git a/dashboards/system.json b/dashboards/system.json
index 821e18d73b35a..89b58bdde6041 100644
--- a/dashboards/system.json
+++ b/dashboards/system.json
@@ -61,7 +61,6 @@
       "gridPos": { "h": 11, "w": 8, "x": 0, "y": 0 },
       "hiddenSeries": false,
       "id": 6,
-      "isNew": false,
       "legend": {
         "alignAsTable": false,
         "avg": false,
@@ -80,7 +79,7 @@
       "nullPointMode": "null",
       "options": { "alertThreshold": true },
       "percentage": false,
-      "pluginVersion": "9.1.1",
+      "pluginVersion": "10.0.0-cloud.3.b04cc88b",
       "pointradius": 2,
       "points": false,
       "renderer": "flot",
@@ -124,7 +123,6 @@
       "gridPos": { "h": 11, "w": 8, "x": 8, "y": 0 },
       "hiddenSeries": false,
       "id": 2,
-      "isNew": false,
       "legend": {
         "alignAsTable": false,
         "avg": false,
@@ -143,7 +141,7 @@
       "nullPointMode": "null",
       "options": { "alertThreshold": true },
       "percentage": false,
-      "pluginVersion": "9.1.1",
+      "pluginVersion": "10.0.0-cloud.3.b04cc88b",
       "pointradius": 2,
       "points": false,
       "renderer": "flot",
@@ -187,7 +185,6 @@
       "gridPos": { "h": 11, "w": 8, "x": 16, "y": 0 },
       "hiddenSeries": false,
       "id": 25,
-      "isNew": false,
       "legend": {
         "alignAsTable": false,
         "avg": false,
@@ -206,7 +203,7 @@
       "nullPointMode": "null",
       "options": { "alertThreshold": true },
       "percentage": false,
-      "pluginVersion": "9.1.1",
+      "pluginVersion": "10.0.0-cloud.3.b04cc88b",
       "pointradius": 2,
       "points": false,
       "renderer": "flot",
@@ -253,7 +250,6 @@
       "gridPos": { "h": 11, "w": 8, "x": 0, "y": 11 },
       "hiddenSeries": false,
       "id": 13,
-      "isNew": false,
       "legend": {
         "alignAsTable": false,
         "avg": false,
@@ -272,7 +268,7 @@
       "nullPointMode": "null",
       "options": { "alertThreshold": true },
       "percentage": false,
-      "pluginVersion": "9.1.1",
+      "pluginVersion": "10.0.0-cloud.3.b04cc88b",
       "pointradius": 2,
       "points": false,
       "renderer": "flot",
@@ -319,7 +315,6 @@
       "gridPos": { "h": 11, "w": 8, "x": 8, "y": 11 },
       "hiddenSeries": false,
       "id": 23,
-      "isNew": false,
       "legend": {
         "alignAsTable": false,
         "avg": false,
@@ -338,7 +333,7 @@
       "nullPointMode": "null",
       "options": { "alertThreshold": true },
       "percentage": false,
-      "pluginVersion": "9.1.1",
+      "pluginVersion": "10.0.0-cloud.3.b04cc88b",
       "pointradius": 2,
       "points": false,
       "renderer": "flot",
@@ -384,7 +379,6 @@
       "gridPos": { "h": 11, "w": 8, "x": 16, "y": 11 },
       "hiddenSeries": false,
       "id": 24,
-      "isNew": false,
       "legend": {
         "alignAsTable": false,
         "avg": false,
@@ -403,7 +397,7 @@
       "nullPointMode": "null",
       "options": { "alertThreshold": true },
       "percentage": false,
-      "pluginVersion": "9.1.1",
+      "pluginVersion": "10.0.0-cloud.3.b04cc88b",
       "pointradius": 2,
       "points": false,
       "renderer": "flot",
@@ -447,7 +441,6 @@
       "gridPos": { "h": 11, "w": 8, "x": 0, "y": 22 },
       "hiddenSeries": false,
       "id": 22,
-      "isNew": false,
       "legend": {
         "alignAsTable": false,
         "avg": false,
@@ -466,7 +459,7 @@
       "nullPointMode": "null",
       "options": { "alertThreshold": true },
       "percentage": false,
-      "pluginVersion": "9.1.1",
+      "pluginVersion": "10.0.0-cloud.3.b04cc88b",
       "pointradius": 2,
       "points": false,
       "renderer": "flot",
@@ -510,7 +503,6 @@
       "gridPos": { "h": 11, "w": 8, "x": 16, "y": 22 },
       "hiddenSeries": false,
       "id": 16,
-      "isNew": false,
       "legend": {
         "alignAsTable": false,
         "avg": false,
@@ -529,7 +521,7 @@
       "nullPointMode": "null",
       "options": { "alertThreshold": true },
       "percentage": false,
-      "pluginVersion": "9.1.1",
+      "pluginVersion": "10.0.0-cloud.3.b04cc88b",
       "pointradius": 2,
       "points": false,
       "renderer": "flot",
@@ -564,7 +556,7 @@
     }
   ],
   "refresh": false,
-  "schemaVersion": 37,
+  "schemaVersion": 38,
   "style": "dark",
   "tags": ["aptos-core"],
   "templating": {
@@ -717,9 +709,9 @@
         "multiFormat": "",
         "name": "pod",
         "options": [],
-        "query": { "query": "up{namespace=~\"$namespace\"}", "refId": "StandardVariableQuery" },
+        "query": { "query": "up{namespace=~\"$namespace\"}", "refId": "PrometheusVariableQueryEditor-VariableQuery" },
         "refresh": 1,
-        "regex": ".*pod=\"(.*?)\".*",
+        "regex": ".*kubernetes_pod_name=\"(.*?)\".*",
         "skipUrlSync": false,
         "sort": 1,
         "type": "query"
@@ -738,8 +730,8 @@
         "multiFormat": "",
         "name": "interval",
         "options": [
-          { "selected": true, "text": "auto", "value": "$__auto_interval_interval" },
-          { "selected": false, "text": "1m", "value": "1m" },
+          { "selected": false, "text": "auto", "value": "$__auto_interval_interval" },
+          { "selected": true, "text": "1m", "value": "1m" },
           { "selected": false, "text": "5m", "value": "5m" },
           { "selected": false, "text": "10m", "value": "10m" },
           { "selected": false, "text": "30m", "value": "30m" },
@@ -768,6 +760,6 @@
   "timezone": "",
   "title": "system",
   "uid": "system",
-  "version": 1,
+  "version": 2,
   "weekStart": ""
 }
diff --git a/dashboards/system.json.gz b/dashboards/system.json.gz
index ea26d8a7b9b66b9f5fc0c0e806baea00c594bc1f..aec70bf782cf8f87424b0ee029d2ab7e1d1d77e1 100644
GIT binary patch
literal 2585
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

literal 2561
zcmV+c3jXyUiwFP!000001MOUGbKAHP{+?gK;kX^gm3*S#lbKG(7uPrGU0!-lJkvTE
z4opH4Y7$@o(6&z1{q|b`d;>|>rfWO0&3uT&1+V}X&+a}1WXxYUj*BQ|5=p|Sa9=xf
z5P>ivLc-IDesVIYE;&s}B;Qgf^aiCgL=p*>@&GFxjw@%0`sPkJ8Y7C_f#aqmRFdJ)
z`N;^K;m~y!6(yLW(?~UwJjE6Hl!Pr(5-|FPMT{%0d~%9bM+0ZW^WeYj?SbRHbSsr9
ziuHK*%gH)_cJ?F8rKr}Eh)=LIbBIVx)K_l=irpB=V7gCdAQ+=a;DM?h==ynn#EaJQE7g?F)Q-Yp1Fl@WJ!FPXmh!@wWF$hM1E7MM-_2IC@yr|#_r!z
z%xCq+V#+Rl0nLTUD@76~_3E%3KjWEb5sO2Dqp(?UPiu`YWqXIJfN{{?C?PV!R}@`|
z9R2zAMTQ|4heXy^-5nDVpy*#1@gtb6e8;Gq=1ZrLlT1G`7DcF4MUK+omc=xP(hwgbF6u4MFit*^xDHce45jjeoMP@A`OR#7(jn$6=Jzh@U!=(q`@IBJ_*M3B(%)e*2*OZU`_+5(^M^A}7f+LGSLlH<1O
z?arKV7Gs!TDk{#rGCwG)FDj_2F0QQ}bFRJ4mW~zt-Y_~Q6Vq#m$0&`YFi$BZ24~QN
zt5MUqK2R#m#V%tYD8Ow_4F%Lfx{xS1
zYjms9QG&y^WR<0vGVG{-C0r{>nInl;A(~1AYPcUHsh+fIOmGbcm1QH0gFcxk~%y%V*NW)1Wd=pu8sV!2Kln!kOU0ytCwfU%w;{550yEs{a
zb-)~O_q9qCRIn)0nS>zk8~fW;@}`FI;L?_L2j0d0#zaAYu1Fo>LGKGBkGuB5h?DRi4kgs<~O68rfh*tHU
zt-j|MPl#XSyZoNliC=h|J-_JrMb9s85F@mvn{te^^b|)}`sXZ4Rmzq~3O^M%{EnLt
ziGlzqqtc8jh!BZYwe_{(YDqs{4)OXLa1iGQr*#$q0)<4*9?wi3j!m@=Y-yO)0TE}0
zS~-7u(&XwpoTBtp>CsT7z1vZxjh-s?RH>&*Jyp7nU`$(`r65;XTn?wOms{os56pUnPj`*~0k!jgU`q~{~G
zosf=%#Owd0v?nA_o{)435+7gf>>X|$?!DUGINUkd-8#7K8A^>qP%PEP3vi$SlXGmg
zF}@?8fc&k6@Odr&$;S>jp`zG>S<1mbFacVUv!M58fu7ZI(2vW?e_rIbZosOm1+4}w
zR|HcWqcR+C?i#V2nUxF?H}{1UcdWQ5kxUE&#<6SkN*pH#CGs@+|2DD<0&ouYD{OuCM)feJ!`Ae)t4yrvmJ3ea*U3=!_(vd2}?RK^rs5
z14M-tHSb=kQ=qQMvqx0HUV*9;_>v8O2oYSpV7gxi73egJEqvV3&nFbiCqV5p8s&CC
zVC~+iy9S`0Iy->S^6vtfdU(Ex$*U9sw-1&Iun_8ZAYA$?hQn)IEs4Lp;+6kMA__q*
zJVpRUcw_jd?xxj|uYvfTAop9f`&)zdddOxW%LZyLTrzmxcYrJ@;lp6_2J8~xTaIc8
zq3hinbZ-)G6)Y^^uJ}IaST@|=b6CyZSC$5|Rme78wHC#@))J!m{sQqcMRTq04ZvKy
zK0gjPU$JwrsO$Kl){8Br@YtpGw%vNWTWfDr>wMI${bsHGX2?RqK4KTl>vXSX(#MzG&XMC+o$7
z?RWqP8NezJyy;+PIslsuyl}7^4qyZWt+g$#ZnVYKJ9$wmJT8x<`m?<0T$)S6)xid2
zRL%9-#c)%vybhP@*{xJgNN}bPaI>R>Y!ZcQn^OlJFO}K!hw)(JiJtk$9K+z-01W_=
z+0~r4RU(kx)-*EU&Oo}cWj^$(8R#fu+w=U5(K0EN$6sOwuLrRaW<;VYIxkLJ%&qPh
X7@z4I;I*n3ix+
Date: Fri, 9 Jun 2023 11:52:10 -0700
Subject: [PATCH 132/200] [Sharding] Integrate executor benchmark with sharded
 block-stm (#8566)

* generate non-conflicting coin transfer txns for executor-benchmark

* tidy up

* non-conflicting coin transfer as a txn type

* revert run_transfer

* revert

* tidy up

* BurnAndRecycleSampler keeps samples and replace later.

* lint

* lint

* rename

* simplify BasicSampler
---
 .../src/sharded_block_executor/counters.rs    |  14 ++
 .../src/sharded_block_executor/mod.rs         |   4 +-
 crates/transaction-generator-lib/src/args.rs  |   7 +
 crates/transaction-generator-lib/src/lib.rs   |  21 ++-
 .../src/p2p_transaction_generator.rs          | 163 ++++++++++++++++--
 .../src/account_generator.rs                  |   3 +-
 execution/executor-benchmark/src/lib.rs       |  78 ++++++---
 .../src/transaction_generator.rs              |  41 +++--
 8 files changed, 277 insertions(+), 54 deletions(-)
 create mode 100644 aptos-move/aptos-vm/src/sharded_block_executor/counters.rs

diff --git a/aptos-move/aptos-vm/src/sharded_block_executor/counters.rs b/aptos-move/aptos-vm/src/sharded_block_executor/counters.rs
new file mode 100644
index 0000000000000..85d0b2d6aacd4
--- /dev/null
+++ b/aptos-move/aptos-vm/src/sharded_block_executor/counters.rs
@@ -0,0 +1,14 @@
+// Copyright © Aptos Foundation
+// Parts of the project are originally copyright © Meta Platforms, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+use aptos_metrics_core::{register_int_gauge, IntGauge};
+use once_cell::sync::Lazy;
+
+pub static NUM_EXECUTOR_SHARDS: Lazy = Lazy::new(|| {
+    register_int_gauge!(
+        "num_executor_shards",
+        "Number of shards for the sharded block executor"
+    )
+    .unwrap()
+});
diff --git a/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs b/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs
index 7efd7f9578b17..f2fcf476abb99 100644
--- a/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs
+++ b/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs
@@ -2,7 +2,7 @@
 // Parts of the project are originally copyright © Meta Platforms, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-use crate::sharded_block_executor::executor_shard::ExecutorShard;
+use crate::sharded_block_executor::{counters::NUM_EXECUTOR_SHARDS, executor_shard::ExecutorShard};
 use aptos_block_partitioner::{BlockPartitioner, UniformPartitioner};
 use aptos_logger::{error, info, trace};
 use aptos_state_view::StateView;
@@ -19,6 +19,7 @@ use std::{
 };
 
 pub mod block_executor_client;
+mod counters;
 mod executor_shard;
 
 /// A wrapper around sharded block executors that manages multiple shards and aggregates the results.
@@ -78,6 +79,7 @@ impl ShardedBlockExecutor {
         concurrency_level_per_shard: usize,
         maybe_block_gas_limit: Option,
     ) -> Result, VMStatus> {
+        NUM_EXECUTOR_SHARDS.set(self.num_executor_shards as i64);
         let block_partitions = self.partitioner.partition(block, self.num_executor_shards);
         // Number of partitions might be smaller than the number of executor shards in case of
         // block size is smaller than number of executor shards.
diff --git a/crates/transaction-generator-lib/src/args.rs b/crates/transaction-generator-lib/src/args.rs
index d50e4fb8ca7fa..5325266830ce6 100644
--- a/crates/transaction-generator-lib/src/args.rs
+++ b/crates/transaction-generator-lib/src/args.rs
@@ -13,6 +13,7 @@ pub enum TransactionTypeArg {
     NoOp5Signers,
     CoinTransfer,
     CoinTransferWithInvalid,
+    NonConflictingCoinTransfer,
     AccountGeneration,
     AccountGenerationLargePool,
     PublishPackage,
@@ -51,6 +52,12 @@ impl TransactionTypeArg {
                 invalid_transaction_ratio: 0,
                 sender_use_account_pool,
             },
+            TransactionTypeArg::NonConflictingCoinTransfer => {
+                TransactionType::NonConflictingCoinTransfer {
+                    invalid_transaction_ratio: 0,
+                    sender_use_account_pool,
+                }
+            },
             TransactionTypeArg::CoinTransferWithInvalid => TransactionType::CoinTransfer {
                 invalid_transaction_ratio: 10,
                 sender_use_account_pool,
diff --git a/crates/transaction-generator-lib/src/lib.rs b/crates/transaction-generator-lib/src/lib.rs
index 06dc51558a2ae..2cd27808c5347 100644
--- a/crates/transaction-generator-lib/src/lib.rs
+++ b/crates/transaction-generator-lib/src/lib.rs
@@ -42,7 +42,7 @@ use self::{
 use crate::{
     accounts_pool_wrapper::AccountsPoolWrapperCreator,
     batch_transfer::BatchTransferTransactionGeneratorCreator,
-    entry_points::EntryPointTransactionGenerator,
+    entry_points::EntryPointTransactionGenerator, p2p_transaction_generator::SamplingMode,
 };
 pub use publishing::module_simple::EntryPoints;
 
@@ -50,6 +50,10 @@ pub const SEND_AMOUNT: u64 = 1;
 
 #[derive(Debug, Copy, Clone)]
 pub enum TransactionType {
+    NonConflictingCoinTransfer {
+        invalid_transaction_ratio: usize,
+        sender_use_account_pool: bool,
+    },
     CoinTransfer {
         invalid_transaction_ratio: usize,
         sender_use_account_pool: bool,
@@ -211,6 +215,20 @@ pub async fn create_txn_generator_creator(
         for (transaction_type, weight) in transaction_mix {
             let txn_generator_creator: Box = match transaction_type
             {
+                TransactionType::NonConflictingCoinTransfer {
+                    invalid_transaction_ratio,
+                    sender_use_account_pool,
+                } => wrap_accounts_pool(
+                    Box::new(P2PTransactionGeneratorCreator::new(
+                        txn_factory.clone(),
+                        SEND_AMOUNT,
+                        addresses_pool.clone(),
+                        *invalid_transaction_ratio,
+                        SamplingMode::BurnAndRecycle(addresses_pool.read().len() / 2),
+                    )),
+                    *sender_use_account_pool,
+                    accounts_pool.clone(),
+                ),
                 TransactionType::CoinTransfer {
                     invalid_transaction_ratio,
                     sender_use_account_pool,
@@ -220,6 +238,7 @@ pub async fn create_txn_generator_creator(
                         SEND_AMOUNT,
                         addresses_pool.clone(),
                         *invalid_transaction_ratio,
+                        SamplingMode::Basic,
                     )),
                     *sender_use_account_pool,
                     accounts_pool.clone(),
diff --git a/crates/transaction-generator-lib/src/p2p_transaction_generator.rs b/crates/transaction-generator-lib/src/p2p_transaction_generator.rs
index 7a3f9a6c1bf0e..e45c453f58f45 100644
--- a/crates/transaction-generator-lib/src/p2p_transaction_generator.rs
+++ b/crates/transaction-generator-lib/src/p2p_transaction_generator.rs
@@ -13,29 +13,161 @@ use rand::{
     rngs::StdRng,
     Rng, RngCore, SeedableRng,
 };
-use std::{cmp::max, sync::Arc};
+use std::{
+    cmp::{max, min},
+    sync::Arc,
+};
+
+pub enum SamplingMode {
+    /// See `BasicSampler`.
+    Basic,
+    /// See `BurnAndRecycleSampler`.
+    BurnAndRecycle(usize),
+}
+
+/// Specifies how to get a given number of samples from an item pool.
+pub trait Sampler: Send + Sync {
+    fn sample_from_pool(
+        &mut self,
+        rng: &mut StdRng,
+        pool: &mut Vec,
+        num_samples: usize,
+    ) -> Vec;
+}
+
+/// A sampler that samples a random subset of the pool. Samples are replaced immediately.
+pub struct BasicSampler {}
+
+impl BasicSampler {
+    fn new() -> Self {
+        Self {}
+    }
+}
+
+impl Sampler for BasicSampler {
+    fn sample_from_pool(
+        &mut self,
+        rng: &mut StdRng,
+        pool: &mut Vec,
+        num_samples: usize,
+    ) -> Vec {
+        let mut samples = Vec::with_capacity(num_samples);
+        let num_available = pool.len();
+        for _ in 0..num_samples {
+            let idx = rng.gen_range(0, num_available);
+            samples.push(pool[idx].clone());
+        }
+        samples
+    }
+}
+
+/// A samplers that samples from a pool but do not replace items until the pool is depleted.
+/// The pool is divided into sub-pools. Replacement is done with with each sub-pool shuffled internally.
+///
+/// Here is an example. Say the initial pool is `[I, J, K, X, Y, Z]`.
+/// A `BurnAndRecycleSampler` is created with `replace_batch_size=3` to sample from the pool.
+/// The first 6 samples are guaranteed to be `Z`, `Y`, `X`, `K`, `J`, `I`.
+/// Then at the beginning of the 7-th sampling,
+/// sub-pools `{I, J, K}`, `{X, Y, Z}` are shuffled and replaced.
+/// A possible state of the pool is `[K, I, J, Y, X, Z]`.
+///
+/// This behavior helps generate a block of non-conflicting coin transfer transactions,
+/// when there are 2+ sub-pools of size larger than or equal to the block size.
+pub struct BurnAndRecycleSampler {
+    /// We store all sub-pools together in 1 Vec: `item_pool[segment_size * x..segment_size * (x+1)]` being the x-th sub-pool.
+    to_be_replaced: Vec,
+    sub_pool_size: usize,
+}
+
+impl BurnAndRecycleSampler {
+    fn new(replace_batch_size: usize) -> Self {
+        Self {
+            to_be_replaced: vec![],
+            sub_pool_size: replace_batch_size,
+        }
+    }
+
+    fn sample_one_from_pool(&mut self, rng: &mut StdRng, pool: &mut Vec) -> T {
+        if pool.is_empty() {
+            let num_addresses = self.to_be_replaced.len();
+            for replace_batch_start in (0..num_addresses).step_by(self.sub_pool_size) {
+                let end = min(replace_batch_start + self.sub_pool_size, num_addresses);
+                self.to_be_replaced[replace_batch_start..end].shuffle(rng);
+            }
+            for _ in 0..num_addresses {
+                pool.push(self.to_be_replaced.pop().unwrap());
+            }
+        }
+        let sample = pool.pop().unwrap();
+        self.to_be_replaced.push(sample.clone());
+        sample
+    }
+}
+
+impl Sampler for BurnAndRecycleSampler {
+    fn sample_from_pool(
+        &mut self,
+        rng: &mut StdRng,
+        pool: &mut Vec,
+        num_samples: usize,
+    ) -> Vec {
+        (0..num_samples)
+            .map(|_| self.sample_one_from_pool(rng, pool))
+            .collect()
+    }
+}
+
+#[test]
+fn test_burn_and_recycle_sampler() {
+    use std::collections::HashSet;
+    let mut rng = StdRng::from_entropy();
+    let mut sampler = BurnAndRecycleSampler::new(3);
+    let mut pool: Vec = (0..8).collect();
+    let samples = (0..16)
+        .map(|_| sampler.sample_one_from_pool(&mut rng, &mut pool))
+        .collect::>();
+    // `samples[0..3]` and `samples[8..11]` are 2 permutations of sub-pool 0.
+    assert_eq!(
+        samples[0..3].iter().collect::>(),
+        samples[8..11].iter().collect::>()
+    );
+    // `samples[3..6]` and `samples[11..14]` are 2 permutations of sub-pool 1.
+    assert_eq!(
+        samples[3..6].iter().collect::>(),
+        samples[11..14].iter().collect::>()
+    );
+    // `samples[6..8]` and `samples[14..16]` are 2 permutations of sub-pool 1.
+    assert_eq!(
+        samples[6..8].iter().collect::>(),
+        samples[14..16].iter().collect::>()
+    );
+}
 
 pub struct P2PTransactionGenerator {
     rng: StdRng,
     send_amount: u64,
     txn_factory: TransactionFactory,
     all_addresses: Arc>>,
+    sampler: Box>,
     invalid_transaction_ratio: usize,
 }
 
 impl P2PTransactionGenerator {
     pub fn new(
-        rng: StdRng,
+        mut rng: StdRng,
         send_amount: u64,
         txn_factory: TransactionFactory,
         all_addresses: Arc>>,
         invalid_transaction_ratio: usize,
+        sampler: Box>,
     ) -> Self {
+        all_addresses.write().shuffle(&mut rng);
         Self {
             rng,
             send_amount,
             txn_factory,
             all_addresses,
+            sampler,
             invalid_transaction_ratio,
         }
     }
@@ -53,7 +185,7 @@ impl P2PTransactionGenerator {
     }
 
     fn generate_invalid_transaction(
-        &self,
+        &mut self,
         rng: &mut StdRng,
         sender: &mut LocalAccount,
         receiver: &AccountAddress,
@@ -131,12 +263,12 @@ impl TransactionGenerator for P2PTransactionGenerator {
         };
         let mut num_valid_tx = num_to_create * (1 - invalid_size);
 
-        let receivers = self
-            .all_addresses
-            .read()
-            .choose_multiple(&mut self.rng, num_to_create)
-            .cloned()
-            .collect::>();
+        let receivers: Vec = {
+            let mut all_addrs = self.all_addresses.write();
+            self.sampler
+                .sample_from_pool(&mut self.rng, all_addrs.as_mut(), num_to_create)
+        };
+
         assert!(
             receivers.len() >= num_to_create,
             "failed: {} >= {}",
@@ -167,6 +299,7 @@ pub struct P2PTransactionGeneratorCreator {
     amount: u64,
     all_addresses: Arc>>,
     invalid_transaction_ratio: usize,
+    sampling_mode: SamplingMode,
 }
 
 impl P2PTransactionGeneratorCreator {
@@ -175,24 +308,34 @@ impl P2PTransactionGeneratorCreator {
         amount: u64,
         all_addresses: Arc>>,
         invalid_transaction_ratio: usize,
+        sampling_mode: SamplingMode,
     ) -> Self {
         Self {
             txn_factory,
             amount,
             all_addresses,
             invalid_transaction_ratio,
+            sampling_mode,
         }
     }
 }
 
 impl TransactionGeneratorCreator for P2PTransactionGeneratorCreator {
     fn create_transaction_generator(&mut self) -> Box {
+        let rng = StdRng::from_entropy();
+        let sampler: Box> = match self.sampling_mode {
+            SamplingMode::Basic => Box::new(BasicSampler::new()),
+            SamplingMode::BurnAndRecycle(recycle_batch_size) => {
+                Box::new(BurnAndRecycleSampler::new(recycle_batch_size))
+            },
+        };
         Box::new(P2PTransactionGenerator::new(
-            StdRng::from_entropy(),
+            rng,
             self.amount,
             self.txn_factory.clone(),
             self.all_addresses.clone(),
             self.invalid_transaction_ratio,
+            sampler,
         ))
     }
 }
diff --git a/execution/executor-benchmark/src/account_generator.rs b/execution/executor-benchmark/src/account_generator.rs
index 426e32e468d0a..83367d254b0e0 100644
--- a/execution/executor-benchmark/src/account_generator.rs
+++ b/execution/executor-benchmark/src/account_generator.rs
@@ -62,7 +62,7 @@ impl AccountGenerator {
 pub struct AccountCache {
     generator: AccountGenerator,
     pub accounts: VecDeque,
-    rng: StdRng,
+    pub rng: StdRng,
 }
 
 impl AccountCache {
@@ -113,7 +113,6 @@ impl AccountCache {
             .map(|i| self.accounts[i].address())
             .collect();
         let sender = &mut self.accounts[sender_idx];
-
         (sender, receivers)
     }
 }
diff --git a/execution/executor-benchmark/src/lib.rs b/execution/executor-benchmark/src/lib.rs
index b854b1a0a9c32..061b88dd5328f 100644
--- a/execution/executor-benchmark/src/lib.rs
+++ b/execution/executor-benchmark/src/lib.rs
@@ -29,10 +29,12 @@ use aptos_executor::{
 use aptos_jellyfish_merkle::metrics::{
     APTOS_JELLYFISH_INTERNAL_ENCODED_BYTES, APTOS_JELLYFISH_LEAF_ENCODED_BYTES,
 };
-use aptos_logger::info;
+use aptos_logger::{info, warn};
+use aptos_sdk::types::LocalAccount;
 use aptos_storage_interface::DbReaderWriter;
 use aptos_transaction_generator_lib::{
     create_txn_generator_creator, TransactionGeneratorCreator, TransactionType,
+    TransactionType::NonConflictingCoinTransfer,
 };
 use aptos_vm::counters::TXN_GAS_USAGE;
 use db_reliable_submitter::DbReliableTransactionSubmitter;
@@ -84,11 +86,12 @@ fn create_checkpoint(
 }
 
 /// Runs the benchmark with given parameters.
+#[allow(clippy::too_many_arguments)]
 pub fn run_benchmark(
     block_size: usize,
     num_blocks: usize,
     transaction_type: Option,
-    transactions_per_sender: usize,
+    mut transactions_per_sender: usize,
     num_main_signer_accounts: usize,
     num_additional_dst_pool_accounts: usize,
     source_dir: impl AsRef,
@@ -114,14 +117,34 @@ pub fn run_benchmark(
     config.storage.rocksdb_configs.use_sharded_state_merkle_db = use_sharded_state_merkle_db;
 
     let (db, executor) = init_db_and_executor::(&config);
-
     let transaction_generator_creator = transaction_type.map(|transaction_type| {
-        init_workload::(
+        let num_existing_accounts = TransactionGenerator::read_meta(&source_dir);
+        let num_accounts_to_be_loaded = std::cmp::min(
+            num_existing_accounts,
+            num_main_signer_accounts + num_additional_dst_pool_accounts,
+        );
+
+        let mut num_accounts_to_skip = 0;
+        if let NonConflictingCoinTransfer{..} = transaction_type {
+            // In case of random non-conflicting coin transfer using `P2PTransactionGenerator`,
+            // `3*block_size` addresses is required:
+            // `block_size` number of signers, and 2 groups of burn-n-recycle recipients used alternatively.
+            if num_accounts_to_be_loaded < block_size * 3 {
+                panic!("Cannot guarantee random non-conflicting coin transfer using `P2PTransactionGenerator`.");
+            }
+            num_accounts_to_skip = block_size;
+        }
+
+        let accounts_cache =
+            TransactionGenerator::gen_user_account_cache(db.reader.clone(), num_accounts_to_be_loaded, num_accounts_to_skip);
+        let (main_signer_accounts, burner_accounts) =
+            accounts_cache.split(num_main_signer_accounts);
+
+        init_workload::(
             transaction_type,
-            num_main_signer_accounts,
-            num_additional_dst_pool_accounts,
+            main_signer_accounts,
+            burner_accounts,
             db.clone(),
-            &source_dir,
             // Initialization pipeline is temporary, so needs to be fully committed.
             // No discards/aborts allowed during initialization, even if they are allowed later.
             PipelineConfig {
@@ -138,13 +161,28 @@ pub fn run_benchmark(
 
     let (pipeline, block_sender) =
         Pipeline::new(executor, version, pipeline_config.clone(), Some(num_blocks));
+
+    let mut num_accounts_to_load = num_main_signer_accounts;
+    if let Some(NonConflictingCoinTransfer { .. }) = transaction_type {
+        // In case of non-conflicting coin transfer,
+        // `aptos_executor_benchmark::transaction_generator::TransactionGenerator` needs to hold
+        // at least `block_size` number of accounts, all as signer only.
+        num_accounts_to_load = block_size;
+        if transactions_per_sender > 1 {
+            warn!(
+            "Overriding transactions_per_sender to 1 for non_conflicting_txns_per_block workload"
+        );
+            transactions_per_sender = 1;
+        }
+    }
+
     let mut generator = TransactionGenerator::new_with_existing_db(
         db.clone(),
         genesis_key,
         block_sender,
         source_dir,
         version,
-        Some(num_main_signer_accounts),
+        Some(num_accounts_to_load),
     );
 
     let mut start_time = Instant::now();
@@ -180,6 +218,7 @@ pub fn run_benchmark(
         .collect::>();
     let start_commit_total = APTOS_EXECUTOR_COMMIT_BLOCKS_SECONDS.get_sample_sum();
 
+    let start_vm_time = APTOS_EXECUTOR_VM_EXECUTE_BLOCK_SECONDS.get_sample_sum();
     if let Some(transaction_generator_creator) = transaction_generator_creator {
         generator.run_workload(
             block_size,
@@ -200,6 +239,11 @@ pub fn run_benchmark(
     let elapsed = start_time.elapsed().as_secs_f64();
     let delta_v = (db.reader.get_latest_version().unwrap() - version) as f64;
     let delta_gas = TXN_GAS_USAGE.get_sample_sum() - start_gas;
+    let delta_vm_time = APTOS_EXECUTOR_VM_EXECUTE_BLOCK_SECONDS.get_sample_sum() - start_vm_time;
+    info!(
+        "VM execution TPS {} txn/s",
+        (delta_v / delta_vm_time) as usize
+    );
     info!(
         "Executed workload {}",
         if let Some(ttype) = transaction_type {
@@ -251,12 +295,11 @@ pub fn run_benchmark(
     }
 }
 
-fn init_workload>(
+fn init_workload(
     transaction_type: TransactionType,
-    num_main_signer_accounts: usize,
-    num_additional_dst_pool_accounts: usize,
+    mut main_signer_accounts: Vec,
+    burner_accounts: Vec,
     db: DbReaderWriter,
-    db_dir: &P,
     pipeline_config: PipelineConfig,
 ) -> Box
 where
@@ -271,17 +314,6 @@ where
     );
 
     let runtime = Runtime::new().unwrap();
-
-    let num_existing_accounts = TransactionGenerator::read_meta(db_dir);
-    let num_cached_accounts = std::cmp::min(
-        num_existing_accounts,
-        num_main_signer_accounts + num_additional_dst_pool_accounts,
-    );
-    let accounts_cache =
-        TransactionGenerator::gen_user_account_cache(db.reader.clone(), num_cached_accounts);
-
-    let (mut main_signer_accounts, burner_accounts) =
-        accounts_cache.split(num_main_signer_accounts);
     let transaction_factory = TransactionGenerator::create_transaction_factory();
 
     let (txn_generator_creator, _address_pool, _account_pool) = runtime.block_on(async {
diff --git a/execution/executor-benchmark/src/transaction_generator.rs b/execution/executor-benchmark/src/transaction_generator.rs
index 0a5481cb0a7a5..fd0b57323faba 100644
--- a/execution/executor-benchmark/src/transaction_generator.rs
+++ b/execution/executor-benchmark/src/transaction_generator.rs
@@ -18,6 +18,7 @@ use aptos_types::{
 use chrono::Local;
 use indicatif::{ProgressBar, ProgressStyle};
 use itertools::Itertools;
+use rand::thread_rng;
 use rayon::iter::{IntoParallelRefIterator, ParallelIterator};
 use serde::{Deserialize, Serialize};
 use std::{
@@ -141,11 +142,15 @@ impl TransactionGenerator {
         accounts
     }
 
-    pub fn gen_user_account_cache(reader: Arc, num_accounts: usize) -> AccountCache {
+    pub fn gen_user_account_cache(
+        reader: Arc,
+        num_accounts: usize,
+        num_to_skip: usize,
+    ) -> AccountCache {
         Self::resync_sequence_numbers(
             reader,
             Self::gen_account_cache(
-                AccountGenerator::new_for_user_accounts(0),
+                AccountGenerator::new_for_user_accounts(num_to_skip as u64),
                 num_accounts,
                 "user",
             ),
@@ -185,7 +190,7 @@ impl TransactionGenerator {
             main_signer_accounts: num_main_signer_accounts.map(|num_main_signer_accounts| {
                 let num_cached_accounts =
                     std::cmp::min(num_existing_accounts, num_main_signer_accounts);
-                Self::gen_user_account_cache(db.reader.clone(), num_cached_accounts)
+                Self::gen_user_account_cache(db.reader.clone(), num_cached_accounts, 0)
             }),
             num_existing_accounts,
             version,
@@ -275,23 +280,25 @@ impl TransactionGenerator {
         transactions_per_sender: usize,
     ) {
         assert!(self.block_sender.is_some());
+        let num_senders_per_block =
+            (block_size + transactions_per_sender - 1) / transactions_per_sender;
+        let account_pool_size = self.main_signer_accounts.as_ref().unwrap().accounts.len();
         let mut transaction_generator =
             transaction_generator_creator.create_transaction_generator();
-
         for _ in 0..num_blocks {
-            // TODO: handle when block_size isn't divisible by transactions_per_sender
-            let transactions: Vec<_> = (0..(block_size / transactions_per_sender))
-                .into_iter()
-                .flat_map(|_| {
-                    let sender = self.main_signer_accounts.as_mut().unwrap().get_random();
-                    transaction_generator
-                        .generate_transactions(sender, transactions_per_sender)
-                        .into_iter()
-                        .map(Transaction::UserTransaction)
-                        .collect::>()
-                })
-                .chain(once(Transaction::StateCheckpoint(HashValue::random())))
-                .collect();
+            let transactions: Vec<_> = rand::seq::index::sample(
+                &mut thread_rng(),
+                account_pool_size,
+                num_senders_per_block,
+            )
+            .into_iter()
+            .flat_map(|idx| {
+                let sender = &mut self.main_signer_accounts.as_mut().unwrap().accounts[idx];
+                transaction_generator.generate_transactions(sender, transactions_per_sender)
+            })
+            .map(Transaction::UserTransaction)
+            .chain(once(Transaction::StateCheckpoint(HashValue::random())))
+            .collect();
             self.version += transactions.len() as Version;
 
             if let Some(sender) = &self.block_sender {

From b4d12adb0b3ad2323ab6609d5090aa339bc2caf8 Mon Sep 17 00:00:00 2001
From: Balaji Arun 
Date: Fri, 9 Jun 2023 13:36:33 -0700
Subject: [PATCH 133/200] [terraform][gcp][testnet] make default daily 24h
 (#8607)

---
 terraform/aptos-node-testnet/gcp/variables.tf | 6 +++---
 terraform/aptos-node/gcp/variables.tf         | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/terraform/aptos-node-testnet/gcp/variables.tf b/terraform/aptos-node-testnet/gcp/variables.tf
index d7e88193a713c..2f95addf051a7 100644
--- a/terraform/aptos-node-testnet/gcp/variables.tf
+++ b/terraform/aptos-node-testnet/gcp/variables.tf
@@ -213,9 +213,9 @@ variable "gke_maintenance_policy" {
   })
   default = {
     recurring_window = {
-      start_time = "2023-06-01T14:00:00Z"
-      end_time   = "2023-06-01T18:00:00Z"
-      recurrence = "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"
+      start_time = "2023-06-15T00:00:00Z"
+      end_time   = "2023-06-15T23:59:00Z"
+      recurrence = "FREQ=DAILY"
     }
   }
 }
diff --git a/terraform/aptos-node/gcp/variables.tf b/terraform/aptos-node/gcp/variables.tf
index 3028a1f7e2f77..c5dd42daf4f58 100644
--- a/terraform/aptos-node/gcp/variables.tf
+++ b/terraform/aptos-node/gcp/variables.tf
@@ -252,9 +252,9 @@ variable "gke_maintenance_policy" {
   })
   default = {
     recurring_window = {
-      start_time = "2023-06-01T14:00:00Z"
-      end_time   = "2023-06-01T18:00:00Z"
-      recurrence = "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"
+      start_time = "2023-06-15T00:00:00Z"
+      end_time   = "2023-06-15T23:59:00Z"
+      recurrence = "FREQ=DAILY"
     }
   }
 }

From fe3af3e2c455e11b2a64874c0b516b635b272667 Mon Sep 17 00:00:00 2001
From: Stelian Ionescu 
Date: Fri, 9 Jun 2023 15:10:54 -0400
Subject: [PATCH 134/200] [Helm] Update autoscaling charts

---
 terraform/helm/autoscaling/Chart.lock            |   6 +++---
 terraform/helm/autoscaling/Chart.yaml            |   2 +-
 .../autoscaling/charts/metrics-server-3.10.0.tgz | Bin 0 -> 8452 bytes
 .../autoscaling/charts/metrics-server-3.8.2.tgz  | Bin 6208 -> 0 bytes
 terraform/helm/autoscaling/values.yaml           |   2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)
 create mode 100644 terraform/helm/autoscaling/charts/metrics-server-3.10.0.tgz
 delete mode 100644 terraform/helm/autoscaling/charts/metrics-server-3.8.2.tgz

diff --git a/terraform/helm/autoscaling/Chart.lock b/terraform/helm/autoscaling/Chart.lock
index 68cae46b3ddaa..b62abaaf3221d 100644
--- a/terraform/helm/autoscaling/Chart.lock
+++ b/terraform/helm/autoscaling/Chart.lock
@@ -1,6 +1,6 @@
 dependencies:
 - name: metrics-server
   repository: https://kubernetes-sigs.github.io/metrics-server/
-  version: 3.8.2
-digest: sha256:fa1a19fa0f1ff4bae7f9e397277af3a832718ba50351e6ddf3b72a398d17fd0a
-generated: "2022-04-12T17:19:04.312907-07:00"
+  version: 3.10.0
+digest: sha256:e5771e2fb7d8cee664fa3f7fbde4bb626f6ce4e8ba12504a85da3e8261a19d9a
+generated: "2023-06-09T17:24:05.737993-04:00"
diff --git a/terraform/helm/autoscaling/Chart.yaml b/terraform/helm/autoscaling/Chart.yaml
index 896fe206aa75d..623c9ee16c41b 100644
--- a/terraform/helm/autoscaling/Chart.yaml
+++ b/terraform/helm/autoscaling/Chart.yaml
@@ -4,5 +4,5 @@ version: 0.1.0
 
 dependencies:
   - name: metrics-server
-    version: 3.8.2
+    version: 3.10.0
     repository: "https://kubernetes-sigs.github.io/metrics-server/"
diff --git a/terraform/helm/autoscaling/charts/metrics-server-3.10.0.tgz b/terraform/helm/autoscaling/charts/metrics-server-3.10.0.tgz
new file mode 100644
index 0000000000000000000000000000000000000000..2b38fd615daa7d6057c2109b374d9e2399ed7eea
GIT binary patch
literal 8452
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
e4>?SBWmk4(S9WFd^1lH90RR8x
Date: Fri, 9 Jun 2023 14:28:10 -0700
Subject: [PATCH 135/200] [gha] set up merge gatekeeper (#8586)

---
 .github/workflows/merge-gatekeeper.yaml | 34 +++++++++++++++++++++++++
 1 file changed, 34 insertions(+)
 create mode 100644 .github/workflows/merge-gatekeeper.yaml

diff --git a/.github/workflows/merge-gatekeeper.yaml b/.github/workflows/merge-gatekeeper.yaml
new file mode 100644
index 0000000000000..1a6fd7b3edddd
--- /dev/null
+++ b/.github/workflows/merge-gatekeeper.yaml
@@ -0,0 +1,34 @@
+name: "*Merge Gatekeeper"
+
+on:
+  pull_request:
+    types: [labeled, opened, synchronize, reopened, auto_merge_enabled]
+
+env:
+  MERGE_GATEKEEPER_ALLOWLIST: "rustielin,perryjrandall,geekflyer,sherry-x,sionescu,ibalajiarun,igor-aptos,sitalkedia"
+
+jobs:
+  merge-gatekeeper:
+    runs-on: ubuntu-latest
+    # Restrict permissions of the GITHUB_TOKEN.
+    # Docs: https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs
+    permissions:
+      checks: read
+      statuses: read
+    steps:
+      - name: Beta allowlist for certain actors
+        shell: bash
+        run: |
+          if grep -v "$GITHUB_ACTOR" <<< "$MERGE_GATEKEEPER_ALLOWLIST"; then
+            echo "Your username is not in the beta testing list for merge gatekeeper."
+            echo "Please add yourself if you are interested, in the env MERGE_GATEKEEPER_ALLOWLIST."
+            gh run cancel ${{ github.run_id }}
+          fi
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+      - name: Run Merge Gatekeeper
+        uses: upsidr/merge-gatekeeper@09af7a82c1666d0e64d2bd8c01797a0bcfd3bb5d # pin v1.2.1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          timeout: 5400 # 1.5 hour

From dd1cfd31290c3691b5f12830d37eb7e6dc29ee7a Mon Sep 17 00:00:00 2001
From: Nicolas Martin 
Date: Fri, 9 Jun 2023 18:36:36 -0400
Subject: [PATCH 136/200] consistant operation naming (#8600)

Co-authored-by: nicolas-martin 
---
 crates/aptos-rosetta/src/types/misc.rs    | 10 +++++-----
 crates/aptos-rosetta/src/types/objects.rs |  4 ++--
 testsuite/smoke-test/src/rosetta.rs       |  2 +-
 3 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/crates/aptos-rosetta/src/types/misc.rs b/crates/aptos-rosetta/src/types/misc.rs
index d3af740566482..06e1ddb462c33 100644
--- a/crates/aptos-rosetta/src/types/misc.rs
+++ b/crates/aptos-rosetta/src/types/misc.rs
@@ -109,7 +109,7 @@ pub enum OperationType {
     InitializeStakePool,
     ResetLockup,
     UnlockStake,
-    WithdrawUndelegated,
+    WithdrawUndelegatedFunds,
     DistributeStakingRewards,
     AddDelegatedStake,
     UnlockDelegatedStake,
@@ -131,7 +131,7 @@ impl OperationType {
     const UNLOCK_DELEGATED_STAKE: &'static str = "unlock_delegated_stake";
     const UNLOCK_STAKE: &'static str = "unlock_stake";
     const WITHDRAW: &'static str = "withdraw";
-    const WITHDRAW_UNDELEGATED: &'static str = "withdraw_undelegated";
+    const WITHDRAW_UNDELEGATED_FUNDS: &'static str = "withdraw_undelegated_funds";
 
     pub fn all() -> Vec {
         use OperationType::*;
@@ -146,7 +146,7 @@ impl OperationType {
             InitializeStakePool,
             ResetLockup,
             UnlockStake,
-            WithdrawUndelegated,
+            WithdrawUndelegatedFunds,
             DistributeStakingRewards,
             AddDelegatedStake,
             UnlockDelegatedStake,
@@ -172,7 +172,7 @@ impl FromStr for OperationType {
             Self::DISTRIBUTE_STAKING_REWARDS => Ok(OperationType::DistributeStakingRewards),
             Self::ADD_DELEGATED_STAKE => Ok(OperationType::AddDelegatedStake),
             Self::UNLOCK_DELEGATED_STAKE => Ok(OperationType::UnlockDelegatedStake),
-            Self::WITHDRAW_UNDELEGATED => Ok(OperationType::WithdrawUndelegated),
+            Self::WITHDRAW_UNDELEGATED_FUNDS => Ok(OperationType::WithdrawUndelegatedFunds),
             _ => Err(ApiError::DeserializationFailed(Some(format!(
                 "Invalid OperationType: {}",
                 s
@@ -197,7 +197,7 @@ impl Display for OperationType {
             DistributeStakingRewards => Self::DISTRIBUTE_STAKING_REWARDS,
             AddDelegatedStake => Self::ADD_DELEGATED_STAKE,
             UnlockDelegatedStake => Self::UNLOCK_DELEGATED_STAKE,
-            WithdrawUndelegated => Self::WITHDRAW_UNDELEGATED,
+            WithdrawUndelegatedFunds => Self::WITHDRAW_UNDELEGATED_FUNDS,
             Fee => Self::FEE,
         })
     }
diff --git a/crates/aptos-rosetta/src/types/objects.rs b/crates/aptos-rosetta/src/types/objects.rs
index 072bd17e65744..3b3e3c0447f3a 100644
--- a/crates/aptos-rosetta/src/types/objects.rs
+++ b/crates/aptos-rosetta/src/types/objects.rs
@@ -554,7 +554,7 @@ impl Operation {
         amount: Option,
     ) -> Operation {
         Operation::new(
-            OperationType::WithdrawUndelegated,
+            OperationType::WithdrawUndelegatedFunds,
             operation_index,
             status,
             AccountIdentifier::base_account(owner),
@@ -1914,7 +1914,7 @@ impl InternalOperation {
                                 }));
                             }
                         },
-                        Ok(OperationType::WithdrawUndelegated) => {
+                        Ok(OperationType::WithdrawUndelegatedFunds) => {
                             if let (
                                 Some(OperationMetadata {
                                     pool_address: Some(pool_address),
diff --git a/testsuite/smoke-test/src/rosetta.rs b/testsuite/smoke-test/src/rosetta.rs
index fc151f12dd269..9cf5cf127de0d 100644
--- a/testsuite/smoke-test/src/rosetta.rs
+++ b/testsuite/smoke-test/src/rosetta.rs
@@ -1647,7 +1647,7 @@ async fn parse_operations(
                     panic!("Not a user transaction");
                 }
             },
-            OperationType::WithdrawUndelegated => {
+            OperationType::WithdrawUndelegatedFunds => {
                 if actual_successful {
                     assert_eq!(
                         OperationStatusType::Success,

From 9d5060c7f7915d1d455680502375c6059e70c3c9 Mon Sep 17 00:00:00 2001
From: "Brian R. Murphy" <132495859+brmataptos@users.noreply.github.com>
Date: Sun, 11 Jun 2023 04:59:13 -0700
Subject: [PATCH 137/200] Update generics.md (#8581)

Fix a typo in recursive type example.
---
 developer-docs-site/docs/move/book/generics.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/developer-docs-site/docs/move/book/generics.md b/developer-docs-site/docs/move/book/generics.md
index d7f0d437a5f78..1e5364cd4a3e7 100644
--- a/developer-docs-site/docs/move/book/generics.md
+++ b/developer-docs-site/docs/move/book/generics.md
@@ -435,7 +435,7 @@ module m {
     // error!
     // foo -> foo> -> foo>> -> ...
     fun foo() {
-        foo>();
+        foo>();
     }
 }
 }

From b5f5f522ce76ecbd04f51fda34fb34ec676412a7 Mon Sep 17 00:00:00 2001
From: Zorrot Chen 
Date: Mon, 12 Jun 2023 14:35:19 +0800
Subject: [PATCH 138/200] Spec aptos account (#8364)

* init

* run lint

* delete verfiy and add schema

* pass linter test

* fix lint

* merge aptos main

* run lint

* [python] return int balance of coins

* [python] async sleep for async calls

* [python] use aptos_account::transfer instead of coin::transfer

* [python] expose payload generators for token client

* [python] support inserting sequence numbers in transaction helpers

* [python] add a transaction management layer

This provides a framework for managing as many transactions from a
single account at once
* The AccountSequenceNumber allocates up to 100 outstanding sequence numbers to maximize the number of concurrent transactions in the happy path.
* The transaction manager provides async workers that push a transaction from submission through to validating completion
Together they provide the basic harness for scaling transaction
submission on the Aptos blockchain from a single account.

* [python] Add testing coverage

* [python] cleaning up with feedback

* [docs] update transaction management

* [python] add a modest reliablity layer to transaction management

this handles all the failures associated with network congestion,
meaning this is ready to ship for now... need more testing on other
failure cases.... such as intermittent network connectivity, lost
connections, bad upstreams.

* [python] remove unnecessary python dependencies

* [Execution Benchmark] Calibrate Threshold (#8591)

* clean AptosVmImpl::new() up a bit

* [Helm] Add charts for kube-state-metrics and prometheus-node-exporter (#8576)

* Add a zip functions to iterate over 2 vectors concurrently (#8584)

* [TF] Add health check for waypoint service in GCP testnet-addons

Also, add a default for "gke_maintenance_policy" in the
aptos-node-testnet module.

* [Storage][Sharding][Pruner] Restructure ledger pruner. (#8443)

* use assume to replace require Cointype != Aptos

* fix linter

---------

Co-authored-by: David Wolinsky 
Co-authored-by: danielx <66756900+danielxiangzl@users.noreply.github.com>
Co-authored-by: aldenhu 
Co-authored-by: Stelian Ionescu 
Co-authored-by: Kevin <105028215+movekevin@users.noreply.github.com>
Co-authored-by: Guoteng Rao <3603304+grao1991@users.noreply.github.com>
---
 .../aptos-framework/doc/aptos_account.md      | 163 +++++++++++++++++-
 .../sources/aptos_account.move                |  18 ++
 .../sources/aptos_account.spec.move           | 155 +++++++++++++++--
 3 files changed, 319 insertions(+), 17 deletions(-)

diff --git a/aptos-move/framework/aptos-framework/doc/aptos_account.md b/aptos-move/framework/aptos-framework/doc/aptos_account.md
index 7f9f37670a971..6ee25c8673858 100644
--- a/aptos-move/framework/aptos-framework/doc/aptos_account.md
+++ b/aptos-move/framework/aptos-framework/doc/aptos_account.md
@@ -273,6 +273,12 @@ Batch version of transfer_coins.
 
 
public entry fun batch_transfer_coins<CoinType>(
     from: &signer, recipients: vector<address>, amounts: vector<u64>) acquires DirectTransferConfig {
+    spec {
+    // Cointype should not be aptoscoin, otherwise it will automaticly create an account.
+    // Meanwhile, aptoscoin has already been proved in normal tranfer
+    use aptos_std::type_info;
+    assume type_info::type_of<CoinType>() != type_info::type_of<AptosCoin>();
+    };
     let recipients_len = vector::length(&recipients);
     assert!(
         recipients_len == vector::length(&amounts),
@@ -308,6 +314,12 @@ This would create the recipient account first and register it to receive the Coi
 
 
 
public entry fun transfer_coins<CoinType>(from: &signer, to: address, amount: u64) acquires DirectTransferConfig {
+    spec {
+    // Cointype should not be aptoscoin, otherwise it will automaticly create an account.
+    // Meanwhile, aptoscoin has already been proved in normal tranfer
+    use aptos_std::type_info;
+    assume type_info::type_of<CoinType>() != type_info::type_of<AptosCoin>();
+    };
     deposit_coins(to, coin::withdraw<CoinType>(from, amount));
 }
 

@@ -334,6 +346,12 @@ This would create the recipient account first and register it to receive the Coi
 
 
 
public fun deposit_coins<CoinType>(to: address, coins: Coin<CoinType>) acquires DirectTransferConfig {
+    spec {
+    // Cointype should not be aptoscoin, otherwise it will automaticly create an account.
+    // Meanwhile, aptoscoin has already been proved in normal tranfer
+    use aptos_std::type_info;
+    assume type_info::type_of<CoinType>() != type_info::type_of<AptosCoin>();
+    };
     if (!account::exists_at(to)) {
         create_account(to);
     };
@@ -482,8 +500,7 @@ By default, this returns true if an account has not explicitly set whether the c
 
 
 
-
pragma verify = true;
-pragma aborts_if_is_strict;
+
pragma aborts_if_is_strict;
 

 
 
@@ -548,7 +565,34 @@ Limit the address of auth_key is not @vm_reserved / @aptos_framework / @aptos_to
 
 
 
-
pragma verify=false;
+
pragma verify = false;
+let account_addr_source = signer::address_of(source);
+let coin_store_source = global<coin::CoinStore<AptosCoin>>(account_addr_source);
+let balance_source = coin_store_source.coin.value;
+requires forall i in 0..len(recipients):
+    recipients[i] != account_addr_source;
+requires exists i in 0..len(recipients):
+    amounts[i] > 0;
+aborts_if len(recipients) != len(amounts);
+aborts_if exists i in 0..len(recipients):
+        !account::exists_at(recipients[i]) && length_judgment(recipients[i]);
+aborts_if exists i in 0..len(recipients):
+        !account::exists_at(recipients[i]) && (recipients[i] == @vm_reserved || recipients[i] == @aptos_framework || recipients[i] == @aptos_token);
+ensures forall i in 0..len(recipients):
+        (!account::exists_at(recipients[i]) ==> !length_judgment(recipients[i])) &&
+            (!account::exists_at(recipients[i]) ==> (recipients[i] != @vm_reserved && recipients[i] != @aptos_framework && recipients[i] != @aptos_token));
+aborts_if exists i in 0..len(recipients):
+    !exists<coin::CoinStore<AptosCoin>>(account_addr_source);
+aborts_if exists i in 0..len(recipients):
+    coin_store_source.frozen;
+aborts_if exists i in 0..len(recipients):
+    global<coin::CoinStore<AptosCoin>>(account_addr_source).coin.value < amounts[i];
+aborts_if exists i in 0..len(recipients):
+    exists<coin::CoinStore<AptosCoin>>(recipients[i]) && global<coin::CoinStore<AptosCoin>>(recipients[i]).frozen;
+aborts_if exists i in 0..len(recipients):
+    account::exists_at(recipients[i]) && !exists<coin::CoinStore<AptosCoin>>(recipients[i]) && global<account::Account>(recipients[i]).guid_creation_num + 2 >= account::MAX_GUID_CREATION_NUM;
+aborts_if exists i in 0..len(recipients):
+    account::exists_at(recipients[i]) && !exists<coin::CoinStore<AptosCoin>>(recipients[i]) && global<account::Account>(recipients[i]).guid_creation_num + 2 > MAX_U64;
 

 
 
@@ -564,7 +608,13 @@ Limit the address of auth_key is not @vm_reserved / @aptos_framework / @aptos_to
 
 
 
-
pragma verify = false;
+
let account_addr_source = signer::address_of(source);
+let coin_store_to = global<coin::CoinStore<AptosCoin>>(to);
+requires account_addr_source != to;
+include CreateAccountTransferAbortsIf;
+include GuidAbortsIf<AptosCoin>;
+include WithdrawAbortsIf<AptosCoin>{from: source};
+aborts_if exists<coin::CoinStore<AptosCoin>>(to) && global<coin::CoinStore<AptosCoin>>(to).frozen;
 

 
 
@@ -580,7 +630,38 @@ Limit the address of auth_key is not @vm_reserved / @aptos_framework / @aptos_to
 
 
 
-
pragma verify=false;
+
pragma verify = false;
+let account_addr_source = signer::address_of(from);
+let coin_store_source = global<coin::CoinStore<CoinType>>(account_addr_source);
+let balance_source = coin_store_source.coin.value;
+requires forall i in 0..len(recipients):
+    recipients[i] != account_addr_source;
+requires exists i in 0..len(recipients):
+    amounts[i] > 0;
+aborts_if len(recipients) != len(amounts);
+aborts_if exists i in 0..len(recipients):
+        !account::exists_at(recipients[i]) && length_judgment(recipients[i]);
+aborts_if exists i in 0..len(recipients):
+        !account::exists_at(recipients[i]) && (recipients[i] == @vm_reserved || recipients[i] == @aptos_framework || recipients[i] == @aptos_token);
+ensures forall i in 0..len(recipients):
+        (!account::exists_at(recipients[i]) ==> !length_judgment(recipients[i])) &&
+            (!account::exists_at(recipients[i]) ==> (recipients[i] != @vm_reserved && recipients[i] != @aptos_framework && recipients[i] != @aptos_token));
+aborts_if exists i in 0..len(recipients):
+    !exists<coin::CoinStore<CoinType>>(account_addr_source);
+aborts_if exists i in 0..len(recipients):
+    coin_store_source.frozen;
+aborts_if exists i in 0..len(recipients):
+    global<coin::CoinStore<CoinType>>(account_addr_source).coin.value < amounts[i];
+aborts_if exists i in 0..len(recipients):
+    exists<coin::CoinStore<CoinType>>(recipients[i]) && global<coin::CoinStore<CoinType>>(recipients[i]).frozen;
+aborts_if exists i in 0..len(recipients):
+    account::exists_at(recipients[i]) && !exists<coin::CoinStore<CoinType>>(recipients[i]) && global<account::Account>(recipients[i]).guid_creation_num + 2 >= account::MAX_GUID_CREATION_NUM;
+aborts_if exists i in 0..len(recipients):
+    account::exists_at(recipients[i]) && !exists<coin::CoinStore<CoinType>>(recipients[i]) && global<account::Account>(recipients[i]).guid_creation_num + 2 > MAX_U64;
+aborts_if exists i in 0..len(recipients):
+    !coin::is_account_registered<CoinType>(recipients[i]) && !type_info::spec_is_struct<CoinType>();
+aborts_if exists i in 0..len(recipients):
+    !coin::is_account_registered<CoinType>(recipients[i]) && !can_receive_direct_coin_transfers(recipients[i]);
 

 
 
@@ -596,7 +677,72 @@ Limit the address of auth_key is not @vm_reserved / @aptos_framework / @aptos_to
 
 
 
-
pragma verify=false;
+
let account_addr_source = signer::address_of(from);
+let coin_store_to = global<coin::CoinStore<CoinType>>(to);
+requires account_addr_source != to;
+include CreateAccountTransferAbortsIf;
+include WithdrawAbortsIf<CoinType>;
+include GuidAbortsIf<CoinType>;
+include RegistCoinAbortsIf<CoinType>;
+aborts_if exists<coin::CoinStore<CoinType>>(to) && global<coin::CoinStore<CoinType>>(to).frozen;
+

+
+
+
+
+
+
+
+
schema CreateAccountTransferAbortsIf {
+    to: address;
+    aborts_if !account::exists_at(to) && length_judgment(to);
+    aborts_if !account::exists_at(to) && (to == @vm_reserved || to == @aptos_framework || to == @aptos_token);
+}
+

+
+
+
+
+
+
+
+
schema WithdrawAbortsIf<CoinType> {
+    from: &signer;
+    amount: u64;
+    let account_addr_source = signer::address_of(from);
+    let coin_store_source = global<coin::CoinStore<CoinType>>(account_addr_source);
+    let balance_source = coin_store_source.coin.value;
+    aborts_if !exists<coin::CoinStore<CoinType>>(account_addr_source);
+    aborts_if coin_store_source.frozen;
+    aborts_if balance_source < amount;
+}
+

+
+
+
+
+
+
+
+
schema GuidAbortsIf<CoinType> {
+    to: address;
+    let acc = global<account::Account>(to);
+    aborts_if account::exists_at(to) && !exists<coin::CoinStore<CoinType>>(to) && acc.guid_creation_num + 2 >= account::MAX_GUID_CREATION_NUM;
+    aborts_if account::exists_at(to) && !exists<coin::CoinStore<CoinType>>(to) && acc.guid_creation_num + 2 > MAX_U64;
+}
+

+
+
+
+
+
+
+
+
schema RegistCoinAbortsIf<CoinType> {
+    to: address;
+    aborts_if !coin::is_account_registered<CoinType>(to) && !type_info::spec_is_struct<CoinType>();
+    aborts_if !coin::is_account_registered<CoinType>(to) && !can_receive_direct_coin_transfers(to);
+}
 

 
 
@@ -612,7 +758,10 @@ Limit the address of auth_key is not @vm_reserved / @aptos_framework / @aptos_to
 
 
 
-
pragma verify=false;
+
include CreateAccountTransferAbortsIf;
+include GuidAbortsIf<CoinType>;
+include RegistCoinAbortsIf<CoinType>;
+aborts_if exists<coin::CoinStore<CoinType>>(to) && global<coin::CoinStore<CoinType>>(to).frozen;
 

 
 
diff --git a/aptos-move/framework/aptos-framework/sources/aptos_account.move b/aptos-move/framework/aptos-framework/sources/aptos_account.move
index ff9074ebc8a2f..9eeb66bdab2e8 100644
--- a/aptos-move/framework/aptos-framework/sources/aptos_account.move
+++ b/aptos-move/framework/aptos-framework/sources/aptos_account.move
@@ -75,6 +75,12 @@ module aptos_framework::aptos_account {
     /// Batch version of transfer_coins.
     public entry fun batch_transfer_coins(
         from: &signer, recipients: vector
, amounts: vector) acquires DirectTransferConfig {
+        spec {
+        // Cointype should not be aptoscoin, otherwise it will automaticly create an account.
+        // Meanwhile, aptoscoin has already been proved in normal tranfer
+        use aptos_std::type_info;
+        assume type_info::type_of() != type_info::type_of();
+        };
         let recipients_len = vector::length(&recipients);
         assert!(
             recipients_len == vector::length(&amounts),
@@ -90,12 +96,24 @@ module aptos_framework::aptos_account {
     /// Convenient function to transfer a custom CoinType to a recipient account that might not exist.
     /// This would create the recipient account first and register it to receive the CoinType, before transferring.
     public entry fun transfer_coins(from: &signer, to: address, amount: u64) acquires DirectTransferConfig {
+        spec {
+        // Cointype should not be aptoscoin, otherwise it will automaticly create an account.
+        // Meanwhile, aptoscoin has already been proved in normal tranfer
+        use aptos_std::type_info;
+        assume type_info::type_of() != type_info::type_of();
+        };
         deposit_coins(to, coin::withdraw(from, amount));
     }
 
     /// Convenient function to deposit a custom CoinType into a recipient account that might not exist.
     /// This would create the recipient account first and register it to receive the CoinType, before transferring.
     public fun deposit_coins(to: address, coins: Coin) acquires DirectTransferConfig {
+        spec {
+        // Cointype should not be aptoscoin, otherwise it will automaticly create an account.
+        // Meanwhile, aptoscoin has already been proved in normal tranfer
+        use aptos_std::type_info;
+        assume type_info::type_of() != type_info::type_of();
+        };
         if (!account::exists_at(to)) {
             create_account(to);
         };
diff --git a/aptos-move/framework/aptos-framework/sources/aptos_account.spec.move b/aptos-move/framework/aptos-framework/sources/aptos_account.spec.move
index 5008f857210f9..d1a4e18cee1b8 100644
--- a/aptos-move/framework/aptos-framework/sources/aptos_account.spec.move
+++ b/aptos-move/framework/aptos-framework/sources/aptos_account.spec.move
@@ -1,6 +1,5 @@
 spec aptos_framework::aptos_account {
     spec module {
-        pragma verify = true;
         pragma aborts_if_is_strict;
     }
 
@@ -27,7 +26,17 @@ spec aptos_framework::aptos_account {
     }
 
     spec transfer(source: &signer, to: address, amount: u64) {
-        pragma verify = false;
+        let account_addr_source = signer::address_of(source);
+        let coin_store_to = global>(to);
+
+        // The 'from' addr is implictly not equal to 'to' addr
+        requires account_addr_source != to;
+
+        include CreateAccountTransferAbortsIf;
+        include GuidAbortsIf;
+        include WithdrawAbortsIf{from: source};
+
+        aborts_if exists>(to) && global>(to).frozen;
     }
 
     spec assert_account_exists(addr: address) {
@@ -47,8 +56,44 @@ spec aptos_framework::aptos_account {
     }
 
     spec batch_transfer(source: &signer, recipients: vector
, amounts: vector) {
-        // TODO: missing aborts_if spec
-        pragma verify=false;
+        //TODO: Can't verify the loop invariant in enumerate
+        pragma verify = false;
+        let account_addr_source = signer::address_of(source);
+        let coin_store_source = global>(account_addr_source);
+        let balance_source = coin_store_source.coin.value;
+
+        requires forall i in 0..len(recipients):
+            recipients[i] != account_addr_source;
+        requires exists i in 0..len(recipients):
+            amounts[i] > 0;
+
+        // create account properties
+        aborts_if len(recipients) != len(amounts);
+        aborts_if exists i in 0..len(recipients):
+                !account::exists_at(recipients[i]) && length_judgment(recipients[i]);
+        aborts_if exists i in 0..len(recipients):
+                !account::exists_at(recipients[i]) && (recipients[i] == @vm_reserved || recipients[i] == @aptos_framework || recipients[i] == @aptos_token);
+        ensures forall i in 0..len(recipients):
+                (!account::exists_at(recipients[i]) ==> !length_judgment(recipients[i])) &&
+                    (!account::exists_at(recipients[i]) ==> (recipients[i] != @vm_reserved && recipients[i] != @aptos_framework && recipients[i] != @aptos_token));
+
+        // coin::withdraw properties
+        aborts_if exists i in 0..len(recipients):
+            !exists>(account_addr_source);
+        aborts_if exists i in 0..len(recipients):
+            coin_store_source.frozen;
+        aborts_if exists i in 0..len(recipients):
+            global>(account_addr_source).coin.value < amounts[i];
+
+        // deposit properties
+        aborts_if exists i in 0..len(recipients):
+            exists>(recipients[i]) && global>(recipients[i]).frozen;
+
+        // guid properties
+        aborts_if exists i in 0..len(recipients):
+            account::exists_at(recipients[i]) && !exists>(recipients[i]) && global(recipients[i]).guid_creation_num + 2 >= account::MAX_GUID_CREATION_NUM;
+        aborts_if exists i in 0..len(recipients):
+            account::exists_at(recipients[i]) && !exists>(recipients[i]) && global(recipients[i]).guid_creation_num + 2 > MAX_U64;
     }
 
     spec can_receive_direct_coin_transfers(account: address): bool {
@@ -60,17 +105,107 @@ spec aptos_framework::aptos_account {
     }
 
     spec batch_transfer_coins(from: &signer, recipients: vector
, amounts: vector) {
-        // TODO: missing aborts_if spec
-        pragma verify=false;
+        //TODO: Can't verify the loop invariant in enumerate
+        use aptos_std::type_info;
+        pragma verify = false;
+        let account_addr_source = signer::address_of(from);
+        let coin_store_source = global>(account_addr_source);
+        let balance_source = coin_store_source.coin.value;
+
+        requires forall i in 0..len(recipients):
+            recipients[i] != account_addr_source;
+
+        requires exists i in 0..len(recipients):
+            amounts[i] > 0;
+
+        aborts_if len(recipients) != len(amounts);
+
+        //create account properties
+        aborts_if exists i in 0..len(recipients):
+                !account::exists_at(recipients[i]) && length_judgment(recipients[i]);
+        aborts_if exists i in 0..len(recipients):
+                !account::exists_at(recipients[i]) && (recipients[i] == @vm_reserved || recipients[i] == @aptos_framework || recipients[i] == @aptos_token);
+        ensures forall i in 0..len(recipients):
+                (!account::exists_at(recipients[i]) ==> !length_judgment(recipients[i])) &&
+                    (!account::exists_at(recipients[i]) ==> (recipients[i] != @vm_reserved && recipients[i] != @aptos_framework && recipients[i] != @aptos_token));
+
+        // coin::withdraw properties
+        aborts_if exists i in 0..len(recipients):
+            !exists>(account_addr_source);
+        aborts_if exists i in 0..len(recipients):
+            coin_store_source.frozen;
+        aborts_if exists i in 0..len(recipients):
+            global>(account_addr_source).coin.value < amounts[i];
+
+        // deposit properties
+        aborts_if exists i in 0..len(recipients):
+            exists>(recipients[i]) && global>(recipients[i]).frozen;
+
+        // guid properties
+        aborts_if exists i in 0..len(recipients):
+            account::exists_at(recipients[i]) && !exists>(recipients[i]) && global(recipients[i]).guid_creation_num + 2 >= account::MAX_GUID_CREATION_NUM;
+        aborts_if exists i in 0..len(recipients):
+            account::exists_at(recipients[i]) && !exists>(recipients[i]) && global(recipients[i]).guid_creation_num + 2 > MAX_U64;
+
+        // register_coin properties
+        aborts_if exists i in 0..len(recipients):
+            !coin::is_account_registered(recipients[i]) && !type_info::spec_is_struct();
+        aborts_if exists i in 0..len(recipients):
+            !coin::is_account_registered(recipients[i]) && !can_receive_direct_coin_transfers(recipients[i]);
+
     }
 
     spec deposit_coins(to: address, coins: Coin) {
-        // TODO: missing aborts_if spec
-        pragma verify=false;
+        include CreateAccountTransferAbortsIf;
+        include GuidAbortsIf;
+        include RegistCoinAbortsIf;
+
+        aborts_if exists>(to) && global>(to).frozen;
     }
 
     spec transfer_coins(from: &signer, to: address, amount: u64) {
-        // TODO: missing aborts_if spec
-        pragma verify=false;
+        let account_addr_source = signer::address_of(from);
+        let coin_store_to = global>(to);
+
+        //The 'from' addr is implictly not equal to 'to' addr
+        requires account_addr_source != to;
+
+        include CreateAccountTransferAbortsIf;
+        include WithdrawAbortsIf;
+        include GuidAbortsIf;
+        include RegistCoinAbortsIf;
+
+        aborts_if exists>(to) && global>(to).frozen;
+    }
+
+    spec schema CreateAccountTransferAbortsIf {
+        to: address;
+        aborts_if !account::exists_at(to) && length_judgment(to);
+        aborts_if !account::exists_at(to) && (to == @vm_reserved || to == @aptos_framework || to == @aptos_token);
+    }
+
+    spec schema WithdrawAbortsIf {
+        from: &signer;
+        amount: u64;
+        let account_addr_source = signer::address_of(from);
+        let coin_store_source = global>(account_addr_source);
+        let balance_source = coin_store_source.coin.value;
+        aborts_if !exists>(account_addr_source);
+        aborts_if coin_store_source.frozen;
+        aborts_if balance_source < amount;
+    }
+
+    spec schema GuidAbortsIf {
+        to: address;
+        let acc = global(to);
+        aborts_if account::exists_at(to) && !exists>(to) && acc.guid_creation_num + 2 >= account::MAX_GUID_CREATION_NUM;
+        aborts_if account::exists_at(to) && !exists>(to) && acc.guid_creation_num + 2 > MAX_U64;
+    }
+
+    spec schema RegistCoinAbortsIf {
+        use aptos_std::type_info;
+        to: address;
+        aborts_if !coin::is_account_registered(to) && !type_info::spec_is_struct();
+        aborts_if !coin::is_account_registered(to) && !can_receive_direct_coin_transfers(to);
     }
 }

From f8b4b52448b7618acceb2035c658e877664b29ce Mon Sep 17 00:00:00 2001
From: Perry Randall 
Date: Fri, 9 Jun 2023 17:05:11 -0700
Subject: [PATCH 139/200] [forge] Fix long running job failure

Since the migration to GCP long duration forge jobs have been failing.

I looked at this with Rustie and initially we were stumped.

The code that determines the success is based on fetching the phase of the pod that is running the job, if the phase == "succeeded" then pass skip etc or anything else fail.

When looking at the debugging output (which had auth failure) I realized that the status check could possibly have auth failure as well.

This lead me to the auth duration, which is default to 1.5hr previously in aws forge we had a longer expiration by default!

So this PR addresses this by setting the auth expiration to double the runner duration.

I also add a little error handling in case someone hits this again

Test Plan: unittest + run the test on this branch
---
 .github/actions/docker-setup/action.yaml      |  8 +++++-
 .github/workflows/workflow-run-forge.yaml     |  1 +
 .../testPossibleAuthFailureMessage.fixture    |  4 +++
 testsuite/forge.py                            | 17 +++++++++---
 testsuite/forge_test.py                       | 26 ++++++++++++++++---
 5 files changed, 49 insertions(+), 7 deletions(-)
 create mode 100644 testsuite/fixtures/testPossibleAuthFailureMessage.fixture

diff --git a/.github/actions/docker-setup/action.yaml b/.github/actions/docker-setup/action.yaml
index 6d071cb426e10..9e40faee3a83f 100644
--- a/.github/actions/docker-setup/action.yaml
+++ b/.github/actions/docker-setup/action.yaml
@@ -30,6 +30,12 @@ inputs:
   GIT_CREDENTIALS:
     description: "Optional credentials to pass to git. Useful if you need to pull private repos for dependencies"
     required: false
+  GCP_AUTH_DURATION:
+    description: "Duration of GCP auth token in seconds"
+    type: int
+    # setting this to 1.5h since sometimes docker builds (special performance
+    # builds etc.) take that long. Default is 1h.
+    default: 5400
 outputs:
   CLOUDSDK_AUTH_ACCESS_TOKEN:
     description: "GCP access token"
@@ -70,7 +76,7 @@ runs:
       with:
         create_credentials_file: false
         token_format: "access_token"
-        access_token_lifetime: 5400 # setting this to 1.5h since sometimes docker builds (special performance builds etc.) take that long. Default is 1h.
+        access_token_lifetime: ${{ inputs.GCP_AUTH_DURATION }}
         workload_identity_provider: ${{ inputs.GCP_WORKLOAD_IDENTITY_PROVIDER }}
         service_account: ${{ inputs.GCP_SERVICE_ACCOUNT_EMAIL }}
         export_environment_variables: ${{ inputs.EXPORT_GCP_PROJECT_VARIABLES }}
diff --git a/.github/workflows/workflow-run-forge.yaml b/.github/workflows/workflow-run-forge.yaml
index 2e99d7a6aa0ed..cda57ee825da9 100644
--- a/.github/workflows/workflow-run-forge.yaml
+++ b/.github/workflows/workflow-run-forge.yaml
@@ -128,6 +128,7 @@ jobs:
           AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
           AWS_DOCKER_ARTIFACT_REPO: ${{ secrets.AWS_DOCKER_ARTIFACT_REPO }}
           GIT_CREDENTIALS: ${{ secrets.GIT_CREDENTIALS }}
+          GCP_AUTH_DURATION: ${{ inputs.FORGE_RUNNER_DURATION_SECS * 2 }}
 
       - name: "Install GCloud SDK"
         uses: "google-github-actions/setup-gcloud@62d4898025f6041e16b1068643bfc5a696863587" # pin@v1
diff --git a/testsuite/fixtures/testPossibleAuthFailureMessage.fixture b/testsuite/fixtures/testPossibleAuthFailureMessage.fixture
new file mode 100644
index 0000000000000..959e0721308a1
--- /dev/null
+++ b/testsuite/fixtures/testPossibleAuthFailureMessage.fixture
@@ -0,0 +1,4 @@
+
+Forge output: 
+Forge failed
+Forge took longer than 1 hour to run. This can cause the job to fail even when the test is successful because of gcp + github auth expiration. If you think this is the case please check the GCP_AUTH_DURATION in the github workflow.
\ No newline at end of file
diff --git a/testsuite/forge.py b/testsuite/forge.py
index 0fd7f96fa66ff..ab2f91f3d6c83 100644
--- a/testsuite/forge.py
+++ b/testsuite/forge.py
@@ -151,15 +151,19 @@ def end_time(self) -> datetime:
         assert self._end_time is not None, "end_time is not set"
         return self._end_time
 
+    @property
+    def duration(self) -> float:
+        return (self.end_time - self.start_time).total_seconds()
+
     @classmethod
-    def from_args(cls, state: ForgeState, output: str) -> "ForgeResult":
+    def from_args(cls, state: ForgeState, output: str) -> ForgeResult:
         result = cls()
         result.state = state
         result.output = output
         return result
 
     @classmethod
-    def empty(cls) -> "ForgeResult":
+    def empty(cls) -> ForgeResult:
         return cls.from_args(ForgeState.EMPTY, "")
 
     @classmethod
@@ -207,7 +211,7 @@ def set_debugging_output(self, output: str) -> None:
         self.debugging_output = output
 
     def format(self, context: ForgeContext) -> str:
-        output_lines = []
+        output_lines: List[str] = []
         if not self.succeeded():
             output_lines.append(self.debugging_output)
         output_lines.extend(
@@ -216,6 +220,13 @@ def format(self, context: ForgeContext) -> str:
                 f"Forge {self.state.value.lower()}ed",
             ]
         )
+        if self.state == ForgeState.FAIL and self.duration > 3600:
+            output_lines.append(
+                "Forge took longer than 1 hour to run. This can cause the job to"
+                " fail even when the test is successful because of gcp + github"
+                " auth expiration. If you think this is the case please check the"
+                " GCP_AUTH_DURATION in the github workflow."
+            )
         return "\n".join(output_lines)
 
     def succeeded(self) -> bool:
diff --git a/testsuite/forge_test.py b/testsuite/forge_test.py
index b5b3510b15de2..ef40e797312ab 100644
--- a/testsuite/forge_test.py
+++ b/testsuite/forge_test.py
@@ -3,7 +3,7 @@
 import os
 import unittest
 import tempfile
-from datetime import datetime, timezone
+from datetime import datetime, timezone, timedelta
 from pathlib import Path
 from typing import (
     Any,
@@ -78,18 +78,28 @@ class AssertFixtureMixin:
     def assertFixture(
         self: HasAssertMultiLineEqual, test_str: str, fixture_name: str
     ) -> None:
+        fixture = None
         fixture_path = get_fixture_path(fixture_name)
         if os.getenv("FORGE_WRITE_FIXTURES") == "true":
             print(f"Writing fixture to {str(fixture_path)}")
             fixture_path.write_text(test_str)
             fixture = test_str
         else:
-            fixture = fixture_path.read_text()
+            try:
+                fixture = fixture_path.read_text()
+            except FileNotFoundError as e:
+                raise Exception(
+                    f"Fixture {fixture_path} is missing.\nRun with FORGE_WRITE_FIXTURES=true to update the fixtures"
+                ) from e
+            except Exception as e:
+                raise Exception(
+                    f"Failed while reading fixture:\n{e}\nRun with FORGE_WRITE_FIXTURES=true to update the fixtures"
+                ) from e
         temp = Path(tempfile.mkstemp()[1])
         temp.write_text(test_str)
         self.assertMultiLineEqual(
             test_str,
-            fixture,
+            fixture or "",
             f"Fixture {fixture_name} does not match"
             "\n"
             f"Wrote to {str(temp)} for comparison"
@@ -522,6 +532,16 @@ def testSanitizeForgeNamespaceTooLong(self) -> None:
             "forge-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
         )
 
+    def testPossibleAuthFailureMessage(self) -> None:
+        result = ForgeResult.empty()
+        context = fake_context()
+        now = context.time.now()
+        result._start_time = now - timedelta(seconds=4800)
+        result._end_time = now
+        result.state = ForgeState.FAIL
+        output = result.format(context)
+        self.assertFixture(output, "testPossibleAuthFailureMessage.fixture")
+
 
 class ForgeMainTests(unittest.TestCase, AssertFixtureMixin):
     maxDiff = None

From 402489d7db3ed29696563c91fde8748b68207463 Mon Sep 17 00:00:00 2001
From: perryjrandall 
Date: Mon, 12 Jun 2023 11:25:05 -0700
Subject: [PATCH 140/200] Revert "[forge] Fix long running job failure" (#8625)

This reverts commit f8b4b52448b7618acceb2035c658e877664b29ce.
---
 .github/actions/docker-setup/action.yaml      |  8 +-----
 .github/workflows/workflow-run-forge.yaml     |  1 -
 .../testPossibleAuthFailureMessage.fixture    |  4 ---
 testsuite/forge.py                            | 17 +++---------
 testsuite/forge_test.py                       | 26 +++----------------
 5 files changed, 7 insertions(+), 49 deletions(-)
 delete mode 100644 testsuite/fixtures/testPossibleAuthFailureMessage.fixture

diff --git a/.github/actions/docker-setup/action.yaml b/.github/actions/docker-setup/action.yaml
index 9e40faee3a83f..6d071cb426e10 100644
--- a/.github/actions/docker-setup/action.yaml
+++ b/.github/actions/docker-setup/action.yaml
@@ -30,12 +30,6 @@ inputs:
   GIT_CREDENTIALS:
     description: "Optional credentials to pass to git. Useful if you need to pull private repos for dependencies"
     required: false
-  GCP_AUTH_DURATION:
-    description: "Duration of GCP auth token in seconds"
-    type: int
-    # setting this to 1.5h since sometimes docker builds (special performance
-    # builds etc.) take that long. Default is 1h.
-    default: 5400
 outputs:
   CLOUDSDK_AUTH_ACCESS_TOKEN:
     description: "GCP access token"
@@ -76,7 +70,7 @@ runs:
       with:
         create_credentials_file: false
         token_format: "access_token"
-        access_token_lifetime: ${{ inputs.GCP_AUTH_DURATION }}
+        access_token_lifetime: 5400 # setting this to 1.5h since sometimes docker builds (special performance builds etc.) take that long. Default is 1h.
         workload_identity_provider: ${{ inputs.GCP_WORKLOAD_IDENTITY_PROVIDER }}
         service_account: ${{ inputs.GCP_SERVICE_ACCOUNT_EMAIL }}
         export_environment_variables: ${{ inputs.EXPORT_GCP_PROJECT_VARIABLES }}
diff --git a/.github/workflows/workflow-run-forge.yaml b/.github/workflows/workflow-run-forge.yaml
index cda57ee825da9..2e99d7a6aa0ed 100644
--- a/.github/workflows/workflow-run-forge.yaml
+++ b/.github/workflows/workflow-run-forge.yaml
@@ -128,7 +128,6 @@ jobs:
           AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
           AWS_DOCKER_ARTIFACT_REPO: ${{ secrets.AWS_DOCKER_ARTIFACT_REPO }}
           GIT_CREDENTIALS: ${{ secrets.GIT_CREDENTIALS }}
-          GCP_AUTH_DURATION: ${{ inputs.FORGE_RUNNER_DURATION_SECS * 2 }}
 
       - name: "Install GCloud SDK"
         uses: "google-github-actions/setup-gcloud@62d4898025f6041e16b1068643bfc5a696863587" # pin@v1
diff --git a/testsuite/fixtures/testPossibleAuthFailureMessage.fixture b/testsuite/fixtures/testPossibleAuthFailureMessage.fixture
deleted file mode 100644
index 959e0721308a1..0000000000000
--- a/testsuite/fixtures/testPossibleAuthFailureMessage.fixture
+++ /dev/null
@@ -1,4 +0,0 @@
-
-Forge output: 
-Forge failed
-Forge took longer than 1 hour to run. This can cause the job to fail even when the test is successful because of gcp + github auth expiration. If you think this is the case please check the GCP_AUTH_DURATION in the github workflow.
\ No newline at end of file
diff --git a/testsuite/forge.py b/testsuite/forge.py
index ab2f91f3d6c83..0fd7f96fa66ff 100644
--- a/testsuite/forge.py
+++ b/testsuite/forge.py
@@ -151,19 +151,15 @@ def end_time(self) -> datetime:
         assert self._end_time is not None, "end_time is not set"
         return self._end_time
 
-    @property
-    def duration(self) -> float:
-        return (self.end_time - self.start_time).total_seconds()
-
     @classmethod
-    def from_args(cls, state: ForgeState, output: str) -> ForgeResult:
+    def from_args(cls, state: ForgeState, output: str) -> "ForgeResult":
         result = cls()
         result.state = state
         result.output = output
         return result
 
     @classmethod
-    def empty(cls) -> ForgeResult:
+    def empty(cls) -> "ForgeResult":
         return cls.from_args(ForgeState.EMPTY, "")
 
     @classmethod
@@ -211,7 +207,7 @@ def set_debugging_output(self, output: str) -> None:
         self.debugging_output = output
 
     def format(self, context: ForgeContext) -> str:
-        output_lines: List[str] = []
+        output_lines = []
         if not self.succeeded():
             output_lines.append(self.debugging_output)
         output_lines.extend(
@@ -220,13 +216,6 @@ def format(self, context: ForgeContext) -> str:
                 f"Forge {self.state.value.lower()}ed",
             ]
         )
-        if self.state == ForgeState.FAIL and self.duration > 3600:
-            output_lines.append(
-                "Forge took longer than 1 hour to run. This can cause the job to"
-                " fail even when the test is successful because of gcp + github"
-                " auth expiration. If you think this is the case please check the"
-                " GCP_AUTH_DURATION in the github workflow."
-            )
         return "\n".join(output_lines)
 
     def succeeded(self) -> bool:
diff --git a/testsuite/forge_test.py b/testsuite/forge_test.py
index ef40e797312ab..b5b3510b15de2 100644
--- a/testsuite/forge_test.py
+++ b/testsuite/forge_test.py
@@ -3,7 +3,7 @@
 import os
 import unittest
 import tempfile
-from datetime import datetime, timezone, timedelta
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import (
     Any,
@@ -78,28 +78,18 @@ class AssertFixtureMixin:
     def assertFixture(
         self: HasAssertMultiLineEqual, test_str: str, fixture_name: str
     ) -> None:
-        fixture = None
         fixture_path = get_fixture_path(fixture_name)
         if os.getenv("FORGE_WRITE_FIXTURES") == "true":
             print(f"Writing fixture to {str(fixture_path)}")
             fixture_path.write_text(test_str)
             fixture = test_str
         else:
-            try:
-                fixture = fixture_path.read_text()
-            except FileNotFoundError as e:
-                raise Exception(
-                    f"Fixture {fixture_path} is missing.\nRun with FORGE_WRITE_FIXTURES=true to update the fixtures"
-                ) from e
-            except Exception as e:
-                raise Exception(
-                    f"Failed while reading fixture:\n{e}\nRun with FORGE_WRITE_FIXTURES=true to update the fixtures"
-                ) from e
+            fixture = fixture_path.read_text()
         temp = Path(tempfile.mkstemp()[1])
         temp.write_text(test_str)
         self.assertMultiLineEqual(
             test_str,
-            fixture or "",
+            fixture,
             f"Fixture {fixture_name} does not match"
             "\n"
             f"Wrote to {str(temp)} for comparison"
@@ -532,16 +522,6 @@ def testSanitizeForgeNamespaceTooLong(self) -> None:
             "forge-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
         )
 
-    def testPossibleAuthFailureMessage(self) -> None:
-        result = ForgeResult.empty()
-        context = fake_context()
-        now = context.time.now()
-        result._start_time = now - timedelta(seconds=4800)
-        result._end_time = now
-        result.state = ForgeState.FAIL
-        output = result.format(context)
-        self.assertFixture(output, "testPossibleAuthFailureMessage.fixture")
-
 
 class ForgeMainTests(unittest.TestCase, AssertFixtureMixin):
     maxDiff = None

From 754df7d9ae94f1138577b5f5038dbfbb92e33209 Mon Sep 17 00:00:00 2001
From: Stelian Ionescu 
Date: Mon, 12 Jun 2023 15:52:58 -0400
Subject: [PATCH 141/200] [GHA] Increase the polling interval of
 merge_gatekeeper to 1 minute

---
 .github/workflows/merge-gatekeeper.yaml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/merge-gatekeeper.yaml b/.github/workflows/merge-gatekeeper.yaml
index 1a6fd7b3edddd..cc204842d6918 100644
--- a/.github/workflows/merge-gatekeeper.yaml
+++ b/.github/workflows/merge-gatekeeper.yaml
@@ -31,4 +31,5 @@ jobs:
         uses: upsidr/merge-gatekeeper@09af7a82c1666d0e64d2bd8c01797a0bcfd3bb5d # pin v1.2.1
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
+          interval: 60 # 1 minute
           timeout: 5400 # 1.5 hour

From d004c76e8aa94d93ed09aa2d7f732ea9d986fe19 Mon Sep 17 00:00:00 2001
From: Rustie Lin 
Date: Mon, 12 Jun 2023 13:32:43 -0700
Subject: [PATCH 142/200] [gha] fix merge gatekeeper with checkout (#8629)

---
 .github/workflows/merge-gatekeeper.yaml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/merge-gatekeeper.yaml b/.github/workflows/merge-gatekeeper.yaml
index cc204842d6918..145392174f201 100644
--- a/.github/workflows/merge-gatekeeper.yaml
+++ b/.github/workflows/merge-gatekeeper.yaml
@@ -16,6 +16,7 @@ jobs:
       checks: read
       statuses: read
     steps:
+      - uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 # pin@v3
       - name: Beta allowlist for certain actors
         shell: bash
         run: |

From 34dfe47c5df14ed962380016b5fb85e6e1bb89b9 Mon Sep 17 00:00:00 2001
From: Stelian Ionescu 
Date: Fri, 9 Jun 2023 15:41:28 -0400
Subject: [PATCH 143/200] [Helm] Update Calico version

Update 3.23.3 -> 3.26.0.
---
 terraform/aptos-node/aws/kubernetes.tf | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/terraform/aptos-node/aws/kubernetes.tf b/terraform/aptos-node/aws/kubernetes.tf
index 4884f63c91af5..92b8219c48c7c 100644
--- a/terraform/aptos-node/aws/kubernetes.tf
+++ b/terraform/aptos-node/aws/kubernetes.tf
@@ -83,9 +83,9 @@ resource "kubernetes_namespace" "tigera-operator" {
 resource "helm_release" "calico" {
   count      = var.enable_calico ? 1 : 0
   name       = "calico"
-  repository = "https://docs.projectcalico.org/charts"
+  repository = "https://docs.tigera.io/calico/charts"
   chart      = "tigera-operator"
-  version    = "3.23.3"
+  version    = "3.26.0"
   namespace  = "tigera-operator"
 }
 

From 74f8eecc94a3807113841a0d3d2cb5bfde65195a Mon Sep 17 00:00:00 2001
From: Stelian Ionescu 
Date: Fri, 9 Jun 2023 17:12:27 -0400
Subject: [PATCH 144/200] [TF] Add variable for enabling loadtesting on GCP
 testnets

---
 terraform/aptos-node-testnet/gcp/addons.tf    | 1 +
 terraform/aptos-node-testnet/gcp/variables.tf | 6 ++++++
 2 files changed, 7 insertions(+)

diff --git a/terraform/aptos-node-testnet/gcp/addons.tf b/terraform/aptos-node-testnet/gcp/addons.tf
index 372a88e3c4ebd..01dee100f4b5e 100644
--- a/terraform/aptos-node-testnet/gcp/addons.tf
+++ b/terraform/aptos-node-testnet/gcp/addons.tf
@@ -162,6 +162,7 @@ resource "helm_release" "testnet-addons" {
         }
       }
     }),
+    jsonencode(var.testnet_addons_helm_values)
   ]
   dynamic "set" {
     for_each = var.manage_via_tf ? toset([""]) : toset([])
diff --git a/terraform/aptos-node-testnet/gcp/variables.tf b/terraform/aptos-node-testnet/gcp/variables.tf
index 2f95addf051a7..f76ea1231f4c5 100644
--- a/terraform/aptos-node-testnet/gcp/variables.tf
+++ b/terraform/aptos-node-testnet/gcp/variables.tf
@@ -168,6 +168,12 @@ variable "enable_prometheus_node_exporter" {
   default     = false
 }
 
+variable "testnet_addons_helm_values" {
+  description = "Map of values to pass to testnet-addons helm chart"
+  type        = any
+  default     = {}
+}
+
 ### Autoscaling
 
 variable "gke_enable_node_autoprovisioning" {

From f336b59a5263ffc8ab4c31a1795fe9435c1c3ed7 Mon Sep 17 00:00:00 2001
From: "cryptomolot.apt" <88001005+cryptomolot@users.noreply.github.com>
Date: Tue, 13 Jun 2023 11:15:21 +0300
Subject: [PATCH 145/200] Update external-resources.md (#8538)

* Update external-resources.md

Added my tutorials on monitoring, alerts, and joining a validator set.

Thanks!

* Update external-resources.md

---------

Co-authored-by: Christian Sahar <125399153+saharct@users.noreply.github.com>
---
 developer-docs-site/docs/community/external-resources.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/developer-docs-site/docs/community/external-resources.md b/developer-docs-site/docs/community/external-resources.md
index cab2dbe1cbb2c..98b33008b8e43 100644
--- a/developer-docs-site/docs/community/external-resources.md
+++ b/developer-docs-site/docs/community/external-resources.md
@@ -26,6 +26,10 @@ To add your own resource, click **Edit this page** at the bottom, add your resou
 
 | Contribution | Description | Author | Date added/updated |
 | --- | --- | --- | --- |
+| [Alerts integration on your validator/full node](https://forum.aptoslabs.com/t/alerts-integration-on-your-validator-full-node/196210) | Explains how to integrate alerts on your validator (fullnode). | [cryptomolot](https://forum.aptoslabs.com/u/unlimitedmolot) | 2023-06-11 |
+| [Tools to monitor your validator](https://forum.aptoslabs.com/t/tools-to-monitore-your-validator/197163) | Explains what tools to use to monitor your validator (fullnode). | [cryptomolot](https://forum.aptoslabs.com/u/unlimitedmolot) and [p1xel32](https://forum.aptoslabs.com/u/p1xel32) | 2023-06-11 |
+| [How to join validator set via snapshot](https://forum.aptoslabs.com/t/how-to-join-validator-set-via-snapshot/207568) | Demonstrates a method to join a validator set with a snapshot. | [cryptomolot](https://forum.aptoslabs.com/u/unlimitedmolot) | 2023-06-11 |
+| [Alerts for your validator via Telegram public](https://forum.aptoslabs.com/t/alerts-for-your-validator-via-telegram-public/201959) | Demonstrates a useful method for receiving alerts. | [cryptomolot](https://forum.aptoslabs.com/u/unlimitedmolot) | 2023-06-11 |
 | [Ansible playbook for Node Management (Bare Metal)](https://github.com/RhinoStake/ansible-aptos) | This Ansible Playbook is for the initialization, configuration, planned and hotfix upgrades of Aptos Validators, VFNs and PFNs on bare metal servers. | [RHINO](https://rhinostake.com) | 2023-03-14 |
 | [Ansible playbook for Node Management (Docker)](https://github.com/LavenderFive/aptos-ansible) | This Ansible Playbook is intended for node management, including initial launch and handling upgrades of nodes. | [Lavender.Five Nodes](https://github.com/LavenderFive) | 2023-03-13 |
 | [Write Your First Smart Contract On Aptos](https://medium.com/mokshyaprotocol/write-your-first-smart-contract-on-aptos-a-step-by-step-guide-e16a6f5c2be6) | This blog is created to help you start writing smart contracts in Aptos Blockchain. | [Samundra Karki](https://medium.com/@samundrakarki56), [MokshyaProtocol](https://mokshya.io/) | 2023-02-27 |

From 3b05c8fad8157584f39bf137827f7a64eb8a577b Mon Sep 17 00:00:00 2001
From: Sital Kedia 
Date: Tue, 13 Jun 2023 10:06:52 -0700
Subject: [PATCH 146/200]  [Sharding][Partitioning] Add support for dependent
 edges and conflicting storage location info (#8608)

---
 .../conflict_detector.rs                      |  33 +-
 .../cross_shard_messages.rs                   | 198 ++++++++++++
 .../dependent_edges.rs                        | 281 ++++++++++++++++++
 .../src/sharded_block_partitioner/messages.rs |  56 ++--
 .../src/sharded_block_partitioner/mod.rs      | 278 +++++++++++------
 .../partitioning_shard.rs                     | 204 +++++--------
 execution/block-partitioner/src/types.rs      | 217 ++++++++++++--
 execution/executor-types/src/lib.rs           |   7 +-
 types/src/transaction/analyzed_transaction.rs |   4 +-
 9 files changed, 994 insertions(+), 284 deletions(-)
 create mode 100644 execution/block-partitioner/src/sharded_block_partitioner/cross_shard_messages.rs
 create mode 100644 execution/block-partitioner/src/sharded_block_partitioner/dependent_edges.rs

diff --git a/execution/block-partitioner/src/sharded_block_partitioner/conflict_detector.rs b/execution/block-partitioner/src/sharded_block_partitioner/conflict_detector.rs
index 577e7d3a11685..bed926dc5fc07 100644
--- a/execution/block-partitioner/src/sharded_block_partitioner/conflict_detector.rs
+++ b/execution/block-partitioner/src/sharded_block_partitioner/conflict_detector.rs
@@ -2,7 +2,10 @@
 
 use crate::{
     sharded_block_partitioner::dependency_analysis::{RWSet, WriteSetWithTxnIndex},
-    types::{CrossShardDependencies, ShardId, SubBlock, TransactionWithDependencies, TxnIndex},
+    types::{
+        CrossShardDependencies, ShardId, SubBlock, TransactionWithDependencies, TxnIdxWithShardId,
+        TxnIndex,
+    },
 };
 use aptos_types::transaction::analyzed_transaction::{AnalyzedTransaction, StorageLocation};
 use std::{
@@ -43,7 +46,7 @@ impl CrossShardConflictDetector {
             if self.check_for_cross_shard_conflict(self.shard_id, &txn, cross_shard_rw_set) {
                 rejected_txns.push(txn);
             } else {
-                accepted_txn_dependencies.push(self.get_dependencies_for_frozen_txn(
+                accepted_txn_dependencies.push(self.get_deps_for_frozen_txn(
                     &txn,
                     Arc::new(vec![]),
                     prev_rounds_rw_set_with_index.clone(),
@@ -60,7 +63,7 @@ impl CrossShardConflictDetector {
     /// txn index that has taken a read/write lock on the storage location. If we can't find any such txn index, we
     /// traverse the previous rounds read/write set in reverse order and look for the first txn index that has taken
     /// a read/write lock on the storage location.
-    fn get_dependencies_for_frozen_txn(
+    fn get_deps_for_frozen_txn(
         &self,
         frozen_txn: &AnalyzedTransaction,
         current_round_rw_set_with_index: Arc>,
@@ -80,6 +83,7 @@ impl CrossShardConflictDetector {
             // and find the first shard id that has taken a write lock on the storage location. This ensures that we find the highest txn index that is conflicting
             // with the current transaction. Please note that since we use a multi-version database, there is no conflict if any previous txn index has taken
             // a read lock on the storage location.
+            let mut current_shard_id = (self.shard_id + self.num_shards - 1) % self.num_shards; // current shard id - 1 in a wrapping fashion
             for rw_set_with_index in current_round_rw_set_with_index
                 .iter()
                 .take(self.shard_id)
@@ -87,34 +91,45 @@ impl CrossShardConflictDetector {
                 .chain(prev_rounds_rw_set_with_index.iter().rev())
             {
                 if rw_set_with_index.has_write_lock(storage_location) {
-                    cross_shard_dependencies.add_depends_on_txn(
-                        rw_set_with_index.get_write_lock_txn_index(storage_location),
+                    cross_shard_dependencies.add_required_edge(
+                        TxnIdxWithShardId::new(
+                            rw_set_with_index.get_write_lock_txn_index(storage_location),
+                            current_shard_id,
+                        ),
+                        storage_location.clone(),
                     );
                     break;
                 }
+                // perform a wrapping substraction
+                current_shard_id = (current_shard_id + self.num_shards - 1) % self.num_shards;
             }
         }
 
         cross_shard_dependencies
     }
 
-    pub fn get_frozen_sub_block(
+    pub fn add_deps_for_frozen_sub_block(
         &self,
         txns: Vec,
         current_round_rw_set_with_index: Arc>,
         prev_round_rw_set_with_index: Arc>,
         index_offset: TxnIndex,
-    ) -> SubBlock {
+    ) -> (SubBlock, Vec) {
         let mut frozen_txns = Vec::new();
+        let mut cross_shard_dependencies = Vec::new();
         for txn in txns.into_iter() {
-            let dependency = self.get_dependencies_for_frozen_txn(
+            let dependency = self.get_deps_for_frozen_txn(
                 &txn,
                 current_round_rw_set_with_index.clone(),
                 prev_round_rw_set_with_index.clone(),
             );
+            cross_shard_dependencies.push(dependency.clone());
             frozen_txns.push(TransactionWithDependencies::new(txn, dependency));
         }
-        SubBlock::new(index_offset, frozen_txns)
+        (
+            SubBlock::new(index_offset, frozen_txns),
+            cross_shard_dependencies,
+        )
     }
 
     fn check_for_cross_shard_conflict(
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/cross_shard_messages.rs b/execution/block-partitioner/src/sharded_block_partitioner/cross_shard_messages.rs
new file mode 100644
index 0000000000000..c7cd693a0ca00
--- /dev/null
+++ b/execution/block-partitioner/src/sharded_block_partitioner/cross_shard_messages.rs
@@ -0,0 +1,198 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::{
+    sharded_block_partitioner::{
+        cross_shard_messages::CrossShardMsg::CrossShardDependentEdgesMsg,
+        dependency_analysis::{RWSet, WriteSetWithTxnIndex},
+    },
+    types::{CrossShardEdges, ShardId, TxnIndex},
+};
+use std::sync::mpsc::{Receiver, Sender};
+
+#[derive(Clone, Debug)]
+pub enum CrossShardMsg {
+    WriteSetWithTxnIndexMsg(WriteSetWithTxnIndex),
+    RWSetMsg(RWSet),
+    // Number of accepted transactions in the shard for the current round.
+    AcceptedTxnsMsg(usize),
+    CrossShardDependentEdgesMsg(Vec),
+}
+
+#[derive(Clone, Debug, Default)]
+pub struct CrossShardDependentEdges {
+    pub source_txn_index: TxnIndex,
+    pub dependent_edges: CrossShardEdges,
+}
+
+impl CrossShardDependentEdges {
+    pub fn new(source_txn_index: TxnIndex, dependent_edges: CrossShardEdges) -> Self {
+        Self {
+            source_txn_index,
+            dependent_edges,
+        }
+    }
+}
+
+// Define the interface for CrossShardClient
+pub trait CrossShardClientInterface {
+    fn broadcast_and_collect_rw_set(&self, rw_set: RWSet) -> Vec;
+    fn broadcast_and_collect_write_set_with_index(
+        &self,
+        rw_set_with_index: WriteSetWithTxnIndex,
+    ) -> Vec;
+    fn broadcast_and_collect_num_accepted_txns(&self, num_accepted_txns: usize) -> Vec;
+    fn broadcast_and_collect_dependent_edges(
+        &self,
+        dependent_edges: Vec>,
+    ) -> Vec>;
+}
+
+pub struct CrossShardClient {
+    shard_id: ShardId,
+    message_rxs: Vec>,
+    message_txs: Vec>,
+}
+
+impl CrossShardClient {
+    pub fn new(
+        shard_id: ShardId,
+        message_rxs: Vec>,
+        message_txs: Vec>,
+    ) -> Self {
+        Self {
+            shard_id,
+            message_rxs,
+            message_txs,
+        }
+    }
+
+    fn broadcast_and_collect(&self, f: F, g: G) -> Vec
+    where
+        F: Fn() -> CrossShardMsg,
+        G: Fn(CrossShardMsg) -> Option,
+        T: Default + Clone,
+    {
+        let num_shards = self.message_txs.len();
+        let mut vec = vec![T::default(); num_shards];
+
+        for i in 0..num_shards {
+            if i != self.shard_id {
+                self.message_txs[i].send(f()).unwrap();
+            }
+        }
+
+        for (i, msg_rx) in self.message_rxs.iter().enumerate() {
+            if i == self.shard_id {
+                continue;
+            }
+            let msg = msg_rx.recv().unwrap();
+            vec[i] = g(msg).expect("Unexpected message");
+        }
+        vec
+    }
+}
+
+impl CrossShardClientInterface for CrossShardClient {
+    fn broadcast_and_collect_rw_set(&self, rw_set: RWSet) -> Vec {
+        self.broadcast_and_collect(
+            || CrossShardMsg::RWSetMsg(rw_set.clone()),
+            |msg| match msg {
+                CrossShardMsg::RWSetMsg(rw_set) => Some(rw_set),
+                _ => None,
+            },
+        )
+    }
+
+    fn broadcast_and_collect_write_set_with_index(
+        &self,
+        rw_set_with_index: WriteSetWithTxnIndex,
+    ) -> Vec {
+        self.broadcast_and_collect(
+            || CrossShardMsg::WriteSetWithTxnIndexMsg(rw_set_with_index.clone()),
+            |msg| match msg {
+                CrossShardMsg::WriteSetWithTxnIndexMsg(rw_set_with_index) => {
+                    Some(rw_set_with_index)
+                },
+                _ => None,
+            },
+        )
+    }
+
+    fn broadcast_and_collect_num_accepted_txns(&self, num_accepted_txns: usize) -> Vec {
+        self.broadcast_and_collect(
+            || CrossShardMsg::AcceptedTxnsMsg(num_accepted_txns),
+            |msg| match msg {
+                CrossShardMsg::AcceptedTxnsMsg(num_accepted_txns) => Some(num_accepted_txns),
+                _ => None,
+            },
+        )
+    }
+
+    fn broadcast_and_collect_dependent_edges(
+        &self,
+        dependent_edges: Vec>,
+    ) -> Vec> {
+        let num_shards = self.message_txs.len();
+
+        for (shard_id, dependent_edges) in dependent_edges.into_iter().enumerate() {
+            if shard_id != self.shard_id {
+                self.message_txs[shard_id]
+                    .send(CrossShardDependentEdgesMsg(dependent_edges))
+                    .unwrap();
+            }
+        }
+
+        let mut cross_shard_dependent_edges = vec![vec![]; num_shards];
+
+        for (i, msg_rx) in self.message_rxs.iter().enumerate() {
+            if i == self.shard_id {
+                continue;
+            }
+            let msg = msg_rx.recv().unwrap();
+            match msg {
+                CrossShardDependentEdgesMsg(dependent_edges) => {
+                    cross_shard_dependent_edges[i] = dependent_edges;
+                },
+                _ => panic!("Unexpected message"),
+            }
+        }
+
+        cross_shard_dependent_edges
+    }
+}
+
+// Create a mock implementation of CrossShardClientInterface for testing
+#[cfg(test)]
+pub struct MockCrossShardClient {
+    pub rw_set_results: Vec,
+    pub write_set_with_index_results: Vec,
+    pub num_accepted_txns_results: Vec,
+    pub dependent_edges_results: Vec>,
+}
+
+// Mock CrossShardClient used for testing purposes
+#[cfg(test)]
+impl CrossShardClientInterface for MockCrossShardClient {
+    fn broadcast_and_collect_rw_set(&self, _rw_set: RWSet) -> Vec {
+        self.rw_set_results.clone()
+    }
+
+    fn broadcast_and_collect_write_set_with_index(
+        &self,
+        _rw_set_with_index: WriteSetWithTxnIndex,
+    ) -> Vec {
+        self.write_set_with_index_results.clone()
+    }
+
+    fn broadcast_and_collect_num_accepted_txns(&self, _num_accepted_txns: usize) -> Vec {
+        self.num_accepted_txns_results.clone()
+    }
+
+    fn broadcast_and_collect_dependent_edges(
+        &self,
+        _dependent_edges: Vec>,
+    ) -> Vec> {
+        self.dependent_edges_results.clone()
+    }
+}
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/dependent_edges.rs b/execution/block-partitioner/src/sharded_block_partitioner/dependent_edges.rs
new file mode 100644
index 0000000000000..b903d085c791d
--- /dev/null
+++ b/execution/block-partitioner/src/sharded_block_partitioner/dependent_edges.rs
@@ -0,0 +1,281 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::{
+    sharded_block_partitioner::cross_shard_messages::{
+        CrossShardClientInterface, CrossShardDependentEdges,
+    },
+    types::{
+        CrossShardDependencies, CrossShardEdges, ShardId, SubBlocksForShard, TxnIdxWithShardId,
+        TxnIndex,
+    },
+};
+use itertools::Itertools;
+use std::{collections::HashMap, sync::Arc};
+
+pub struct DependentEdgeCreator {
+    shard_id: ShardId,
+    cross_shard_client: Arc,
+    froze_sub_blocks: SubBlocksForShard,
+    num_shards: usize,
+}
+
+/// Creates a list of dependent edges for each sub block in the current round. It works in following steps
+/// 1. For the current block, it creates a dependent edge list by txn index based on newly required edges in cross shard
+/// dependencies. Dependent edge is a reverse of required edge, for example if txn 20 in shard 2 requires txn 10 in shard 1,
+/// then txn 10 in shard 1 will have a dependent edge to txn 20 in shard 2.
+/// 2. It sends the dependent edge list to all shards and collects the dependent edge list from all shards.
+/// 3. It groups the dependent edge list by source txn index.
+/// 4. It adds the dependent edge list to the sub blocks in the current round.
+///
+impl DependentEdgeCreator {
+    pub fn new(
+        shard_id: ShardId,
+        cross_shard_client: Arc,
+        froze_sub_blocks: SubBlocksForShard,
+        num_shards: usize,
+    ) -> Self {
+        Self {
+            shard_id,
+            cross_shard_client,
+            froze_sub_blocks,
+            num_shards,
+        }
+    }
+
+    pub fn create_dependent_edges(
+        &mut self,
+        curr_cross_shard_deps: &[CrossShardDependencies],
+        index_offset: usize,
+    ) {
+        if self.froze_sub_blocks.is_empty() {
+            // early return in case this is the first round (no previous sub blocks, so no back edges)
+            return;
+        }
+        // List of dependent edges for each shard and by source txn index
+        let mut dependent_edges: Vec> =
+            vec![HashMap::new(); self.num_shards];
+        for (index, cross_shard_deps) in curr_cross_shard_deps.iter().enumerate() {
+            let dependent_index = index + index_offset;
+            self.insert_dependent_edges_for_txn(
+                dependent_index,
+                cross_shard_deps,
+                &mut dependent_edges,
+            );
+        }
+        let dep_edges_vec = self.send_and_collect_dependent_edges(dependent_edges);
+        let dep_edges = self.group_dependent_edges_by_source_idx(dep_edges_vec);
+        self.add_dependent_edges_to_sub_blocks(dep_edges);
+    }
+
+    fn insert_dependent_edges_for_txn(
+        &mut self,
+        dependent_index: TxnIndex,
+        cross_shard_deps: &CrossShardDependencies,
+        back_edges: &mut [HashMap],
+    ) {
+        for (index_with_shard, storage_locations) in cross_shard_deps.required_edges_iter() {
+            let back_edges_for_shard = back_edges.get_mut(index_with_shard.shard_id).unwrap();
+            let back_edges = back_edges_for_shard
+                .entry(index_with_shard.txn_index)
+                .or_insert_with(CrossShardEdges::default);
+            back_edges.add_edge(
+                TxnIdxWithShardId::new(dependent_index, self.shard_id),
+                storage_locations.clone(),
+            );
+        }
+    }
+
+    fn send_and_collect_dependent_edges(
+        &self,
+        dependent_edges: Vec>,
+    ) -> Vec> {
+        let mut back_edges_vec = Vec::new();
+        for (_, back_edges_for_shard) in dependent_edges.into_iter().enumerate() {
+            let mut back_edges = Vec::new();
+            for (source_index, dependent_indices) in back_edges_for_shard {
+                back_edges.push(CrossShardDependentEdges::new(
+                    source_index,
+                    dependent_indices,
+                ));
+            }
+            back_edges_vec.push(back_edges);
+        }
+        self.cross_shard_client
+            .broadcast_and_collect_dependent_edges(back_edges_vec)
+    }
+
+    fn group_dependent_edges_by_source_idx(
+        &self,
+        dependent_edges_vec: Vec>,
+    ) -> Vec<(TxnIndex, CrossShardEdges)> {
+        // combine the back edges from different shards by source txn index
+        let mut dependent_edges_by_source_index = HashMap::new();
+        for (_, dependent_edges) in dependent_edges_vec.into_iter().enumerate() {
+            for dependent_edge in dependent_edges {
+                let source_index = dependent_edge.source_txn_index;
+                let dep_edges_for_idx = dependent_edges_by_source_index
+                    .entry(source_index)
+                    .or_insert_with(CrossShardEdges::default);
+                for (dependent_idx, storage_locations) in dependent_edge.dependent_edges.into_iter()
+                {
+                    dep_edges_for_idx.add_edge(dependent_idx, storage_locations);
+                }
+            }
+        }
+        // sort the back edges by source txn index and return a vector
+        let mut dep_edges_vec = dependent_edges_by_source_index.into_iter().collect_vec();
+        dep_edges_vec.sort_by_key(|(source_index, _)| *source_index);
+        dep_edges_vec
+    }
+
+    fn add_dependent_edges_to_sub_blocks(
+        &mut self,
+        dependent_edges: Vec<(TxnIndex, CrossShardEdges)>,
+    ) {
+        let mut current_sub_block_index = 0;
+        let mut current_sub_block = self.froze_sub_blocks.get_sub_block_mut(0).unwrap();
+        // Since the dependent edges are sorted by source txn index, we can iterate through the sub blocks and add the back edges to the sub blocks
+        for (source_index, dependent_edges) in dependent_edges.into_iter() {
+            while source_index >= current_sub_block.end_index() {
+                current_sub_block_index += 1;
+                current_sub_block = self
+                    .froze_sub_blocks
+                    .get_sub_block_mut(current_sub_block_index)
+                    .unwrap();
+            }
+
+            for (dependent_idx, storage_locations) in dependent_edges.into_iter() {
+                current_sub_block.add_dependent_edge(
+                    source_index,
+                    dependent_idx,
+                    storage_locations,
+                );
+            }
+        }
+    }
+
+    pub fn into_frozen_sub_blocks(self) -> SubBlocksForShard {
+        self.froze_sub_blocks
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::{
+        sharded_block_partitioner::{
+            cross_shard_messages::{CrossShardDependentEdges, MockCrossShardClient},
+            dependent_edges::DependentEdgeCreator,
+        },
+        test_utils::create_non_conflicting_p2p_transaction,
+        types::{
+            CrossShardDependencies, CrossShardEdges, SubBlock, SubBlocksForShard,
+            TransactionWithDependencies, TxnIdxWithShardId,
+        },
+    };
+    use aptos_types::transaction::analyzed_transaction::StorageLocation;
+    use std::sync::Arc;
+
+    #[test]
+    fn test_create_dependent_edges() {
+        let shard_id = 0;
+        let start_index = 0;
+        let num_shards = 3;
+
+        let mut transactions_with_deps = Vec::new();
+        for _ in 0..10 {
+            transactions_with_deps.push(TransactionWithDependencies::new(
+                create_non_conflicting_p2p_transaction(),
+                CrossShardDependencies::default(),
+            ));
+        }
+
+        // cross shard dependent edges from shard 1
+        let mut dependent_edges_from_shard_1 = vec![];
+        let txn_4_storgae_location: Vec =
+            transactions_with_deps[4].txn.write_hints().to_vec();
+        let txn_5_storgae_location: Vec =
+            transactions_with_deps[5].txn.write_hints().to_vec();
+        // Txn 11 is dependent on Txn 4
+        dependent_edges_from_shard_1.push(CrossShardDependentEdges::new(
+            4,
+            CrossShardEdges::new(
+                TxnIdxWithShardId::new(11, 1),
+                txn_4_storgae_location.clone(),
+            ),
+        ));
+        // Txn 12 is dependent on Txn 5
+        dependent_edges_from_shard_1.push(CrossShardDependentEdges::new(
+            5,
+            CrossShardEdges::new(
+                TxnIdxWithShardId::new(12, 1),
+                txn_5_storgae_location.clone(),
+            ),
+        ));
+
+        // cross shard dependent edges from shard 2
+        let dependent_edges_shard_2 = vec![
+            // Txn 21 is dependent on Txn 4
+            CrossShardDependentEdges::new(
+                4,
+                CrossShardEdges::new(
+                    TxnIdxWithShardId::new(21, 2),
+                    txn_4_storgae_location.clone(),
+                ),
+            ),
+            // Txn 22 is dependent on Txn 5
+            CrossShardDependentEdges::new(
+                5,
+                CrossShardEdges::new(
+                    TxnIdxWithShardId::new(22, 2),
+                    txn_5_storgae_location.clone(),
+                ),
+            ),
+        ];
+
+        let cross_shard_client = Arc::new(MockCrossShardClient {
+            rw_set_results: vec![],
+            write_set_with_index_results: vec![],
+            num_accepted_txns_results: vec![],
+            dependent_edges_results: vec![dependent_edges_from_shard_1, dependent_edges_shard_2],
+        });
+
+        let mut sub_blocks = SubBlocksForShard::empty(shard_id);
+        let sub_block = SubBlock::new(start_index, transactions_with_deps.clone());
+        sub_blocks.add_sub_block(sub_block);
+
+        let mut dependent_edge_creator =
+            DependentEdgeCreator::new(shard_id, cross_shard_client, sub_blocks, num_shards);
+
+        dependent_edge_creator.create_dependent_edges(&[], 0);
+
+        let sub_blocks_with_dependent_edges = dependent_edge_creator.into_frozen_sub_blocks();
+        assert_eq!(sub_blocks_with_dependent_edges.num_sub_blocks(), 1);
+        let sub_block = sub_blocks_with_dependent_edges.get_sub_block(0).unwrap();
+        assert_eq!(sub_block.num_txns(), 10);
+
+        let dependent_storage_locs = sub_block.transactions_with_deps()[4]
+            .cross_shard_dependencies
+            .get_dependent_edge_for(TxnIdxWithShardId::new(11, 1))
+            .unwrap();
+        assert_eq!(dependent_storage_locs, &txn_4_storgae_location);
+
+        let dependent_storage_locs = sub_block.transactions_with_deps()[5]
+            .cross_shard_dependencies
+            .get_dependent_edge_for(TxnIdxWithShardId::new(12, 1))
+            .unwrap();
+        assert_eq!(dependent_storage_locs, &txn_5_storgae_location);
+
+        let dependent_storage_locs = sub_block.transactions_with_deps()[4]
+            .cross_shard_dependencies
+            .get_dependent_edge_for(TxnIdxWithShardId::new(21, 2))
+            .unwrap();
+        assert_eq!(dependent_storage_locs, &txn_4_storgae_location);
+
+        let dependent_storage_locs = sub_block.transactions_with_deps()[5]
+            .cross_shard_dependencies
+            .get_dependent_edge_for(TxnIdxWithShardId::new(22, 2))
+            .unwrap();
+        assert_eq!(dependent_storage_locs, &txn_5_storgae_location);
+    }
+}
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/messages.rs b/execution/block-partitioner/src/sharded_block_partitioner/messages.rs
index 6b16abbc66240..d0770433d8bb8 100644
--- a/execution/block-partitioner/src/sharded_block_partitioner/messages.rs
+++ b/execution/block-partitioner/src/sharded_block_partitioner/messages.rs
@@ -1,84 +1,84 @@
 // Copyright © Aptos Foundation
 
 use crate::{
-    sharded_block_partitioner::dependency_analysis::{RWSet, WriteSetWithTxnIndex},
-    types::{SubBlock, TxnIndex},
+    sharded_block_partitioner::dependency_analysis::WriteSetWithTxnIndex,
+    types::{SubBlocksForShard, TxnIndex},
 };
 use aptos_types::transaction::analyzed_transaction::AnalyzedTransaction;
 use std::sync::Arc;
 
-pub enum ControlMsg {
-    DiscardCrossShardDepReq(DiscardTxnsWithCrossShardDep),
-    AddCrossShardDepReq(AddTxnsWithCrossShardDep),
-    Stop,
-}
-
-#[derive(Clone, Debug)]
-pub enum CrossShardMsg {
-    WriteSetWithTxnIndexMsg(WriteSetWithTxnIndex),
-    RWSetMsg(RWSet),
-    // Number of accepted transactions in the shard for the current round.
-    AcceptedTxnsMsg(usize),
-}
-
-pub struct DiscardTxnsWithCrossShardDep {
+pub struct DiscardCrossShardDep {
     pub transactions: Vec,
     // The frozen dependencies in previous chunks.
     pub prev_rounds_write_set_with_index: Arc>,
-    pub prev_rounds_frozen_sub_blocks: Arc>,
+    pub current_round_start_index: TxnIndex,
+    // This is the frozen sub block for the current shard and is passed because we want to modify
+    // it to add dependency back edges.
+    pub frozen_sub_blocks: SubBlocksForShard,
 }
 
-impl DiscardTxnsWithCrossShardDep {
+impl DiscardCrossShardDep {
     pub fn new(
         transactions: Vec,
         prev_rounds_write_set_with_index: Arc>,
-        prev_rounds_frozen_sub_blocks: Arc>,
+        current_round_start_index: TxnIndex,
+        frozen_sub_blocks: SubBlocksForShard,
     ) -> Self {
         Self {
             transactions,
             prev_rounds_write_set_with_index,
-            prev_rounds_frozen_sub_blocks,
+            current_round_start_index,
+            frozen_sub_blocks,
         }
     }
 }
 
-pub struct AddTxnsWithCrossShardDep {
+pub struct AddWithCrossShardDep {
     pub transactions: Vec,
     pub index_offset: TxnIndex,
     // The frozen dependencies in previous chunks.
     pub prev_rounds_write_set_with_index: Arc>,
+    pub frozen_sub_blocks: SubBlocksForShard,
 }
 
-impl AddTxnsWithCrossShardDep {
+impl AddWithCrossShardDep {
     pub fn new(
         transactions: Vec,
         index_offset: TxnIndex,
         prev_rounds_write_set_with_index: Arc>,
+        frozen_sub_blocks: SubBlocksForShard,
     ) -> Self {
         Self {
             transactions,
             index_offset,
             prev_rounds_write_set_with_index,
+            frozen_sub_blocks,
         }
     }
 }
 
-pub struct PartitioningBlockResponse {
-    pub frozen_sub_block: SubBlock,
+pub struct PartitioningResp {
+    pub frozen_sub_blocks: SubBlocksForShard,
     pub write_set_with_index: WriteSetWithTxnIndex,
     pub discarded_txns: Vec,
 }
 
-impl PartitioningBlockResponse {
+impl PartitioningResp {
     pub fn new(
-        frozen_sub_block: SubBlock,
+        frozen_sub_blocks: SubBlocksForShard,
         write_set_with_index: WriteSetWithTxnIndex,
         discarded_txns: Vec,
     ) -> Self {
         Self {
-            frozen_sub_block,
+            frozen_sub_blocks,
             write_set_with_index,
             discarded_txns,
         }
     }
 }
+
+pub enum ControlMsg {
+    DiscardCrossShardDepReq(DiscardCrossShardDep),
+    AddCrossShardDepReq(AddWithCrossShardDep),
+    Stop,
+}
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/mod.rs b/execution/block-partitioner/src/sharded_block_partitioner/mod.rs
index bc80102fb3c14..3ea0842ca428b 100644
--- a/execution/block-partitioner/src/sharded_block_partitioner/mod.rs
+++ b/execution/block-partitioner/src/sharded_block_partitioner/mod.rs
@@ -3,18 +3,20 @@
 
 use crate::{
     sharded_block_partitioner::{
+        cross_shard_messages::CrossShardMsg,
         dependency_analysis::WriteSetWithTxnIndex,
         messages::{
-            AddTxnsWithCrossShardDep, ControlMsg,
+            AddWithCrossShardDep, ControlMsg,
             ControlMsg::{AddCrossShardDepReq, DiscardCrossShardDepReq},
-            CrossShardMsg, DiscardTxnsWithCrossShardDep, PartitioningBlockResponse,
+            DiscardCrossShardDep, PartitioningResp,
         },
         partitioning_shard::PartitioningShard,
     },
-    types::{ShardId, SubBlock},
+    types::{ShardId, SubBlocksForShard, TxnIndex},
 };
 use aptos_logger::{error, info};
 use aptos_types::transaction::analyzed_transaction::AnalyzedTransaction;
+use itertools::Itertools;
 use std::{
     collections::HashMap,
     sync::{
@@ -25,7 +27,9 @@ use std::{
 };
 
 mod conflict_detector;
+mod cross_shard_messages;
 mod dependency_analysis;
+mod dependent_edges;
 mod messages;
 mod partitioning_shard;
 
@@ -102,7 +106,7 @@ mod partitioning_shard;
 pub struct ShardedBlockPartitioner {
     num_shards: usize,
     control_txs: Vec>,
-    result_rxs: Vec>,
+    result_rxs: Vec>,
     shard_threads: Vec>,
 }
 
@@ -202,25 +206,25 @@ impl ShardedBlockPartitioner {
     fn collect_partition_block_response(
         &self,
     ) -> (
-        Vec,
+        Vec,
         Vec,
         Vec>,
     ) {
-        let mut frozen_chunks = Vec::new();
+        let mut frozen_sub_blocks = Vec::new();
         let mut frozen_write_set_with_index = Vec::new();
         let mut rejected_txns_vec = Vec::new();
         for rx in &self.result_rxs {
-            let PartitioningBlockResponse {
-                frozen_sub_block: frozen_chunk,
+            let PartitioningResp {
+                frozen_sub_blocks: frozen_chunk,
                 write_set_with_index,
                 discarded_txns: rejected_txns,
             } = rx.recv().unwrap();
-            frozen_chunks.push(frozen_chunk);
+            frozen_sub_blocks.push(frozen_chunk);
             frozen_write_set_with_index.push(write_set_with_index);
             rejected_txns_vec.push(rejected_txns);
         }
         (
-            frozen_chunks,
+            frozen_sub_blocks,
             frozen_write_set_with_index,
             rejected_txns_vec,
         )
@@ -229,20 +233,23 @@ impl ShardedBlockPartitioner {
     fn discard_txns_with_cross_shard_dependencies(
         &self,
         txns_to_partition: Vec>,
-        frozen_sub_blocks: Arc>,
+        current_round_start_index: TxnIndex,
+        frozen_sub_blocks: Vec,
         frozen_write_set_with_index: Arc>,
     ) -> (
-        Vec,
+        Vec,
         Vec,
         Vec>,
     ) {
         let partition_block_msgs = txns_to_partition
             .into_iter()
-            .map(|txns| {
-                DiscardCrossShardDepReq(DiscardTxnsWithCrossShardDep::new(
+            .zip_eq(frozen_sub_blocks.into_iter())
+            .map(|(txns, sub_blocks)| {
+                DiscardCrossShardDepReq(DiscardCrossShardDep::new(
                     txns,
                     frozen_write_set_with_index.clone(),
-                    frozen_sub_blocks.clone(),
+                    current_round_start_index,
+                    sub_blocks,
                 ))
             })
             .collect();
@@ -254,21 +261,24 @@ impl ShardedBlockPartitioner {
         &self,
         index_offset: usize,
         remaining_txns_vec: Vec>,
+        frozen_sub_blocks_by_shard: Vec,
         frozen_write_set_with_index: Arc>,
     ) -> (
-        Vec,
+        Vec,
         Vec,
         Vec>,
     ) {
         let mut index_offset = index_offset;
         let partition_block_msgs = remaining_txns_vec
             .into_iter()
-            .map(|remaining_txns| {
+            .zip_eq(frozen_sub_blocks_by_shard.into_iter())
+            .map(|(remaining_txns, frozen_sub_blocks)| {
                 let remaining_txns_len = remaining_txns.len();
-                let partitioning_msg = AddCrossShardDepReq(AddTxnsWithCrossShardDep::new(
+                let partitioning_msg = AddCrossShardDepReq(AddWithCrossShardDep::new(
                     remaining_txns,
                     index_offset,
                     frozen_write_set_with_index.clone(),
+                    frozen_sub_blocks,
                 ));
                 index_offset += remaining_txns_len;
                 partitioning_msg
@@ -285,7 +295,7 @@ impl ShardedBlockPartitioner {
         &self,
         transactions: Vec,
         num_partitioning_round: usize,
-    ) -> Vec {
+    ) -> Vec {
         let total_txns = transactions.len();
         if total_txns == 0 {
             return vec![];
@@ -294,24 +304,32 @@ impl ShardedBlockPartitioner {
         // First round, we filter all transactions with cross-shard dependencies
         let mut txns_to_partition = self.partition_by_senders(transactions);
         let mut frozen_write_set_with_index = Arc::new(Vec::new());
-        let mut frozen_sub_blocks = Arc::new(Vec::new());
+        let mut current_round_start_index = 0;
+        let mut frozen_sub_blocks: Vec = vec![];
+        for shard_id in 0..self.num_shards {
+            frozen_sub_blocks.push(SubBlocksForShard::empty(shard_id))
+        }
 
         for _ in 0..num_partitioning_round {
             let (
-                current_frozen_sub_blocks_vec,
+                updated_frozen_sub_blocks,
                 current_frozen_rw_set_with_index_vec,
                 discarded_txns_to_partition,
             ) = self.discard_txns_with_cross_shard_dependencies(
                 txns_to_partition,
-                frozen_sub_blocks.clone(),
+                current_round_start_index,
+                frozen_sub_blocks,
                 frozen_write_set_with_index.clone(),
             );
-            let mut prev_frozen_sub_blocks = Arc::try_unwrap(frozen_sub_blocks).unwrap();
+            // Current round start index is the sum of the number of transactions in the frozen sub-blocks
+            current_round_start_index = updated_frozen_sub_blocks
+                .iter()
+                .map(|sub_blocks| sub_blocks.num_txns())
+                .sum::();
             let mut prev_frozen_write_set_with_index =
                 Arc::try_unwrap(frozen_write_set_with_index).unwrap();
-            prev_frozen_sub_blocks.extend(current_frozen_sub_blocks_vec);
+            frozen_sub_blocks = updated_frozen_sub_blocks;
             prev_frozen_write_set_with_index.extend(current_frozen_rw_set_with_index_vec);
-            frozen_sub_blocks = Arc::new(prev_frozen_sub_blocks);
             frozen_write_set_with_index = Arc::new(prev_frozen_write_set_with_index);
             txns_to_partition = discarded_txns_to_partition;
             if txns_to_partition
@@ -320,26 +338,21 @@ impl ShardedBlockPartitioner {
                 .sum::()
                 == 0
             {
-                return Arc::try_unwrap(frozen_sub_blocks).unwrap();
+                return frozen_sub_blocks;
             }
         }
 
         // We just add cross shard dependencies for remaining transactions.
-        let index_offset = frozen_sub_blocks
-            .iter()
-            .map(|chunk| chunk.len())
-            .sum::();
-        let (remaining_frozen_chunks, _, _) = self.add_cross_shard_dependencies(
-            index_offset,
+        let (frozen_sub_blocks, _, rejected_txns) = self.add_cross_shard_dependencies(
+            current_round_start_index,
             txns_to_partition,
+            frozen_sub_blocks,
             frozen_write_set_with_index,
         );
 
-        Arc::try_unwrap(frozen_sub_blocks)
-            .unwrap()
-            .into_iter()
-            .chain(remaining_frozen_chunks.into_iter())
-            .collect::>()
+        // Assert rejected transactions are empty
+        assert!(rejected_txns.iter().all(|txns| txns.is_empty()));
+        frozen_sub_blocks
     }
 }
 
@@ -365,7 +378,7 @@ impl Drop for ShardedBlockPartitioner {
 fn spawn_partitioning_shard(
     shard_id: ShardId,
     control_rx: Receiver,
-    result_tx: Sender,
+    result_tx: Sender,
     message_rxs: Vec>,
     messages_txs: Vec>,
 ) -> thread::JoinHandle<()> {
@@ -388,17 +401,17 @@ mod tests {
             create_non_conflicting_p2p_transaction, create_signed_p2p_transaction,
             generate_test_account, generate_test_account_for_address, TestAccount,
         },
-        types::SubBlock,
+        types::{SubBlock, TxnIdxWithShardId},
     };
     use aptos_types::transaction::analyzed_transaction::AnalyzedTransaction;
     use move_core_types::account_address::AccountAddress;
     use rand::{rngs::OsRng, Rng};
     use std::collections::HashMap;
 
-    fn verify_no_cross_shard_dependency(partitioned_txns: Vec) {
-        for chunk in partitioned_txns {
-            for txn in chunk.transactions {
-                assert_eq!(txn.cross_shard_dependencies().len(), 0);
+    fn verify_no_cross_shard_dependency(sub_blocks_for_shards: Vec) {
+        for sub_blocks in sub_blocks_for_shards {
+            for txn in sub_blocks.iter() {
+                assert_eq!(txn.cross_shard_dependencies().num_required_edges(), 0);
             }
         }
     }
@@ -419,19 +432,19 @@ mod tests {
             receivers.iter().collect::>(),
         );
         let partitioner = ShardedBlockPartitioner::new(4);
-        let partitioned_txns = partitioner.partition(transactions.clone(), 1);
-        assert_eq!(partitioned_txns.len(), 4);
+        let sub_blocks = partitioner.partition(transactions.clone(), 1);
+        assert_eq!(sub_blocks.len(), 4);
         // The first shard should contain all the transactions
-        assert_eq!(partitioned_txns[0].len(), num_txns);
+        assert_eq!(sub_blocks[0].num_txns(), num_txns);
         // The rest of the shards should be empty
-        for txns in partitioned_txns.iter().take(4).skip(1) {
-            assert_eq!(txns.len(), 0);
+        for sub_blocks in sub_blocks.iter().take(4).skip(1) {
+            assert_eq!(sub_blocks.num_txns(), 0);
         }
         // Verify that the transactions are in the same order as the original transactions and cross shard
         // dependencies are empty.
-        for (i, txn) in partitioned_txns[0].transactions.iter().enumerate() {
+        for (i, txn) in sub_blocks[0].iter().enumerate() {
             assert_eq!(txn.txn(), &transactions[i]);
-            assert_eq!(txn.cross_shard_dependencies().len(), 0);
+            assert_eq!(txn.cross_shard_dependencies().num_required_edges(), 0);
         }
     }
 
@@ -451,11 +464,11 @@ mod tests {
         // Verify that the transactions are in the same order as the original transactions and cross shard
         // dependencies are empty.
         let mut current_index = 0;
-        for analyzed_txns in partitioned_txns.into_iter() {
-            assert_eq!(analyzed_txns.len(), num_txns / num_shards);
-            for txn in analyzed_txns.transactions.iter() {
+        for sub_blocks_for_shard in partitioned_txns.into_iter() {
+            assert_eq!(sub_blocks_for_shard.num_txns(), num_txns / num_shards);
+            for txn in sub_blocks_for_shard.iter() {
                 assert_eq!(txn.txn(), &transactions[current_index]);
-                assert_eq!(txn.cross_shard_dependencies().len(), 0);
+                assert_eq!(txn.cross_shard_dependencies().num_required_edges(), 0);
                 current_index += 1;
             }
         }
@@ -496,17 +509,26 @@ mod tests {
         transactions.push(txns_from_sender[txn_from_sender_index].clone());
 
         let partitioner = ShardedBlockPartitioner::new(num_shards);
-        let partitioned_txns = partitioner.partition(transactions.clone(), 1);
-        assert_eq!(partitioned_txns.len(), num_shards);
-        assert_eq!(partitioned_txns[0].len(), 6);
-        assert_eq!(partitioned_txns[1].len(), 2);
-        assert_eq!(partitioned_txns[2].len(), 0);
+        let sub_blocks = partitioner.partition(transactions.clone(), 1);
+        assert_eq!(sub_blocks.len(), num_shards);
+        assert_eq!(sub_blocks[0].num_sub_blocks(), 1);
+        assert_eq!(sub_blocks[1].num_sub_blocks(), 1);
+        assert_eq!(sub_blocks[2].num_sub_blocks(), 1);
+        assert_eq!(sub_blocks[0].num_txns(), 6);
+        assert_eq!(sub_blocks[1].num_txns(), 2);
+        assert_eq!(sub_blocks[2].num_txns(), 0);
 
         // verify that all transactions from the sender end up in shard 0
-        for (index, txn) in txns_from_sender.iter().enumerate() {
-            assert_eq!(partitioned_txns[0].transactions[index + 1].txn(), txn);
+        for (txn_from_sender, txn) in txns_from_sender.iter().zip(sub_blocks[0].iter().skip(1)) {
+            assert_eq!(txn.txn(), txn_from_sender);
         }
-        verify_no_cross_shard_dependency(partitioned_txns);
+        verify_no_cross_shard_dependency(
+            sub_blocks
+                .iter()
+                .flat_map(|sub_blocks| sub_blocks.sub_block_iter())
+                .cloned()
+                .collect(),
+        );
     }
 
     #[test]
@@ -547,41 +569,80 @@ mod tests {
         ];
 
         let partitioner = ShardedBlockPartitioner::new(num_shards);
-        let partitioned_chunks = partitioner.partition(transactions, 1);
-        assert_eq!(partitioned_chunks.len(), 2 * num_shards);
+        let partitioned_sub_blocks = partitioner.partition(transactions, 1);
+        assert_eq!(partitioned_sub_blocks.len(), num_shards);
 
         // In first round of the partitioning, we should have txn0, txn1 and txn2 in shard 0 and
         // txn3, txn4, txn5 and txn8 in shard 1 and 0 in shard 2. Please note that txn8 is moved to
         // shard 1 because of sender based reordering.
-        assert_eq!(partitioned_chunks[0].len(), 3);
-        assert_eq!(partitioned_chunks[1].len(), 4);
-        assert_eq!(partitioned_chunks[2].len(), 0);
+        assert_eq!(
+            partitioned_sub_blocks[0]
+                .get_sub_block(0)
+                .unwrap()
+                .num_txns(),
+            3
+        );
+        assert_eq!(
+            partitioned_sub_blocks[1]
+                .get_sub_block(0)
+                .unwrap()
+                .num_txns(),
+            4
+        );
+        assert_eq!(
+            partitioned_sub_blocks[2]
+                .get_sub_block(0)
+                .unwrap()
+                .num_txns(),
+            0
+        );
 
         assert_eq!(
-            partitioned_chunks[0]
-                .transactions_with_deps()
+            partitioned_sub_blocks[0]
+                .get_sub_block(0)
+                .unwrap()
                 .iter()
                 .map(|x| x.txn.clone())
                 .collect::>(),
             vec![txn0, txn1, txn2]
         );
         assert_eq!(
-            partitioned_chunks[1]
-                .transactions_with_deps()
+            partitioned_sub_blocks[1]
+                .get_sub_block(0)
+                .unwrap()
                 .iter()
                 .map(|x| x.txn.clone())
                 .collect::>(),
             vec![txn3, txn4, txn5, txn8]
         );
-
-        // Rest of the transactions will be added in round 2 along with their dependencies
-        assert_eq!(partitioned_chunks[3].len(), 0);
-        assert_eq!(partitioned_chunks[4].len(), 0);
-        assert_eq!(partitioned_chunks[5].len(), 2);
+        //
+        // // Rest of the transactions will be added in round 2 along with their dependencies
+        assert_eq!(
+            partitioned_sub_blocks[0]
+                .get_sub_block(1)
+                .unwrap()
+                .num_txns(),
+            0
+        );
+        assert_eq!(
+            partitioned_sub_blocks[1]
+                .get_sub_block(1)
+                .unwrap()
+                .num_txns(),
+            0
+        );
+        assert_eq!(
+            partitioned_sub_blocks[2]
+                .get_sub_block(1)
+                .unwrap()
+                .num_txns(),
+            2
+        );
 
         assert_eq!(
-            partitioned_chunks[5]
-                .transactions_with_deps()
+            partitioned_sub_blocks[2]
+                .get_sub_block(1)
+                .unwrap()
                 .iter()
                 .map(|x| x.txn.clone())
                 .collect::>(),
@@ -590,17 +651,57 @@ mod tests {
 
         // Verify transaction dependencies
         verify_no_cross_shard_dependency(vec![
-            partitioned_chunks[0].clone(),
-            partitioned_chunks[1].clone(),
-            partitioned_chunks[2].clone(),
+            partitioned_sub_blocks[0].get_sub_block(0).unwrap().clone(),
+            partitioned_sub_blocks[1].get_sub_block(0).unwrap().clone(),
+            partitioned_sub_blocks[2].get_sub_block(0).unwrap().clone(),
         ]);
-        // txn6 and txn7 depends on txn8 (index 6)
-        assert!(partitioned_chunks[5].transactions_with_deps()[0]
+        // Verify transaction depends_on and dependency list
+
+        // txn6 (index 7) and txn7 (index 8) depends on txn8 (index 6)
+        partitioned_sub_blocks[2]
+            .get_sub_block(1)
+            .unwrap()
+            .iter()
+            .for_each(|txn| {
+                let required_deps = txn
+                    .cross_shard_dependencies
+                    .get_required_edge_for(TxnIdxWithShardId::new(6, 1))
+                    .unwrap();
+                // txn (6, 7) and 8 has conflict only on the coin store of account 7 as txn (6,7) are sending
+                // from account 7 and txn 8 is receiving in account 7
+                assert_eq!(required_deps.len(), 1);
+                assert_eq!(
+                    required_deps[0],
+                    AnalyzedTransaction::coin_store_location(account7.account_address)
+                );
+            });
+
+        // Verify the dependent edges, again the conflict is only on the coin store of account 7
+        let required_deps = partitioned_sub_blocks[1]
+            .get_sub_block(0)
+            .unwrap()
+            .transactions[3]
             .cross_shard_dependencies
-            .is_depends_on(6));
-        assert!(partitioned_chunks[5].transactions_with_deps()[1]
+            .get_dependent_edge_for(TxnIdxWithShardId::new(7, 2))
+            .unwrap();
+        assert_eq!(required_deps.len(), 1);
+        assert_eq!(
+            required_deps[0],
+            AnalyzedTransaction::coin_store_location(account7.account_address)
+        );
+
+        let required_deps = partitioned_sub_blocks[1]
+            .get_sub_block(0)
+            .unwrap()
+            .transactions[3]
             .cross_shard_dependencies
-            .is_depends_on(6));
+            .get_dependent_edge_for(TxnIdxWithShardId::new(8, 2))
+            .unwrap();
+        assert_eq!(required_deps.len(), 1);
+        assert_eq!(
+            required_deps[0],
+            AnalyzedTransaction::coin_store_location(account7.account_address)
+        );
     }
 
     #[test]
@@ -634,8 +735,9 @@ mod tests {
         // Build a map of storage location to corresponding shards in first round
         // and ensure that no storage location is present in more than one shard.
         let mut storage_location_to_shard_map = HashMap::new();
-        for (shard_id, txns) in partitioned_txns.iter().enumerate().take(num_shards) {
-            for txn in txns.transactions_with_deps().iter() {
+        for (shard_id, txns) in partitioned_txns.iter().enumerate() {
+            let first_round_sub_block = txns.get_sub_block(0).unwrap();
+            for txn in first_round_sub_block.iter() {
                 let storage_locations = txn
                     .txn()
                     .read_hints()
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/partitioning_shard.rs b/execution/block-partitioner/src/sharded_block_partitioner/partitioning_shard.rs
index ccaf34d502606..5a9efc86b945e 100644
--- a/execution/block-partitioner/src/sharded_block_partitioner/partitioning_shard.rs
+++ b/execution/block-partitioner/src/sharded_block_partitioner/partitioning_shard.rs
@@ -1,15 +1,12 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
-// Copyright © Aptos Foundation
-// SPDX-License-Identifier: Apache-2.0
 use crate::{
     sharded_block_partitioner::{
         conflict_detector::CrossShardConflictDetector,
+        cross_shard_messages::{CrossShardClient, CrossShardClientInterface, CrossShardMsg},
         dependency_analysis::{RWSet, WriteSetWithTxnIndex},
-        messages::{
-            AddTxnsWithCrossShardDep, ControlMsg, CrossShardMsg, DiscardTxnsWithCrossShardDep,
-            PartitioningBlockResponse,
-        },
+        dependent_edges::DependentEdgeCreator,
+        messages::{AddWithCrossShardDep, ControlMsg, DiscardCrossShardDep, PartitioningResp},
     },
     types::{ShardId, SubBlock, TransactionWithDependencies},
 };
@@ -20,155 +17,74 @@ use std::sync::{
 };
 
 pub struct PartitioningShard {
+    num_shards: usize,
     shard_id: ShardId,
     control_rx: Receiver,
-    result_tx: Sender,
-    message_rxs: Vec>,
-    message_txs: Vec>,
+    result_tx: Sender,
+    cross_shard_client: Arc,
 }
 
 impl PartitioningShard {
     pub fn new(
         shard_id: ShardId,
         control_rx: Receiver,
-        result_tx: Sender,
+        result_tx: Sender,
         message_rxs: Vec>,
-        messages_txs: Vec>,
+        message_txs: Vec>,
     ) -> Self {
+        let num_shards = message_txs.len();
+        let cross_shard_client =
+            Arc::new(CrossShardClient::new(shard_id, message_rxs, message_txs));
         Self {
+            num_shards,
             shard_id,
             control_rx,
             result_tx,
-            message_rxs,
-            message_txs: messages_txs,
-        }
-    }
-
-    fn broadcast_rw_set(&self, rw_set: RWSet) {
-        let num_shards = self.message_txs.len();
-        for i in 0..num_shards {
-            if i != self.shard_id {
-                self.message_txs[i]
-                    .send(CrossShardMsg::RWSetMsg(rw_set.clone()))
-                    .unwrap();
-            }
-        }
-    }
-
-    fn collect_rw_set(&self) -> Vec {
-        let mut rw_set_vec = vec![RWSet::default(); self.message_txs.len()];
-        for (i, msg_rx) in self.message_rxs.iter().enumerate() {
-            if i == self.shard_id {
-                continue;
-            }
-
-            let msg = msg_rx.recv().unwrap();
-            match msg {
-                CrossShardMsg::RWSetMsg(rw_set) => {
-                    rw_set_vec[i] = rw_set;
-                },
-                _ => panic!("Unexpected message"),
-            }
-        }
-        rw_set_vec
-    }
-
-    fn broadcast_write_set_with_index(&self, rw_set_with_index: WriteSetWithTxnIndex) {
-        let num_shards = self.message_txs.len();
-        for i in 0..num_shards {
-            if i != self.shard_id {
-                self.message_txs[i]
-                    .send(CrossShardMsg::WriteSetWithTxnIndexMsg(
-                        rw_set_with_index.clone(),
-                    ))
-                    .unwrap();
-            }
+            cross_shard_client,
         }
     }
 
-    fn collect_write_set_with_index(&self) -> Vec {
-        let mut rw_set_with_index_vec =
-            vec![WriteSetWithTxnIndex::default(); self.message_txs.len()];
-        for (i, msg_rx) in self.message_rxs.iter().enumerate() {
-            if i == self.shard_id {
-                continue;
-            }
-            let msg = msg_rx.recv().unwrap();
-            match msg {
-                CrossShardMsg::WriteSetWithTxnIndexMsg(rw_set_with_index) => {
-                    rw_set_with_index_vec[i] = rw_set_with_index;
-                },
-                _ => panic!("Unexpected message"),
-            }
-        }
-        rw_set_with_index_vec
-    }
-
-    fn broadcast_num_accepted_txns(&self, num_accepted_txns: usize) {
-        let num_shards = self.message_txs.len();
-        for i in 0..num_shards {
-            if i != self.shard_id {
-                self.message_txs[i]
-                    .send(CrossShardMsg::AcceptedTxnsMsg(num_accepted_txns))
-                    .unwrap();
-            }
-        }
-    }
-
-    fn collect_num_accepted_txns(&self) -> Vec {
-        let mut accepted_txns_vec = vec![0; self.message_txs.len()];
-        for (i, msg_rx) in self.message_rxs.iter().enumerate() {
-            if i == self.shard_id {
-                continue;
-            }
-            let msg = msg_rx.recv().unwrap();
-            match msg {
-                CrossShardMsg::AcceptedTxnsMsg(num_accepted_txns) => {
-                    accepted_txns_vec[i] = num_accepted_txns;
-                },
-                _ => panic!("Unexpected message"),
-            }
-        }
-        accepted_txns_vec
-    }
-
-    fn discard_txns_with_cross_shard_deps(&self, partition_msg: DiscardTxnsWithCrossShardDep) {
-        let DiscardTxnsWithCrossShardDep {
+    fn discard_txns_with_cross_shard_deps(&self, partition_msg: DiscardCrossShardDep) {
+        let DiscardCrossShardDep {
             transactions,
             prev_rounds_write_set_with_index,
-            prev_rounds_frozen_sub_blocks,
+            current_round_start_index,
+            frozen_sub_blocks,
         } = partition_msg;
-        let num_shards = self.message_txs.len();
-        let mut conflict_detector = CrossShardConflictDetector::new(self.shard_id, num_shards);
+        let mut conflict_detector = CrossShardConflictDetector::new(self.shard_id, self.num_shards);
         // If transaction filtering is allowed, we need to prepare the dependency analysis and broadcast it to other shards
         // Based on the dependency analysis received from other shards, we will reject transactions that are conflicting with
         // transactions in other shards
         let read_write_set = RWSet::new(&transactions);
-        self.broadcast_rw_set(read_write_set);
-        let cross_shard_rw_set = self.collect_rw_set();
+        let cross_shard_rw_set = self
+            .cross_shard_client
+            .broadcast_and_collect_rw_set(read_write_set);
         let (accepted_txns, accepted_cross_shard_dependencies, rejected_txns) = conflict_detector
             .discard_txns_with_cross_shard_deps(
                 transactions,
                 &cross_shard_rw_set,
                 prev_rounds_write_set_with_index,
             );
+
         // Broadcast and collect the stats around number of accepted and rejected transactions from other shards
         // this will be used to determine the absolute index of accepted transactions in this shard.
-        self.broadcast_num_accepted_txns(accepted_txns.len());
-        let accepted_txns_vec = self.collect_num_accepted_txns();
+        let accepted_txns_vec = self
+            .cross_shard_client
+            .broadcast_and_collect_num_accepted_txns(accepted_txns.len());
         // Calculate the absolute index of accepted transactions in this shard, which is the sum of all accepted transactions
-        // from other shards whose shard id is smaller than the current shard id and the number of accepted transactions in the
-        // previous rounds
-        // TODO(skedia): Evaluate if we can avoid this calculation by tracking it with a number across rounds.
-        let mut index_offset = prev_rounds_frozen_sub_blocks
-            .iter()
-            .map(|chunk| chunk.len())
-            .sum::();
-        // Drop the previous rounds frozen sub blocks so that the reference count for this drops and
-        // the coordinator can unwrap the Arc after receiving the response
-        drop(prev_rounds_frozen_sub_blocks);
+        // from other shards whose shard id is smaller than the current shard id and the current round start index
         let num_accepted_txns = accepted_txns_vec.iter().take(self.shard_id).sum::();
-        index_offset += num_accepted_txns;
+        let index_offset = current_round_start_index + num_accepted_txns;
+
+        // Now that we have finalized the global transaction index, we can add the dependent txn edges.
+        let mut dependent_edge_creator = DependentEdgeCreator::new(
+            self.shard_id,
+            self.cross_shard_client.clone(),
+            frozen_sub_blocks,
+            self.num_shards,
+        );
+        dependent_edge_creator
+            .create_dependent_edges(&accepted_cross_shard_dependencies, index_offset);
 
         // Calculate the RWSetWithTxnIndex for the accepted transactions
         let current_rw_set_with_index = WriteSetWithTxnIndex::new(&accepted_txns, index_offset);
@@ -179,43 +95,57 @@ impl PartitioningShard {
             .map(|(txn, dependencies)| TransactionWithDependencies::new(txn, dependencies))
             .collect::>();
 
-        let frozen_sub_block = SubBlock::new(index_offset, accepted_txns_with_dependencies);
+        let mut frozen_sub_blocks = dependent_edge_creator.into_frozen_sub_blocks();
+        let current_frozen_sub_block = SubBlock::new(index_offset, accepted_txns_with_dependencies);
+        frozen_sub_blocks.add_sub_block(current_frozen_sub_block);
         // send the result back to the controller
         self.result_tx
-            .send(PartitioningBlockResponse::new(
-                frozen_sub_block,
+            .send(PartitioningResp::new(
+                frozen_sub_blocks,
                 current_rw_set_with_index,
                 rejected_txns,
             ))
             .unwrap();
     }
 
-    fn add_txns_with_cross_shard_deps(&self, partition_msg: AddTxnsWithCrossShardDep) {
-        let AddTxnsWithCrossShardDep {
+    fn add_txns_with_cross_shard_deps(&self, partition_msg: AddWithCrossShardDep) {
+        let AddWithCrossShardDep {
             transactions,
             index_offset,
             // The frozen dependencies in previous chunks.
             prev_rounds_write_set_with_index,
+            mut frozen_sub_blocks,
         } = partition_msg;
-        let num_shards = self.message_txs.len();
-        let conflict_detector = CrossShardConflictDetector::new(self.shard_id, num_shards);
+        let conflict_detector = CrossShardConflictDetector::new(self.shard_id, self.num_shards);
 
         // Since txn filtering is not allowed, we can create the RW set with maximum txn
         // index with the index offset passed.
         let write_set_with_index_for_shard = WriteSetWithTxnIndex::new(&transactions, index_offset);
 
-        self.broadcast_write_set_with_index(write_set_with_index_for_shard.clone());
-        let current_round_rw_set_with_index = self.collect_write_set_with_index();
-        let frozen_sub_block = conflict_detector.get_frozen_sub_block(
-            transactions,
-            Arc::new(current_round_rw_set_with_index),
-            prev_rounds_write_set_with_index,
-            index_offset,
+        let current_round_rw_set_with_index = self
+            .cross_shard_client
+            .broadcast_and_collect_write_set_with_index(write_set_with_index_for_shard.clone());
+        let (current_frozen_sub_block, current_cross_shard_deps) = conflict_detector
+            .add_deps_for_frozen_sub_block(
+                transactions,
+                Arc::new(current_round_rw_set_with_index),
+                prev_rounds_write_set_with_index,
+                index_offset,
+            );
+
+        frozen_sub_blocks.add_sub_block(current_frozen_sub_block);
+
+        let mut dependent_edge_creator = DependentEdgeCreator::new(
+            self.shard_id,
+            self.cross_shard_client.clone(),
+            frozen_sub_blocks,
+            self.num_shards,
         );
+        dependent_edge_creator.create_dependent_edges(¤t_cross_shard_deps, index_offset);
 
         self.result_tx
-            .send(PartitioningBlockResponse::new(
-                frozen_sub_block,
+            .send(PartitioningResp::new(
+                dependent_edge_creator.into_frozen_sub_blocks(),
                 write_set_with_index_for_shard,
                 vec![],
             ))
diff --git a/execution/block-partitioner/src/types.rs b/execution/block-partitioner/src/types.rs
index 56b6a40c31899..46af531c134c1 100644
--- a/execution/block-partitioner/src/types.rs
+++ b/execution/block-partitioner/src/types.rs
@@ -1,40 +1,140 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
-use aptos_types::transaction::analyzed_transaction::AnalyzedTransaction;
-use std::collections::HashSet;
+use aptos_types::transaction::analyzed_transaction::{AnalyzedTransaction, StorageLocation};
+use std::collections::HashMap;
 
 pub type ShardId = usize;
 pub type TxnIndex = usize;
 
+#[derive(Debug, Clone, Eq, Hash, PartialEq)]
+pub struct TxnIdxWithShardId {
+    pub txn_index: TxnIndex,
+    pub shard_id: ShardId,
+}
+
+impl TxnIdxWithShardId {
+    pub fn new(txn_index: TxnIndex, shard_id: ShardId) -> Self {
+        Self {
+            shard_id,
+            txn_index,
+        }
+    }
+}
+
+#[derive(Debug, Default, Clone)]
+/// Denotes a set of cross shard edges, which contains the set (required or dependent) transaction
+/// indices and the relevant storage locations that are conflicting.
+pub struct CrossShardEdges {
+    edges: HashMap>,
+}
+
+impl CrossShardEdges {
+    pub fn new(txn_idx: TxnIdxWithShardId, storage_locations: Vec) -> Self {
+        let mut edges = HashMap::new();
+        edges.insert(txn_idx, storage_locations);
+        Self { edges }
+    }
+
+    pub fn add_edge(
+        &mut self,
+        txn_idx: TxnIdxWithShardId,
+        storage_locations: Vec,
+    ) {
+        self.edges
+            .entry(txn_idx)
+            .or_insert_with(Vec::new)
+            .extend(storage_locations.into_iter());
+    }
+
+    pub fn iter(&self) -> impl Iterator)> {
+        self.edges.iter()
+    }
+
+    pub fn len(&self) -> usize {
+        self.edges.len()
+    }
+
+    pub fn contains_idx(&self, txn_idx: &TxnIdxWithShardId) -> bool {
+        self.edges.contains_key(txn_idx)
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.edges.is_empty()
+    }
+}
+
+impl IntoIterator for CrossShardEdges {
+    type IntoIter = std::collections::hash_map::IntoIter>;
+    type Item = (TxnIdxWithShardId, Vec);
+
+    fn into_iter(self) -> Self::IntoIter {
+        self.edges.into_iter()
+    }
+}
+
 #[derive(Default, Debug, Clone)]
 /// Represents the dependencies of a transaction on other transactions across shards. Two types
 /// of dependencies are supported:
-/// 1. `depends_on`: The transaction depends on the execution of the transactions in the set. In this
+/// 1. `required_edges`: The transaction depends on the execution of the transactions in the set. In this
 /// case, the transaction can only be executed after the transactions in the set have been executed.
-/// 2. `dependents`: The transactions in the set depend on the execution of the transaction. In this
+/// 2. `dependent_edges`: The transactions in the set depend on the execution of the transaction. In this
 /// case, the transactions in the set can only be executed after the transaction has been executed.
+/// Dependent edge is a reverse of required edge, for example if txn 20 in shard 2 requires txn 10 in shard 1,
+/// then txn 10 in shard 1 will have a dependent edge to txn 20 in shard 2.
 pub struct CrossShardDependencies {
-    depends_on: HashSet,
-    // TODO (skedia) add support for this.
-    _dependents: HashSet,
+    required_edges: CrossShardEdges,
+    dependent_edges: CrossShardEdges,
 }
 
 impl CrossShardDependencies {
-    pub fn len(&self) -> usize {
-        self.depends_on.len()
+    pub fn num_required_edges(&self) -> usize {
+        self.required_edges.len()
     }
 
-    pub fn is_empty(&self) -> bool {
-        self.depends_on.is_empty()
+    pub fn required_edges_iter(
+        &self,
+    ) -> impl Iterator)> {
+        self.required_edges.iter()
+    }
+
+    pub fn has_required_txn(&self, txn_idx: TxnIdxWithShardId) -> bool {
+        self.required_edges.contains_idx(&txn_idx)
+    }
+
+    pub fn get_required_edge_for(
+        &self,
+        txn_idx: TxnIdxWithShardId,
+    ) -> Option<&Vec> {
+        self.required_edges.edges.get(&txn_idx)
+    }
+
+    pub fn get_dependent_edge_for(
+        &self,
+        txn_idx: TxnIdxWithShardId,
+    ) -> Option<&Vec> {
+        self.dependent_edges.edges.get(&txn_idx)
     }
 
-    pub fn is_depends_on(&self, txn_index: TxnIndex) -> bool {
-        self.depends_on.contains(&txn_index)
+    pub fn has_dependent_txn(&self, txn_ids: TxnIdxWithShardId) -> bool {
+        self.dependent_edges.contains_idx(&txn_ids)
     }
 
-    pub fn add_depends_on_txn(&mut self, txn_index: TxnIndex) {
-        self.depends_on.insert(txn_index);
+    pub fn add_required_edge(
+        &mut self,
+        txn_idx: TxnIdxWithShardId,
+        storage_location: StorageLocation,
+    ) {
+        self.required_edges
+            .add_edge(txn_idx, vec![storage_location]);
+    }
+
+    pub fn add_dependent_edge(
+        &mut self,
+        txn_idx: TxnIdxWithShardId,
+        storage_locations: Vec,
+    ) {
+        self.dependent_edges.add_edge(txn_idx, storage_locations);
     }
 }
 
@@ -42,7 +142,7 @@ impl CrossShardDependencies {
 /// A contiguous chunk of transactions (along with their dependencies) in a block.
 ///
 /// Each `SubBlock` represents a sequential section of transactions within a block.
-/// The chunk includes the index of the first transaction relative to the block and a vector
+/// The sub block includes the index of the first transaction relative to the block and a vector
 /// of `TransactionWithDependencies` representing the transactions included in the chunk.
 ///
 /// Illustration:
@@ -70,7 +170,7 @@ impl SubBlock {
         }
     }
 
-    pub fn len(&self) -> usize {
+    pub fn num_txns(&self) -> usize {
         self.transactions.len()
     }
 
@@ -78,9 +178,83 @@ impl SubBlock {
         self.transactions.is_empty()
     }
 
+    pub fn end_index(&self) -> TxnIndex {
+        self.start_index + self.num_txns()
+    }
+
     pub fn transactions_with_deps(&self) -> &Vec {
         &self.transactions
     }
+
+    pub fn add_dependent_edge(
+        &mut self,
+        source_index: TxnIndex,
+        txn_idx: TxnIdxWithShardId,
+        storage_locations: Vec,
+    ) {
+        let source_txn = self
+            .transactions
+            .get_mut(source_index - self.start_index)
+            .unwrap();
+        source_txn.add_dependent_edge(txn_idx, storage_locations);
+    }
+
+    pub fn iter(&self) -> impl Iterator {
+        self.transactions.iter()
+    }
+}
+
+// A set of sub blocks assigned to a shard.
+#[derive(Default)]
+pub struct SubBlocksForShard {
+    pub shard_id: ShardId,
+    pub sub_blocks: Vec,
+}
+
+impl SubBlocksForShard {
+    pub fn empty(shard_id: ShardId) -> Self {
+        Self {
+            shard_id,
+            sub_blocks: Vec::new(),
+        }
+    }
+
+    pub fn add_sub_block(&mut self, sub_block: SubBlock) {
+        self.sub_blocks.push(sub_block);
+    }
+
+    pub fn num_txns(&self) -> usize {
+        self.sub_blocks
+            .iter()
+            .map(|sub_block| sub_block.num_txns())
+            .sum()
+    }
+
+    pub fn num_sub_blocks(&self) -> usize {
+        self.sub_blocks.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.sub_blocks.is_empty()
+    }
+
+    pub fn iter(&self) -> impl Iterator {
+        self.sub_blocks
+            .iter()
+            .flat_map(|sub_block| sub_block.iter())
+    }
+
+    pub fn sub_block_iter(&self) -> impl Iterator {
+        self.sub_blocks.iter()
+    }
+
+    pub fn get_sub_block(&self, round: usize) -> Option<&SubBlock> {
+        self.sub_blocks.get(round)
+    }
+
+    pub fn get_sub_block_mut(&mut self, round: usize) -> Option<&mut SubBlock> {
+        self.sub_blocks.get_mut(round)
+    }
 }
 
 #[derive(Debug, Clone)]
@@ -106,4 +280,13 @@ impl TransactionWithDependencies {
     pub fn cross_shard_dependencies(&self) -> &CrossShardDependencies {
         &self.cross_shard_dependencies
     }
+
+    pub fn add_dependent_edge(
+        &mut self,
+        txn_idx: TxnIdxWithShardId,
+        storage_locations: Vec,
+    ) {
+        self.cross_shard_dependencies
+            .add_dependent_edge(txn_idx, storage_locations);
+    }
 }
diff --git a/execution/executor-types/src/lib.rs b/execution/executor-types/src/lib.rs
index 4fd1364d45b9c..829987578f8c8 100644
--- a/execution/executor-types/src/lib.rs
+++ b/execution/executor-types/src/lib.rs
@@ -156,9 +156,10 @@ impl ExecutableTransactions {
     pub fn num_transactions(&self) -> usize {
         match self {
             ExecutableTransactions::Unsharded(transactions) => transactions.len(),
-            ExecutableTransactions::Sharded(sub_blocks) => {
-                sub_blocks.iter().map(|sub_block| sub_block.len()).sum()
-            },
+            ExecutableTransactions::Sharded(sub_blocks) => sub_blocks
+                .iter()
+                .map(|sub_block| sub_block.num_txns())
+                .sum(),
         }
     }
 }
diff --git a/types/src/transaction/analyzed_transaction.rs b/types/src/transaction/analyzed_transaction.rs
index e5f402a12171e..b77952a2dc335 100644
--- a/types/src/transaction/analyzed_transaction.rs
+++ b/types/src/transaction/analyzed_transaction.rs
@@ -120,14 +120,14 @@ impl AnalyzedTransaction {
         )
     }
 
-    fn account_resource_location(address: AccountAddress) -> StorageLocation {
+    pub fn account_resource_location(address: AccountAddress) -> StorageLocation {
         StorageLocation::Specific(StateKey::access_path(AccessPath::new(
             address,
             AccountResource::struct_tag().access_vector(),
         )))
     }
 
-    fn coin_store_location(address: AccountAddress) -> StorageLocation {
+    pub fn coin_store_location(address: AccountAddress) -> StorageLocation {
         StorageLocation::Specific(StateKey::access_path(AccessPath::new(
             address,
             CoinStoreResource::struct_tag().access_vector(),

From 300856091c19d2c649b8423342b9a36769a2f05f Mon Sep 17 00:00:00 2001
From: zhoujunma 
Date: Tue, 13 Jun 2023 10:10:27 -0700
Subject: [PATCH 147/200] sparse-merkle-tree bench update (#8613)

* jemalloc for smt bench

* update

* tweak
---
 Cargo.lock                                  |  1 +
 storage/scratchpad/Cargo.toml               |  1 +
 storage/scratchpad/benches/sparse_merkle.rs | 28 +++++++++------------
 3 files changed, 14 insertions(+), 16 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index c81d6ccd5edce..58d9402234a96 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2780,6 +2780,7 @@ dependencies = [
  "bitvec 0.19.6",
  "criterion",
  "itertools",
+ "jemallocator",
  "once_cell",
  "proptest",
  "rand 0.7.3",
diff --git a/storage/scratchpad/Cargo.toml b/storage/scratchpad/Cargo.toml
index 80146f14dd19e..92b70b11fd9cf 100644
--- a/storage/scratchpad/Cargo.toml
+++ b/storage/scratchpad/Cargo.toml
@@ -20,6 +20,7 @@ aptos-types = { workspace = true }
 bitvec = { workspace = true }
 criterion = { workspace = true, optional = true }
 itertools = { workspace = true }
+jemallocator = { workspace = true }
 once_cell = { workspace = true }
 proptest = { workspace = true, optional = true }
 rayon = { workspace = true }
diff --git a/storage/scratchpad/benches/sparse_merkle.rs b/storage/scratchpad/benches/sparse_merkle.rs
index f39797f429595..f28f50c8af10a 100644
--- a/storage/scratchpad/benches/sparse_merkle.rs
+++ b/storage/scratchpad/benches/sparse_merkle.rs
@@ -13,22 +13,19 @@ use itertools::zip_eq;
 use rand::{distributions::Standard, prelude::StdRng, seq::IteratorRandom, Rng, SeedableRng};
 use std::collections::HashSet;
 
+#[cfg(unix)]
+#[global_allocator]
+static ALLOC: jemallocator::Jemalloc = jemallocator::Jemalloc;
+
 struct Block {
     smt: SparseMerkleTree,
-    updates: Vec)>>,
+    updates: Vec<(HashValue, Option)>,
     proof_reader: ProofReader,
 }
 
 impl Block {
-    fn updates(&self) -> Vec)>> {
-        self.updates
-            .iter()
-            .map(|small_batch| small_batch.iter().map(|(k, v)| (*k, v.as_ref())).collect())
-            .collect()
-    }
-
-    fn updates_flat_batch(&self) -> Vec<(HashValue, Option<&StateValue>)> {
-        self.updates().iter().flatten().cloned().collect()
+    fn updates(&self) -> Vec<(HashValue, Option<&StateValue>)> {
+        self.updates.iter().map(|(k, v)| (*k, v.as_ref())).collect()
     }
 }
 
@@ -43,7 +40,7 @@ impl Group {
 
         for block in &self.blocks {
             let block_size = block.updates.len();
-            let one_large_batch = block.updates_flat_batch();
+            let one_large_batch = block.updates();
 
             group.throughput(Throughput::Elements(block_size as u64));
 
@@ -141,7 +138,7 @@ impl Benches {
                     Block {
                         smt: base_block
                             .smt
-                            .batch_update(base_block.updates_flat_batch(), &base_block.proof_reader)
+                            .batch_update(base_block.updates(), &base_block.proof_reader)
                             .unwrap(),
                         updates,
                         proof_reader,
@@ -167,8 +164,8 @@ impl Benches {
         rng: &mut StdRng,
         keys: &[HashValue],
         block_size: usize,
-    ) -> Vec)>> {
-        std::iter::repeat_with(|| vec![Self::gen_update(rng, keys), Self::gen_update(rng, keys)])
+    ) -> Vec<(HashValue, Option)> {
+        std::iter::repeat_with(|| Self::gen_update(rng, keys))
             .take(block_size)
             .collect()
     }
@@ -188,11 +185,10 @@ impl Benches {
 
     fn gen_proof_reader(
         naive_smt: &mut NaiveSmt,
-        updates: &[Vec<(HashValue, Option)>],
+        updates: &[(HashValue, Option)],
     ) -> ProofReader {
         let proofs = updates
             .iter()
-            .flatten()
             .map(|(key, _)| (*key, naive_smt.get_proof(key)))
             .collect();
         ProofReader::new(proofs)

From 1dda750308934b7bebd7f46d157f2ea4850ba379 Mon Sep 17 00:00:00 2001
From: Josh Lind 
Date: Mon, 12 Jun 2023 13:11:33 -0400
Subject: [PATCH 148/200] [Storage Service] Fix flaky tests.

---
 state-sync/storage-service/server/src/lib.rs  |  8 ++++++++
 .../src/tests/new_transaction_outputs.rs      | 16 ++++++++++++++++
 .../server/src/tests/new_transactions.rs      | 16 ++++++++++++++++
 .../src/tests/new_transactions_or_outputs.rs  | 16 ++++++++++++++++
 .../storage-service/server/src/tests/utils.rs | 19 +++++++++++++++++++
 5 files changed, 75 insertions(+)

diff --git a/state-sync/storage-service/server/src/lib.rs b/state-sync/storage-service/server/src/lib.rs
index 2294347545a32..a1b971d64346a 100644
--- a/state-sync/storage-service/server/src/lib.rs
+++ b/state-sync/storage-service/server/src/lib.rs
@@ -265,6 +265,14 @@ impl StorageServiceServer {
     pub(crate) fn get_request_moderator(&self) -> Arc {
         self.request_moderator.clone()
     }
+
+    #[cfg(test)]
+    /// Returns a copy of the active optimistic fetches for test purposes
+    pub(crate) fn get_optimistic_fetches(
+        &self,
+    ) -> Arc>> {
+        self.optimistic_fetches.clone()
+    }
 }
 
 /// Refreshes the cached storage server summary
diff --git a/state-sync/storage-service/server/src/tests/new_transaction_outputs.rs b/state-sync/storage-service/server/src/tests/new_transaction_outputs.rs
index 63e41b4c95e33..188a3375b204d 100644
--- a/state-sync/storage-service/server/src/tests/new_transaction_outputs.rs
+++ b/state-sync/storage-service/server/src/tests/new_transaction_outputs.rs
@@ -48,12 +48,16 @@ async fn test_get_new_transaction_outputs() {
 
         // Create the storage client and server
         let (mut mock_client, service, mock_time, _) = MockClient::new(Some(db_reader), None);
+        let active_optimistic_fetches = service.get_optimistic_fetches();
         tokio::spawn(service.start());
 
         // Send a request to optimistically fetch new transaction outputs
         let mut response_receiver =
             get_new_outputs_with_proof(&mut mock_client, peer_version, highest_epoch).await;
 
+        // Wait until the optimistic fetch is active
+        utils::wait_for_active_optimistic_fetches(active_optimistic_fetches.clone(), 1).await;
+
         // Verify no optimistic fetch response has been received yet
         assert_none!(response_receiver.try_recv().unwrap());
 
@@ -115,6 +119,7 @@ async fn test_get_new_transaction_outputs_different_networks() {
 
         // Create the storage client and server
         let (mut mock_client, service, mock_time, _) = MockClient::new(Some(db_reader), None);
+        let active_optimistic_fetches = service.get_optimistic_fetches();
         tokio::spawn(service.start());
 
         // Send a request to optimistically fetch new transaction outputs for peer 1
@@ -138,6 +143,9 @@ async fn test_get_new_transaction_outputs_different_networks() {
         )
         .await;
 
+        // Wait until the optimistic fetches are active
+        utils::wait_for_active_optimistic_fetches(active_optimistic_fetches.clone(), 2).await;
+
         // Verify no optimistic fetch response has been received yet
         assert_none!(response_receiver_1.try_recv().unwrap());
         assert_none!(response_receiver_2.try_recv().unwrap());
@@ -206,12 +214,16 @@ async fn test_get_new_transaction_outputs_epoch_change() {
 
     // Create the storage client and server
     let (mut mock_client, service, mock_time, _) = MockClient::new(Some(db_reader), None);
+    let active_optimistic_fetches = service.get_optimistic_fetches();
     tokio::spawn(service.start());
 
     // Send a request to optimistically fetch new transaction outputs
     let response_receiver =
         get_new_outputs_with_proof(&mut mock_client, peer_version, peer_epoch).await;
 
+    // Wait until the optimistic fetch is active
+    utils::wait_for_active_optimistic_fetches(active_optimistic_fetches.clone(), 1).await;
+
     // Elapse enough time to force the optimistic fetch thread to work
     utils::wait_for_optimistic_fetch_service_to_refresh(&mut mock_client, &mock_time).await;
 
@@ -255,12 +267,16 @@ async fn test_get_new_transaction_outputs_max_chunk() {
 
     // Create the storage client and server
     let (mut mock_client, service, mock_time, _) = MockClient::new(Some(db_reader), None);
+    let active_optimistic_fetches = service.get_optimistic_fetches();
     tokio::spawn(service.start());
 
     // Send a request to optimistically fetch new transaction outputs
     let response_receiver =
         get_new_outputs_with_proof(&mut mock_client, peer_version, highest_epoch).await;
 
+    // Wait until the optimistic fetch is active
+    utils::wait_for_active_optimistic_fetches(active_optimistic_fetches.clone(), 1).await;
+
     // Elapse enough time to force the optimistic fetch thread to work
     utils::wait_for_optimistic_fetch_service_to_refresh(&mut mock_client, &mock_time).await;
 
diff --git a/state-sync/storage-service/server/src/tests/new_transactions.rs b/state-sync/storage-service/server/src/tests/new_transactions.rs
index 6002f4aad3121..42cd8556ee0d9 100644
--- a/state-sync/storage-service/server/src/tests/new_transactions.rs
+++ b/state-sync/storage-service/server/src/tests/new_transactions.rs
@@ -54,6 +54,7 @@ async fn test_get_new_transactions() {
 
             // Create the storage client and server
             let (mut mock_client, service, mock_time, _) = MockClient::new(Some(db_reader), None);
+            let active_optimistic_fetches = service.get_optimistic_fetches();
             tokio::spawn(service.start());
 
             // Send a request to optimistically fetch new transactions
@@ -65,6 +66,9 @@ async fn test_get_new_transactions() {
             )
             .await;
 
+            // Wait until the optimistic fetch is active
+            utils::wait_for_active_optimistic_fetches(active_optimistic_fetches.clone(), 1).await;
+
             // Verify no optimistic fetch response has been received yet
             assert_none!(response_receiver.try_recv().unwrap());
 
@@ -135,6 +139,7 @@ async fn test_get_new_transactions_different_networks() {
 
             // Create the storage client and server
             let (mut mock_client, service, mock_time, _) = MockClient::new(Some(db_reader), None);
+            let active_optimistic_fetches = service.get_optimistic_fetches();
             tokio::spawn(service.start());
 
             // Send a request to optimistically fetch new transactions for peer 1
@@ -160,6 +165,9 @@ async fn test_get_new_transactions_different_networks() {
             )
             .await;
 
+            // Wait until the optimistic fetches are active
+            utils::wait_for_active_optimistic_fetches(active_optimistic_fetches.clone(), 2).await;
+
             // Verify no optimistic fetch response has been received yet
             assert_none!(response_receiver_1.try_recv().unwrap());
             assert_none!(response_receiver_2.try_recv().unwrap());
@@ -233,6 +241,7 @@ async fn test_get_new_transactions_epoch_change() {
 
         // Create the storage client and server
         let (mut mock_client, service, mock_time, _) = MockClient::new(Some(db_reader), None);
+        let active_optimistic_fetches = service.get_optimistic_fetches();
         tokio::spawn(service.start());
 
         // Send a request to optimistically fetch new transactions
@@ -244,6 +253,9 @@ async fn test_get_new_transactions_epoch_change() {
         )
         .await;
 
+        // Wait until the optimistic fetch is active
+        utils::wait_for_active_optimistic_fetches(active_optimistic_fetches.clone(), 1).await;
+
         // Elapse enough time to force the optimistic fetch thread to work
         utils::wait_for_optimistic_fetch_service_to_refresh(&mut mock_client, &mock_time).await;
 
@@ -292,6 +304,7 @@ async fn test_get_new_transactions_max_chunk() {
 
         // Create the storage client and server
         let (mut mock_client, service, mock_time, _) = MockClient::new(Some(db_reader), None);
+        let active_optimistic_fetches = service.get_optimistic_fetches();
         tokio::spawn(service.start());
 
         // Send a request to optimistically fetch new transactions
@@ -303,6 +316,9 @@ async fn test_get_new_transactions_max_chunk() {
         )
         .await;
 
+        // Wait until the optimistic fetch is active
+        utils::wait_for_active_optimistic_fetches(active_optimistic_fetches.clone(), 1).await;
+
         // Elapse enough time to force the optimistic fetch thread to work
         utils::wait_for_optimistic_fetch_service_to_refresh(&mut mock_client, &mock_time).await;
 
diff --git a/state-sync/storage-service/server/src/tests/new_transactions_or_outputs.rs b/state-sync/storage-service/server/src/tests/new_transactions_or_outputs.rs
index d6008ee542dca..e6b4f33224b06 100644
--- a/state-sync/storage-service/server/src/tests/new_transactions_or_outputs.rs
+++ b/state-sync/storage-service/server/src/tests/new_transactions_or_outputs.rs
@@ -76,6 +76,7 @@ async fn test_get_new_transactions_or_outputs() {
             );
             let (mut mock_client, service, mock_time, _) =
                 MockClient::new(Some(db_reader), Some(storage_config));
+            let active_optimistic_fetches = service.get_optimistic_fetches();
             tokio::spawn(service.start());
 
             // Send a request to optimistically fetch new transactions or outputs
@@ -88,6 +89,9 @@ async fn test_get_new_transactions_or_outputs() {
             )
             .await;
 
+            // Wait until the optimistic fetch is active
+            utils::wait_for_active_optimistic_fetches(active_optimistic_fetches.clone(), 1).await;
+
             // Verify no optimistic fetch response has been received yet
             assert_none!(response_receiver.try_recv().unwrap());
 
@@ -196,6 +200,7 @@ async fn test_get_new_transactions_or_outputs_different_network() {
             );
             let (mut mock_client, service, mock_time, _) =
                 MockClient::new(Some(db_reader), Some(storage_config));
+            let active_optimistic_fetches = service.get_optimistic_fetches();
             tokio::spawn(service.start());
 
             // Send a request to optimistically fetch new transactions or outputs for peer 1
@@ -223,6 +228,9 @@ async fn test_get_new_transactions_or_outputs_different_network() {
             )
             .await;
 
+            // Wait until the optimistic fetches are active
+            utils::wait_for_active_optimistic_fetches(active_optimistic_fetches.clone(), 2).await;
+
             // Verify no optimistic fetch response has been received yet
             assert_none!(response_receiver_1.try_recv().unwrap());
             assert_none!(response_receiver_2.try_recv().unwrap());
@@ -337,6 +345,7 @@ async fn test_get_new_transactions_or_outputs_epoch_change() {
         );
         let (mut mock_client, service, mock_time, _) =
             MockClient::new(Some(db_reader), Some(storage_config));
+        let active_optimistic_fetches = service.get_optimistic_fetches();
         tokio::spawn(service.start());
 
         // Send a request to optimistically fetch new transaction outputs
@@ -349,6 +358,9 @@ async fn test_get_new_transactions_or_outputs_epoch_change() {
         )
         .await;
 
+        // Wait until the optimistic fetch is active
+        utils::wait_for_active_optimistic_fetches(active_optimistic_fetches.clone(), 1).await;
+
         // Elapse enough time to force the optimistic fetch thread to work
         utils::wait_for_optimistic_fetch_service_to_refresh(&mut mock_client, &mock_time).await;
 
@@ -432,6 +444,7 @@ async fn test_get_new_transactions_or_outputs_max_chunk() {
         );
         let (mut mock_client, service, mock_time, _) =
             MockClient::new(Some(db_reader), Some(storage_config));
+        let active_optimistic_fetches = service.get_optimistic_fetches();
         tokio::spawn(service.start());
 
         // Send a request to optimistically fetch new transaction outputs
@@ -444,6 +457,9 @@ async fn test_get_new_transactions_or_outputs_max_chunk() {
         )
         .await;
 
+        // Wait until the optimistic fetch is active
+        utils::wait_for_active_optimistic_fetches(active_optimistic_fetches.clone(), 1).await;
+
         // Elapse enough time to force the optimistic fetch thread to work
         utils::wait_for_optimistic_fetch_service_to_refresh(&mut mock_client, &mock_time).await;
 
diff --git a/state-sync/storage-service/server/src/tests/utils.rs b/state-sync/storage-service/server/src/tests/utils.rs
index f1f42fe986e05..95fdb560fb335 100644
--- a/state-sync/storage-service/server/src/tests/utils.rs
+++ b/state-sync/storage-service/server/src/tests/utils.rs
@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::{
+    optimistic_fetch::OptimisticFetchRequest,
     storage::StorageReader,
     tests::mock::{MockClient, MockDatabaseReader},
     StorageServiceServer,
@@ -11,6 +12,7 @@ use aptos_config::{
     network_id::{NetworkId, PeerNetworkId},
 };
 use aptos_crypto::{ed25519::Ed25519PrivateKey, HashValue, PrivateKey, SigningKey, Uniform};
+use aptos_infallible::Mutex;
 use aptos_storage_service_types::{
     requests::{
         DataRequest, StateValuesWithProofRequest, StorageServiceRequest,
@@ -39,6 +41,7 @@ use aptos_types::{
 };
 use mockall::predicate::eq;
 use rand::Rng;
+use std::{collections::HashMap, sync::Arc, time::Duration};
 
 /// Advances the given timer by the amount of time it takes to refresh storage
 pub async fn advance_storage_refresh_time(mock_time: &MockTimeService) {
@@ -429,3 +432,19 @@ pub async fn wait_for_optimistic_fetch_service_to_refresh(
     // Elapse enough time to force the optimistic fetch thread to work
     advance_storage_refresh_time(mock_time).await;
 }
+
+/// Waits for the specified number of optimistic fetches to be active
+pub async fn wait_for_active_optimistic_fetches(
+    active_optimistic_fetches: Arc>>,
+    expected_num_active_fetches: usize,
+) {
+    loop {
+        let num_active_fetches = active_optimistic_fetches.lock().len();
+        if num_active_fetches == expected_num_active_fetches {
+            return; // We found the expected number of active fetches
+        }
+
+        // Sleep for a while
+        tokio::time::sleep(Duration::from_millis(100)).await;
+    }
+}

From 2bf6e6a59282d44603bd4891ae6678fb5bf9112c Mon Sep 17 00:00:00 2001
From: "cryptomolot.apt" <88001005+cryptomolot@users.noreply.github.com>
Date: Tue, 13 Jun 2023 20:42:49 +0300
Subject: [PATCH 149/200] Update CONTRIBUTING.md (#8620)

---
 CONTRIBUTING.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9497c341472b4..db412e537ccbf 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -5,7 +5,7 @@ title: Contributing to Aptos Core
 
 # Contributing
 
-Our goal is to make contributing to Aptos Core easy and transparent. See [Aptos Community](https://aptos.dev/community/help-index) for full details. This page describes [our development process](#our-development-process).
+Our goal is to make contributing to Aptos Core easy and transparent. See [Aptos Community](https://aptos.dev/community) for full details. This page describes [our development process](#our-development-process).
 
 ## Aptos Core
 

From 763a8ad81f6e8d6479badfc676be5cba3a8599b4 Mon Sep 17 00:00:00 2001
From: Aaron Gao 
Date: Wed, 24 May 2023 16:28:31 -0700
Subject: [PATCH 150/200] [move-example] refactor fungible asset examples

---
 .../move-examples/fungible_asset/Move.toml    |   2 +-
 .../fungible_asset/sources/coin_example.move  |  50 ++-
 .../sources/managed_fungible_asset.move       | 392 ++++++++++++++----
 ...ged_coin.move => simple_managed_coin.move} |  12 +-
 4 files changed, 341 insertions(+), 115 deletions(-)
 rename aptos-move/move-examples/fungible_asset/sources/{managed_coin.move => simple_managed_coin.move} (94%)

diff --git a/aptos-move/move-examples/fungible_asset/Move.toml b/aptos-move/move-examples/fungible_asset/Move.toml
index 50d6e3404a053..13e36a1b8502e 100644
--- a/aptos-move/move-examples/fungible_asset/Move.toml
+++ b/aptos-move/move-examples/fungible_asset/Move.toml
@@ -4,7 +4,7 @@ version = "0.0.0"
 
 [addresses]
 aptos_framework = "0x1"
-fungible_asset_extension = "_"
+example_addr = "_"
 
 [dependencies]
 AptosFramework = { local = "../../framework/aptos-framework" }
diff --git a/aptos-move/move-examples/fungible_asset/sources/coin_example.move b/aptos-move/move-examples/fungible_asset/sources/coin_example.move
index fbd67f9e7dc56..1128e6851a5a4 100644
--- a/aptos-move/move-examples/fungible_asset/sources/coin_example.move
+++ b/aptos-move/move-examples/fungible_asset/sources/coin_example.move
@@ -1,9 +1,10 @@
-/// A coin example using managed_fungible_asset to create a fungible "coin".
-module fungible_asset_extension::coin_example {
+/// A coin example using managed_fungible_asset to create a fungible "coin" and helper functions to only interact with
+/// primary fungible stores.
+module example_addr::coin_example {
     use aptos_framework::object;
     use aptos_framework::fungible_asset::{Metadata, FungibleAsset};
     use aptos_framework::object::Object;
-    use fungible_asset_extension::managed_fungible_asset;
+    use example_addr::managed_fungible_asset;
     use std::string::utf8;
 
     const ASSET_SYMBOL: vector = b"YOLO";
@@ -19,55 +20,70 @@ module fungible_asset_extension::coin_example {
             8, /* decimals */
             utf8(b"http://example.com/favicon.ico"), /* icon */
             utf8(b"http://example.com"), /* project */
+            vector[true, true, true], /* mint_ref, transfer_ref, burn_ref */
         );
     }
 
     #[view]
     /// Return the address of the metadata that's created when this module is deployed.
     public fun get_metadata(): Object {
-        let metadata_address = object::create_object_address(&@fungible_asset_extension, ASSET_SYMBOL);
+        let metadata_address = object::create_object_address(&@example_addr, ASSET_SYMBOL);
         object::address_to_object(metadata_address)
     }
 
     /// Mint as the owner of metadata object.
-    public entry fun mint(admin: &signer, amount: u64, to: address) {
-        managed_fungible_asset::mint(admin, get_metadata(), amount, to);
+    public entry fun mint(admin: &signer, to: address, amount: u64) {
+        managed_fungible_asset::mint_to_primary_stores(admin, get_metadata(), vector[to], vector[amount]);
     }
 
     /// Transfer as the owner of metadata object ignoring `frozen` field.
     public entry fun transfer(admin: &signer, from: address, to: address, amount: u64) {
-        managed_fungible_asset::transfer(admin, get_metadata(), from, to, amount);
+        managed_fungible_asset::transfer_between_primary_stores(
+            admin,
+            get_metadata(),
+            vector[from],
+            vector[to],
+            vector[amount]
+        );
     }
 
     /// Burn fungible assets as the owner of metadata object.
     public entry fun burn(admin: &signer, from: address, amount: u64) {
-        managed_fungible_asset::burn(admin, get_metadata(), from, amount);
+        managed_fungible_asset::burn_from_primary_stores(admin, get_metadata(), vector[from], vector[amount]);
     }
 
     /// Freeze an account so it cannot transfer or receive fungible assets.
     public entry fun freeze_account(admin: &signer, account: address) {
-        managed_fungible_asset::freeze_account(admin, get_metadata(), account);
+        managed_fungible_asset::set_primary_stores_frozen_status(admin, get_metadata(), vector[account], true);
     }
 
     /// Unfreeze an account so it can transfer or receive fungible assets.
     public entry fun unfreeze_account(admin: &signer, account: address) {
-        managed_fungible_asset::unfreeze_account(admin, get_metadata(), account);
+        managed_fungible_asset::set_primary_stores_frozen_status(admin, get_metadata(), vector[account], false);
     }
 
     /// Withdraw as the owner of metadata object ignoring `frozen` field.
-    public fun withdraw(admin: &signer, amount: u64, from: address): FungibleAsset {
-        managed_fungible_asset::withdraw(admin, get_metadata(), amount, from)
+    public fun withdraw(admin: &signer, from: address, amount: u64): FungibleAsset {
+        managed_fungible_asset::withdraw_from_primary_stores(admin, get_metadata(), vector[from], vector[amount])
     }
 
     /// Deposit as the owner of metadata object ignoring `frozen` field.
-    public fun deposit(admin: &signer, to: address, fa: FungibleAsset) {
-        managed_fungible_asset::deposit(admin, get_metadata(), to, fa);
+    public fun deposit(admin: &signer, fa: FungibleAsset, to: address) {
+        let amount = fungible_asset::amount(&fa);
+        managed_fungible_asset::deposit_to_primary_stores(
+            admin,
+            &mut fa,
+            vector[to],
+            vector[amount]
+        );
+        fungible_asset::destroy_zero(fa);
     }
 
     #[test_only]
     use aptos_framework::primary_fungible_store;
     #[test_only]
     use std::signer;
+    use aptos_framework::fungible_asset;
 
     #[test(creator = @0xcafe)]
     fun test_basic_flow(creator: &signer) {
@@ -75,7 +91,7 @@ module fungible_asset_extension::coin_example {
         let creator_address = signer::address_of(creator);
         let aaron_address = @0xface;
 
-        mint(creator, 100, creator_address);
+        mint(creator, creator_address, 100);
         let metadata = get_metadata();
         assert!(primary_fungible_store::balance(creator_address, metadata) == 100, 4);
         freeze_account(creator, creator_address);
@@ -89,10 +105,10 @@ module fungible_asset_extension::coin_example {
     }
 
     #[test(creator = @0xcafe, aaron = @0xface)]
-    #[expected_failure(abort_code = 0x50001, location = fungible_asset_extension::managed_fungible_asset)]
+    #[expected_failure(abort_code = 0x50001, location = example_addr::managed_fungible_asset)]
     fun test_permission_denied(creator: &signer, aaron: &signer) {
         init_module(creator);
         let creator_address = signer::address_of(creator);
-        mint(aaron, 100, creator_address);
+        mint(aaron, creator_address, 100);
     }
 }
diff --git a/aptos-move/move-examples/fungible_asset/sources/managed_fungible_asset.move b/aptos-move/move-examples/fungible_asset/sources/managed_fungible_asset.move
index 685e531c80478..8848fa35f1362 100644
--- a/aptos-move/move-examples/fungible_asset/sources/managed_fungible_asset.move
+++ b/aptos-move/move-examples/fungible_asset/sources/managed_fungible_asset.move
@@ -2,11 +2,13 @@
 /// mint, transfer and burn fungible assets.
 ///
 /// The functionalities offered by this module are:
-/// 1. Mint fungible assets as the owner of metadata object.
-/// 2. Transfer fungible assets as the owner of metadata object ignoring `frozen` field.
-/// 3. Burn fungible assets as the owner of metadata object.
-module fungible_asset_extension::managed_fungible_asset {
-    use aptos_framework::fungible_asset::{Self, MintRef, TransferRef, BurnRef, FungibleAsset, Metadata};
+/// 1. Mint fungible assets to fungible stores as the owner of metadata object.
+/// 2. Transfer fungible assets as the owner of metadata object ignoring `frozen` field between fungible stores.
+/// 3. Burn fungible assets from fungible stores as the owner of metadata object.
+/// 4. Withdraw the merged fungible assets from fungible stores as the owner of metadata object.
+/// 5. Deposit fungible assets to fungible stores.
+module example_addr::managed_fungible_asset {
+    use aptos_framework::fungible_asset::{Self, MintRef, TransferRef, BurnRef, Metadata, FungibleStore, FungibleAsset};
     use aptos_framework::object::{Self, Object, ConstructorRef};
     use aptos_framework::primary_fungible_store;
     use std::error;
@@ -15,17 +17,27 @@ module fungible_asset_extension::managed_fungible_asset {
     use std::option;
 
     /// Only fungible asset metadata owner can make changes.
-    const ENOT_OWNER: u64 = 1;
+    const ERR_NOT_OWNER: u64 = 1;
+    /// The length of ref_flags is not 3.
+    const ERR_INVALID_REF_FLAGS_LENGTH: u64 = 2;
+    /// The lengths of two vector do not equal.
+    const ERR_VECTORS_LENGTH_MISMATCH: u64 = 3;
+    /// MintRef error.
+    const ERR_MINT_REF: u64 = 4;
+    /// TransferRef error.
+    const ERR_TRANSFER_REF: u64 = 5;
+    /// BurnRef error.
+    const ERR_BURN_REF: u64 = 6;
 
     #[resource_group_member(group = aptos_framework::object::ObjectGroup)]
     /// Hold refs to control the minting, transfer and burning of fungible assets.
-    struct ManagedFungibleAsset has key {
-        mint_ref: MintRef,
-        transfer_ref: TransferRef,
-        burn_ref: BurnRef,
+    struct ManagingRefs has key {
+        mint_ref: Option,
+        transfer_ref: Option,
+        burn_ref: Option,
     }
 
-    /// Initialize metadata object and store the refs.
+    /// Initialize metadata object and store the refs specified by `ref_flags`.
     public fun initialize(
         constructor_ref: &ConstructorRef,
         maximum_supply: u128,
@@ -34,7 +46,9 @@ module fungible_asset_extension::managed_fungible_asset {
         decimals: u8,
         icon_uri: String,
         project_uri: String,
+        ref_flags: vector,
     ) {
+        assert!(vector::length(&ref_flags) == 3, error::invalid_argument(ERR_INVALID_REF_FLAGS_LENGTH));
         let supply = if (maximum_supply != 0) {
             option::some(maximum_supply)
         } else {
@@ -50,100 +64,238 @@ module fungible_asset_extension::managed_fungible_asset {
             project_uri,
         );
 
-        // Create mint/burn/transfer refs to allow creator to manage the fungible asset.
-        let mint_ref = fungible_asset::generate_mint_ref(constructor_ref);
-        let burn_ref = fungible_asset::generate_burn_ref(constructor_ref);
-        let transfer_ref = fungible_asset::generate_transfer_ref(constructor_ref);
+        // Optionally create mint/burn/transfer refs to allow creator to manage the fungible asset.
+        let mint_ref = if (*vector::borrow(&ref_flags, 0)) {
+            option::some(fungible_asset::generate_mint_ref(constructor_ref))
+        } else {
+            option::none()
+        };
+        let transfer_ref = if (*vector::borrow(&ref_flags, 1)) {
+            option::some(fungible_asset::generate_transfer_ref(constructor_ref))
+        } else {
+            option::none()
+        };
+        let burn_ref = if (*vector::borrow(&ref_flags, 2)) {
+            option::some(fungible_asset::generate_burn_ref(constructor_ref))
+        } else {
+            option::none()
+        };
         let metadata_object_signer = object::generate_signer(constructor_ref);
         move_to(
             &metadata_object_signer,
-            ManagedFungibleAsset { mint_ref, transfer_ref, burn_ref }
+            ManagingRefs { mint_ref, transfer_ref, burn_ref }
         )
     }
 
-    /// Mint as the owner of metadata object.
+    /// Mint as the owner of metadata object to the primary fungible stores of the accounts with amounts of FAs.
+    public entry fun mint_to_primary_stores(
+        admin: &signer,
+        asset: Object,
+        to: vector
,
+        amounts: vector
+    ) acquires ManagingRefs {
+        let receiver_primary_stores = vector::map(
+            to,
+            |addr| primary_fungible_store::ensure_primary_store_exists(addr, asset)
+        );
+        mint(admin, asset, receiver_primary_stores, amounts);
+    }
+
+
+    /// Mint as the owner of metadata object to multiple fungible stores with amounts of FAs.
     public entry fun mint(
         admin: &signer,
-        metadata: Object,
-        amount: u64,
-        to: address
-    ) acquires ManagedFungibleAsset {
-        let managed_fungible_asset = authorized_borrow_refs(admin, metadata);
-        let to_wallet = primary_fungible_store::ensure_primary_store_exists(to, metadata);
-        let fa = fungible_asset::mint(&managed_fungible_asset.mint_ref, amount);
-        fungible_asset::deposit_with_ref(&managed_fungible_asset.transfer_ref, to_wallet, fa);
+        asset: Object,
+        stores: vector>,
+        amounts: vector,
+    ) acquires ManagingRefs {
+        let length = vector::length(&stores);
+        assert!(length == vector::length(&amounts), error::invalid_argument(ERR_VECTORS_LENGTH_MISMATCH));
+        let mint_ref = authorized_borrow_mint_ref(admin, asset);
+        let i = 0;
+        while (i < length) {
+            fungible_asset::mint_to(mint_ref, *vector::borrow(&stores, i), *vector::borrow(&amounts, i));
+            i = i + 1;
+        }
     }
 
-    /// Transfer as the owner of metadata object ignoring `frozen` field.
+    /// Transfer as the owner of metadata object ignoring `frozen` field from primary stores to primary stores of
+    /// accounts.
+    public entry fun transfer_between_primary_stores(
+        admin: &signer,
+        asset: Object,
+        from: vector
,
+        to: vector
,
+        amounts: vector
+    ) acquires ManagingRefs {
+        let sender_primary_stores = vector::map(
+            from,
+            |addr| primary_fungible_store::primary_store(addr, asset)
+        );
+        let receiver_primary_stores = vector::map(
+            to,
+            |addr| primary_fungible_store::ensure_primary_store_exists(addr, asset)
+        );
+        transfer(admin, asset, sender_primary_stores, receiver_primary_stores, amounts);
+    }
+
+    /// Transfer as the owner of metadata object ignoring `frozen` field between fungible stores.
     public entry fun transfer(
         admin: &signer,
-        metadata: Object,
-        from: address,
-        to: address,
-        amount: u64
-    ) acquires ManagedFungibleAsset {
-        let transfer_ref = &authorized_borrow_refs(admin, metadata).transfer_ref;
-        let from_wallet = primary_fungible_store::ensure_primary_store_exists(from, metadata);
-        let to_wallet = primary_fungible_store::ensure_primary_store_exists(to, metadata);
-        fungible_asset::transfer_with_ref(transfer_ref, from_wallet, to_wallet, amount);
-    }
-
-    /// Burn fungible assets as the owner of metadata object.
+        asset: Object,
+        sender_stores: vector>,
+        receiver_stores: vector>,
+        amounts: vector,
+    ) acquires ManagingRefs {
+        let length = vector::length(&sender_stores);
+        assert!(length == vector::length(&receiver_stores), error::invalid_argument(ERR_VECTORS_LENGTH_MISMATCH));
+        assert!(length == vector::length(&amounts), error::invalid_argument(ERR_VECTORS_LENGTH_MISMATCH));
+        let transfer_ref = authorized_borrow_transfer_ref(admin, asset);
+        let i = 0;
+        while (i < length) {
+            fungible_asset::transfer_with_ref(
+                transfer_ref,
+                *vector::borrow(&sender_stores, i),
+                *vector::borrow(&receiver_stores, i),
+                *vector::borrow(&amounts, i)
+            );
+            i = i + 1;
+        }
+    }
+
+    /// Burn fungible assets as the owner of metadata object from the primary stores of accounts.
+    public entry fun burn_from_primary_stores(
+        admin: &signer,
+        asset: Object,
+        from: vector
,
+        amounts: vector
+    ) acquires ManagingRefs {
+        let primary_stores = vector::map(
+            from,
+            |addr| primary_fungible_store::primary_store(addr, asset)
+        );
+        burn(admin, asset, primary_stores, amounts);
+    }
+
+    /// Burn fungible assets as the owner of metadata object from fungible stores.
     public entry fun burn(
         admin: &signer,
-        metadata: Object,
-        from: address,
-        amount: u64
-    ) acquires ManagedFungibleAsset {
-        let burn_ref = &authorized_borrow_refs(admin, metadata).burn_ref;
-        let from_wallet = primary_fungible_store::ensure_primary_store_exists(from, metadata);
-        fungible_asset::burn_from(burn_ref, from_wallet, amount);
+        asset: Object,
+        stores: vector>,
+        amounts: vector
+    ) acquires ManagingRefs {
+        let length = vector::length(&stores);
+        assert!(length == vector::length(&amounts), error::invalid_argument(ERR_VECTORS_LENGTH_MISMATCH));
+        let burn_ref = authorized_borrow_burn_ref(admin, asset);
+        let i = 0;
+        while (i < length) {
+            fungible_asset::burn_from(burn_ref, *vector::borrow(&stores, i), *vector::borrow(&amounts, i));
+            i = i + 1;
+        };
     }
 
-    /// Freeze an account so it cannot transfer or receive fungible assets.
-    public entry fun freeze_account(
+
+    /// Freeze/unfreeze the primary stores of accounts so they cannot transfer or receive fungible assets.
+    public entry fun set_primary_stores_frozen_status(
         admin: &signer,
-        metadata: Object,
-        account: address
-    ) acquires ManagedFungibleAsset {
-        let transfer_ref = &authorized_borrow_refs(admin, metadata).transfer_ref;
-        let wallet = primary_fungible_store::ensure_primary_store_exists(account, metadata);
-        fungible_asset::set_frozen_flag(transfer_ref, wallet, true);
+        asset: Object,
+        accounts: vector
,
+        frozen: bool
+    ) acquires ManagingRefs {
+        let primary_stores = vector::map(accounts, |acct| {
+            primary_fungible_store::ensure_primary_store_exists(acct, asset)
+        });
+        set_frozen_status(admin, asset, primary_stores, frozen);
+    }
+
+    /// Freeze/unfreeze the fungible stores so they cannot transfer or receive fungible assets.
+    public entry fun set_frozen_status(
+        admin: &signer,
+        asset: Object,
+        stores: vector>,
+        frozen: bool
+    ) acquires ManagingRefs {
+        let transfer_ref = authorized_borrow_transfer_ref(admin, asset);
+        vector::for_each(stores, |store| {
+            fungible_asset::set_frozen_flag(transfer_ref, store, frozen);
+        });
     }
 
-    /// Unfreeze an account so it can transfer or receive fungible assets.
-    public entry fun unfreeze_account(
+    /// Withdraw as the owner of metadata object ignoring `frozen` field from primary fungible stores of accounts.
+    public fun withdraw_from_primary_stores(
         admin: &signer,
-        metadata: Object,
-        account: address,
-    ) acquires ManagedFungibleAsset {
-        let transfer_ref = &authorized_borrow_refs(admin, metadata).transfer_ref;
-        let wallet = primary_fungible_store::ensure_primary_store_exists(account, metadata);
-        fungible_asset::set_frozen_flag(transfer_ref, wallet, false);
+        asset: Object,
+        from: vector
,
+        amounts: vector
+    ): FungibleAsset acquires ManagingRefs {
+        let primary_stores = vector::map(
+            from,
+            |addr| primary_fungible_store::primary_store(addr, asset)
+        );
+        withdraw(admin, asset, primary_stores, amounts)
     }
 
-    /// Withdraw as the owner of metadata object ignoring `frozen` field.
+    /// Withdraw as the owner of metadata object ignoring `frozen` field from fungible stores.
+    /// return a fungible asset `fa` where `fa.amount = sum(amounts)`.
     public fun withdraw(
         admin: &signer,
-        metadata: Object,
-        amount: u64,
-        from: address,
-    ): FungibleAsset acquires ManagedFungibleAsset {
-        let transfer_ref = &authorized_borrow_refs(admin, metadata).transfer_ref;
-        let from_wallet = primary_fungible_store::ensure_primary_store_exists(from, metadata);
-        fungible_asset::withdraw_with_ref(transfer_ref, from_wallet, amount)
+        asset: Object,
+        stores: vector>,
+        amounts: vector
+    ): FungibleAsset acquires ManagingRefs {
+        let length = vector::length(&stores);
+        assert!(length == vector::length(&amounts), error::invalid_argument(ERR_VECTORS_LENGTH_MISMATCH));
+        let transfer_ref = authorized_borrow_transfer_ref(admin, asset);
+        let i = 0;
+        let sum = fungible_asset::zero(asset);
+        while (i < length) {
+            let fa = fungible_asset::withdraw_with_ref(
+                transfer_ref,
+                *vector::borrow(&stores, i),
+                *vector::borrow(&amounts, i)
+            );
+            fungible_asset::merge(&mut sum, fa);
+            i = i + 1;
+        };
+        sum
+    }
+
+    /// Deposit as the owner of metadata object ignoring `frozen` field to primary fungible stores of accounts from a
+    /// single source of fungible asset.
+    public fun deposit_to_primary_stores(
+        admin: &signer,
+        fa: &mut FungibleAsset,
+        from: vector
,
+        amounts: vector,
+    ) acquires ManagingRefs {
+        let primary_stores = vector::map(
+            from,
+            |addr| primary_fungible_store::ensure_primary_store_exists(addr, fungible_asset::asset_metadata(fa))
+        );
+        deposit(admin, fa, primary_stores, amounts);
     }
 
-    /// Deposit as the owner of metadata object ignoring `frozen` field.
+    /// Deposit as the owner of metadata object ignoring `frozen` field from fungible stores. The amount left in `fa`
+    /// is `fa.amount - sum(amounts)`.
     public fun deposit(
         admin: &signer,
-        metadata: Object,
-        to: address,
-        fa: FungibleAsset,
-    ) acquires ManagedFungibleAsset {
-        let transfer_ref = &authorized_borrow_refs(admin, metadata).transfer_ref;
-        let to_wallet = primary_fungible_store::ensure_primary_store_exists(to, metadata);
-        fungible_asset::deposit_with_ref(transfer_ref, to_wallet, fa);
+        fa: &mut FungibleAsset,
+        stores: vector>,
+        amounts: vector
+    ) acquires ManagingRefs {
+        let length = vector::length(&stores);
+        assert!(length == vector::length(&amounts), error::invalid_argument(ERR_VECTORS_LENGTH_MISMATCH));
+        let transfer_ref = authorized_borrow_transfer_ref(admin, fungible_asset::asset_metadata(fa));
+        let i = 0;
+        while (i < length) {
+            let split_fa = fungible_asset::extract(fa, *vector::borrow(&amounts, i));
+            fungible_asset::deposit_with_ref(
+                transfer_ref,
+                *vector::borrow(&stores, i),
+                split_fa,
+            );
+            i = i + 1;
+        };
     }
 
     /// Borrow the immutable reference of the refs of `metadata`.
@@ -151,15 +303,47 @@ module fungible_asset_extension::managed_fungible_asset {
     inline fun authorized_borrow_refs(
         owner: &signer,
         asset: Object,
-    ): &ManagedFungibleAsset acquires ManagedFungibleAsset {
-        assert!(object::is_owner(asset, signer::address_of(owner)), error::permission_denied(ENOT_OWNER));
-        borrow_global(object::object_address(&asset))
+    ): &ManagingRefs acquires ManagingRefs {
+        assert!(object::is_owner(asset, signer::address_of(owner)), error::permission_denied(ERR_NOT_OWNER));
+        borrow_global(object::object_address(&asset))
+    }
+
+    /// Check the existence and borrow `MintRef`.
+    inline fun authorized_borrow_mint_ref(
+        owner: &signer,
+        asset: Object,
+    ): &MintRef acquires ManagingRefs {
+        let refs = authorized_borrow_refs(owner, asset);
+        assert!(option::is_some(&refs.mint_ref), error::not_found(ERR_MINT_REF));
+        option::borrow(&refs.mint_ref)
+    }
+
+    /// Check the existence and borrow `TransferRef`.
+    inline fun authorized_borrow_transfer_ref(
+        owner: &signer,
+        asset: Object,
+    ): &TransferRef acquires ManagingRefs {
+        let refs = authorized_borrow_refs(owner, asset);
+        assert!(option::is_some(&refs.transfer_ref), error::not_found(ERR_TRANSFER_REF));
+        option::borrow(&refs.transfer_ref)
+    }
+
+    /// Check the existence and borrow `BurnRef`.
+    inline fun authorized_borrow_burn_ref(
+        owner: &signer,
+        asset: Object,
+    ): &BurnRef acquires ManagingRefs {
+        let refs = authorized_borrow_refs(owner, asset);
+        assert!(option::is_some(&refs.mint_ref), error::not_found(ERR_BURN_REF));
+        option::borrow(&refs.burn_ref)
     }
 
     #[test_only]
     use aptos_framework::object::object_from_constructor_ref;
     #[test_only]
     use std::string::utf8;
+    use std::vector;
+    use std::option::Option;
 
     #[test_only]
     fun create_test_mfa(creator: &signer): Object {
@@ -172,6 +356,7 @@ module fungible_asset_extension::managed_fungible_asset {
             8, /* decimals */
             utf8(b"http://example.com/favicon.ico"), /* icon */
             utf8(b"http://example.com"), /* project */
+            vector[true, true, true]
         );
         object_from_constructor_ref(constructor_ref)
     }
@@ -179,21 +364,46 @@ module fungible_asset_extension::managed_fungible_asset {
     #[test(creator = @0xcafe)]
     fun test_basic_flow(
         creator: &signer,
-    ) acquires ManagedFungibleAsset {
+    ) acquires ManagingRefs {
         let metadata = create_test_mfa(creator);
         let creator_address = signer::address_of(creator);
         let aaron_address = @0xface;
 
-        mint(creator, metadata, 100, creator_address);
-        assert!(primary_fungible_store::balance(creator_address, metadata) == 100, 4);
-        freeze_account(creator, metadata, creator_address);
-        assert!(primary_fungible_store::is_frozen(creator_address, metadata), 5);
-        transfer(creator, metadata, creator_address, aaron_address, 10);
-        assert!(primary_fungible_store::balance(aaron_address, metadata) == 10, 6);
+        mint_to_primary_stores(creator, metadata, vector[creator_address, aaron_address], vector[100, 50]);
+        assert!(primary_fungible_store::balance(creator_address, metadata) == 100, 1);
+        assert!(primary_fungible_store::balance(aaron_address, metadata) == 50, 2);
+
+        set_primary_stores_frozen_status(creator, metadata, vector[creator_address, aaron_address], true);
+        assert!(primary_fungible_store::is_frozen(creator_address, metadata), 3);
+        assert!(primary_fungible_store::is_frozen(aaron_address, metadata), 4);
+
+        transfer_between_primary_stores(
+            creator,
+            metadata,
+            vector[creator_address, aaron_address],
+            vector[aaron_address, creator_address],
+            vector[10, 5]
+        );
+        assert!(primary_fungible_store::balance(creator_address, metadata) == 95, 5);
+        assert!(primary_fungible_store::balance(aaron_address, metadata) == 55, 6);
 
-        unfreeze_account(creator, metadata, creator_address);
+        set_primary_stores_frozen_status(creator, metadata, vector[creator_address, aaron_address], false);
         assert!(!primary_fungible_store::is_frozen(creator_address, metadata), 7);
-        burn(creator, metadata, creator_address, 90);
+        assert!(!primary_fungible_store::is_frozen(aaron_address, metadata), 8);
+
+        let fa = withdraw_from_primary_stores(
+            creator,
+            metadata,
+            vector[creator_address, aaron_address],
+            vector[25, 15]
+        );
+        assert!(fungible_asset::amount(&fa) == 40, 9);
+        deposit_to_primary_stores(creator, &mut fa, vector[creator_address, aaron_address], vector[30, 10]);
+        fungible_asset::destroy_zero(fa);
+
+        burn_from_primary_stores(creator, metadata, vector[creator_address, aaron_address], vector[100, 50]);
+        assert!(primary_fungible_store::balance(creator_address, metadata) == 0, 10);
+        assert!(primary_fungible_store::balance(aaron_address, metadata) == 0, 11);
     }
 
     #[test(creator = @0xcafe, aaron = @0xface)]
@@ -201,9 +411,9 @@ module fungible_asset_extension::managed_fungible_asset {
     fun test_permission_denied(
         creator: &signer,
         aaron: &signer
-    ) acquires ManagedFungibleAsset {
+    ) acquires ManagingRefs {
         let metadata = create_test_mfa(creator);
         let creator_address = signer::address_of(creator);
-        mint(aaron, metadata, 100, creator_address);
+        mint_to_primary_stores(aaron, metadata, vector[creator_address], vector[100]);
     }
 }
diff --git a/aptos-move/move-examples/fungible_asset/sources/managed_coin.move b/aptos-move/move-examples/fungible_asset/sources/simple_managed_coin.move
similarity index 94%
rename from aptos-move/move-examples/fungible_asset/sources/managed_coin.move
rename to aptos-move/move-examples/fungible_asset/sources/simple_managed_coin.move
index 1d4ac7efca315..78e8cac010eb9 100644
--- a/aptos-move/move-examples/fungible_asset/sources/managed_coin.move
+++ b/aptos-move/move-examples/fungible_asset/sources/simple_managed_coin.move
@@ -1,7 +1,7 @@
 /// A 2-in-1 module that combines managed_fungible_asset and coin_example into one module that when deployed, the
 /// deployer will be creating a new managed fungible asset with the hardcoded supply config, name, symbol, and decimals.
-/// The address of the asset can be obtained via get_metadata().
-module fungible_asset_extension::managed_coin {
+/// The address of the asset can be obtained via get_metadata(). As a simple version, it only deal with primary stores.
+module example_addr::simple_managed_coin {
     use aptos_framework::fungible_asset::{Self, MintRef, TransferRef, BurnRef, Metadata, FungibleAsset};
     use aptos_framework::object::{Self, Object};
     use aptos_framework::primary_fungible_store;
@@ -50,7 +50,7 @@ module fungible_asset_extension::managed_coin {
     #[view]
     /// Return the address of the managed fungible asset that's created when this module is deployed.
     public fun get_metadata(): Object {
-        let asset_address = object::create_object_address(&@fungible_asset_extension, ASSET_SYMBOL);
+        let asset_address = object::create_object_address(&@example_addr, ASSET_SYMBOL);
         object::address_to_object(asset_address)
     }
 
@@ -67,7 +67,7 @@ module fungible_asset_extension::managed_coin {
     public entry fun transfer(admin: &signer, from: address, to: address, amount: u64) acquires ManagedFungibleAsset {
         let asset = get_metadata();
         let transfer_ref = &authorized_borrow_refs(admin, asset).transfer_ref;
-        let from_wallet = primary_fungible_store::ensure_primary_store_exists(from, asset);
+        let from_wallet = primary_fungible_store::primary_store(from, asset);
         let to_wallet = primary_fungible_store::ensure_primary_store_exists(to, asset);
         fungible_asset::transfer_with_ref(transfer_ref, from_wallet, to_wallet, amount);
     }
@@ -76,7 +76,7 @@ module fungible_asset_extension::managed_coin {
     public entry fun burn(admin: &signer, from: address, amount: u64) acquires ManagedFungibleAsset {
         let asset = get_metadata();
         let burn_ref = &authorized_borrow_refs(admin, asset).burn_ref;
-        let from_wallet = primary_fungible_store::ensure_primary_store_exists(from, asset);
+        let from_wallet = primary_fungible_store::primary_store(from, asset);
         fungible_asset::burn_from(burn_ref, from_wallet, amount);
     }
 
@@ -100,7 +100,7 @@ module fungible_asset_extension::managed_coin {
     public fun withdraw(admin: &signer, amount: u64, from: address): FungibleAsset acquires ManagedFungibleAsset {
         let asset = get_metadata();
         let transfer_ref = &authorized_borrow_refs(admin, asset).transfer_ref;
-        let from_wallet = primary_fungible_store::ensure_primary_store_exists(from, asset);
+        let from_wallet = primary_fungible_store::primary_store(from, asset);
         fungible_asset::withdraw_with_ref(transfer_ref, from_wallet, amount)
     }
 

From 8c7fc88a31c98ab3ac7368640b4ed69ea6732fc3 Mon Sep 17 00:00:00 2001
From: Aaron Gao 
Date: Thu, 25 May 2023 12:51:50 -0700
Subject: [PATCH 151/200] [move-examples] pre-minted managed FA

---
 .../src/tests/fungible_asset.rs               |  49 +++--
 .../move-examples/fungible_asset/README.md    |   6 +
 .../managed_fungible_asset/Move.toml          |  12 ++
 .../sources/coin_example.move                 |   9 +-
 .../sources/managed_fungible_asset.move       |   4 +-
 .../managed_fungible_token/Move.toml          |  13 ++
 .../sources/managed_fungible_token.move       |  63 ++++++
 .../preminted_managed_coin/Move.toml          |  11 ++
 .../sources/preminted_managed_coin.move       |  63 ++++++
 .../{ => simple_managed_coin}/Move.toml       |   4 +-
 .../sources/simple_managed_coin.move          |   4 +-
 .../move-examples/fungible_token/Move.toml    |  12 --
 .../sources/managed_fungible_token.move       | 179 ------------------
 .../move-examples/tests/move_unit_tests.rs    |  16 +-
 14 files changed, 229 insertions(+), 216 deletions(-)
 create mode 100644 aptos-move/move-examples/fungible_asset/README.md
 create mode 100644 aptos-move/move-examples/fungible_asset/managed_fungible_asset/Move.toml
 rename aptos-move/move-examples/fungible_asset/{ => managed_fungible_asset}/sources/coin_example.move (95%)
 rename aptos-move/move-examples/fungible_asset/{ => managed_fungible_asset}/sources/managed_fungible_asset.move (99%)
 create mode 100644 aptos-move/move-examples/fungible_asset/managed_fungible_token/Move.toml
 create mode 100644 aptos-move/move-examples/fungible_asset/managed_fungible_token/sources/managed_fungible_token.move
 create mode 100644 aptos-move/move-examples/fungible_asset/preminted_managed_coin/Move.toml
 create mode 100644 aptos-move/move-examples/fungible_asset/preminted_managed_coin/sources/preminted_managed_coin.move
 rename aptos-move/move-examples/fungible_asset/{ => simple_managed_coin}/Move.toml (51%)
 rename aptos-move/move-examples/fungible_asset/{ => simple_managed_coin}/sources/simple_managed_coin.move (98%)
 delete mode 100644 aptos-move/move-examples/fungible_token/Move.toml
 delete mode 100644 aptos-move/move-examples/fungible_token/sources/managed_fungible_token.move

diff --git a/aptos-move/e2e-move-tests/src/tests/fungible_asset.rs b/aptos-move/e2e-move-tests/src/tests/fungible_asset.rs
index be4fb8cdfa1a3..e8142b054482a 100644
--- a/aptos-move/e2e-move-tests/src/tests/fungible_asset.rs
+++ b/aptos-move/e2e-move-tests/src/tests/fungible_asset.rs
@@ -23,26 +23,49 @@ fn test_basic_fungible_token() {
     let mut build_options = aptos_framework::BuildOptions::default();
     build_options
         .named_addresses
-        .insert("fungible_token".to_string(), *alice.address());
+        .insert("example_addr".to_string(), *alice.address());
 
     let result = h.publish_package_with_options(
         &alice,
-        &common::test_dir_path("../../../move-examples/fungible_token"),
+        &common::test_dir_path("../../../move-examples/fungible_asset/managed_fungible_asset"),
+        build_options.clone(),
+    );
+
+    assert_success!(result);
+    let result = h.publish_package_with_options(
+        &alice,
+        &common::test_dir_path("../../../move-examples/fungible_asset/managed_fungible_token"),
         build_options,
     );
     assert_success!(result);
 
+    let metadata = h
+        .execute_view_function(
+            str::parse(&format!(
+                "0x{}::managed_fungible_token::get_metadata",
+                *alice.address()
+            ))
+            .unwrap(),
+            vec![],
+            vec![],
+        )
+        .unwrap()
+        .pop()
+        .unwrap();
+    let metadata = bcs::from_bytes::(metadata.as_slice()).unwrap();
+
     let result = h.run_entry_function(
         &alice,
         str::parse(&format!(
-            "0x{}::managed_fungible_token::mint",
+            "0x{}::managed_fungible_asset::mint_to_primary_stores",
             *alice.address()
         ))
         .unwrap(),
         vec![],
         vec![
-            bcs::to_bytes::(&100).unwrap(), // amount
-            bcs::to_bytes(alice.address()).unwrap(),
+            bcs::to_bytes(&metadata).unwrap(),
+            bcs::to_bytes(&vec![alice.address()]).unwrap(),
+            bcs::to_bytes(&vec![100u64]).unwrap(), // amount
         ],
     );
     assert_success!(result);
@@ -50,15 +73,16 @@ fn test_basic_fungible_token() {
     let result = h.run_entry_function(
         &alice,
         str::parse(&format!(
-            "0x{}::managed_fungible_token::transfer",
+            "0x{}::managed_fungible_asset::transfer_between_primary_stores",
             *alice.address()
         ))
         .unwrap(),
         vec![],
         vec![
-            bcs::to_bytes(alice.address()).unwrap(),
-            bcs::to_bytes(bob.address()).unwrap(),
-            bcs::to_bytes::(&30).unwrap(), // amount
+            bcs::to_bytes(&metadata).unwrap(),
+            bcs::to_bytes(&vec![alice.address()]).unwrap(),
+            bcs::to_bytes(&vec![bob.address()]).unwrap(),
+            bcs::to_bytes(&vec![30u64]).unwrap(), // amount
         ],
     );
 
@@ -66,14 +90,15 @@ fn test_basic_fungible_token() {
     let result = h.run_entry_function(
         &alice,
         str::parse(&format!(
-            "0x{}::managed_fungible_token::burn",
+            "0x{}::managed_fungible_asset::burn_from_primary_stores",
             *alice.address()
         ))
         .unwrap(),
         vec![],
         vec![
-            bcs::to_bytes(bob.address()).unwrap(),
-            bcs::to_bytes::(&20).unwrap(), // amount
+            bcs::to_bytes(&metadata).unwrap(),
+            bcs::to_bytes(&vec![bob.address()]).unwrap(),
+            bcs::to_bytes(&vec![20u64]).unwrap(), // amount
         ],
     );
     assert_success!(result);
diff --git a/aptos-move/move-examples/fungible_asset/README.md b/aptos-move/move-examples/fungible_asset/README.md
new file mode 100644
index 0000000000000..e4e0e0419099c
--- /dev/null
+++ b/aptos-move/move-examples/fungible_asset/README.md
@@ -0,0 +1,6 @@
+# Fungible Asset
+
+* Managed fungible asset: A full-fledged fungible asset with customizable management capabilities and associated functions, based on which a light example is provided to show how to issue coin.
+* Managed fungible token: A fungible token example that adds token resource to the metadata object.
+* Simple managed coin: an all-in-one module implementing managed coin using fungible asset with limited functionalities (only deal with primary fungible stores).
+* Pre-minted managed coin: An example issuing pre-minting coin based on managed fungible asset.
\ No newline at end of file
diff --git a/aptos-move/move-examples/fungible_asset/managed_fungible_asset/Move.toml b/aptos-move/move-examples/fungible_asset/managed_fungible_asset/Move.toml
new file mode 100644
index 0000000000000..13f5646be9c3e
--- /dev/null
+++ b/aptos-move/move-examples/fungible_asset/managed_fungible_asset/Move.toml
@@ -0,0 +1,12 @@
+[package]
+name = "ManagedFungibleAsset"
+version = "0.0.0"
+
+[addresses]
+aptos_framework = "0x1"
+aptos_token_objects = "0x4"
+example_addr = "_"
+
+[dependencies]
+AptosFramework = { local = "../../../framework/aptos-framework" }
+AptosTokenObjects = { local = "../../../framework/aptos-token-objects" }
diff --git a/aptos-move/move-examples/fungible_asset/sources/coin_example.move b/aptos-move/move-examples/fungible_asset/managed_fungible_asset/sources/coin_example.move
similarity index 95%
rename from aptos-move/move-examples/fungible_asset/sources/coin_example.move
rename to aptos-move/move-examples/fungible_asset/managed_fungible_asset/sources/coin_example.move
index 1128e6851a5a4..77a893cbc6ce3 100644
--- a/aptos-move/move-examples/fungible_asset/sources/coin_example.move
+++ b/aptos-move/move-examples/fungible_asset/managed_fungible_asset/sources/coin_example.move
@@ -1,8 +1,8 @@
 /// A coin example using managed_fungible_asset to create a fungible "coin" and helper functions to only interact with
-/// primary fungible stores.
+/// primary fungible stores only.
 module example_addr::coin_example {
     use aptos_framework::object;
-    use aptos_framework::fungible_asset::{Metadata, FungibleAsset};
+    use aptos_framework::fungible_asset::{Self, Metadata, FungibleAsset};
     use aptos_framework::object::Object;
     use example_addr::managed_fungible_asset;
     use std::string::utf8;
@@ -83,9 +83,8 @@ module example_addr::coin_example {
     use aptos_framework::primary_fungible_store;
     #[test_only]
     use std::signer;
-    use aptos_framework::fungible_asset;
 
-    #[test(creator = @0xcafe)]
+    #[test(creator = @example_addr)]
     fun test_basic_flow(creator: &signer) {
         init_module(creator);
         let creator_address = signer::address_of(creator);
@@ -104,7 +103,7 @@ module example_addr::coin_example {
         burn(creator, creator_address, 90);
     }
 
-    #[test(creator = @0xcafe, aaron = @0xface)]
+    #[test(creator = @example_addr, aaron = @0xface)]
     #[expected_failure(abort_code = 0x50001, location = example_addr::managed_fungible_asset)]
     fun test_permission_denied(creator: &signer, aaron: &signer) {
         init_module(creator);
diff --git a/aptos-move/move-examples/fungible_asset/sources/managed_fungible_asset.move b/aptos-move/move-examples/fungible_asset/managed_fungible_asset/sources/managed_fungible_asset.move
similarity index 99%
rename from aptos-move/move-examples/fungible_asset/sources/managed_fungible_asset.move
rename to aptos-move/move-examples/fungible_asset/managed_fungible_asset/sources/managed_fungible_asset.move
index 8848fa35f1362..316d022642496 100644
--- a/aptos-move/move-examples/fungible_asset/sources/managed_fungible_asset.move
+++ b/aptos-move/move-examples/fungible_asset/managed_fungible_asset/sources/managed_fungible_asset.move
@@ -361,7 +361,7 @@ module example_addr::managed_fungible_asset {
         object_from_constructor_ref(constructor_ref)
     }
 
-    #[test(creator = @0xcafe)]
+    #[test(creator = @example_addr)]
     fun test_basic_flow(
         creator: &signer,
     ) acquires ManagingRefs {
@@ -406,7 +406,7 @@ module example_addr::managed_fungible_asset {
         assert!(primary_fungible_store::balance(aaron_address, metadata) == 0, 11);
     }
 
-    #[test(creator = @0xcafe, aaron = @0xface)]
+    #[test(creator = @example_addr, aaron = @0xface)]
     #[expected_failure(abort_code = 0x50001, location = Self)]
     fun test_permission_denied(
         creator: &signer,
diff --git a/aptos-move/move-examples/fungible_asset/managed_fungible_token/Move.toml b/aptos-move/move-examples/fungible_asset/managed_fungible_token/Move.toml
new file mode 100644
index 0000000000000..f45cd7800e185
--- /dev/null
+++ b/aptos-move/move-examples/fungible_asset/managed_fungible_token/Move.toml
@@ -0,0 +1,13 @@
+[package]
+name = "ManagedFungibleToken"
+version = "0.0.0"
+
+[addresses]
+aptos_framework = "0x1"
+aptos_token_objects = "0x4"
+example_addr = "_"
+
+[dependencies]
+AptosFramework = { local = "../../../framework/aptos-framework" }
+AptosTokenObjects = { local = "../../../framework/aptos-token-objects" }
+ManagedFungibleAsset = { local = "../managed_fungible_asset" }
diff --git a/aptos-move/move-examples/fungible_asset/managed_fungible_token/sources/managed_fungible_token.move b/aptos-move/move-examples/fungible_asset/managed_fungible_token/sources/managed_fungible_token.move
new file mode 100644
index 0000000000000..028be76f94b92
--- /dev/null
+++ b/aptos-move/move-examples/fungible_asset/managed_fungible_token/sources/managed_fungible_token.move
@@ -0,0 +1,63 @@
+/// An example combining fungible assets with token as fungible token. In this example, a token object is used as
+/// metadata to create fungible units, aka, fungible tokens.
+module example_addr::managed_fungible_token {
+    use aptos_framework::fungible_asset::Metadata;
+    use aptos_framework::object::{Self, Object};
+    use std::string::{utf8, String};
+    use std::option;
+    use aptos_token_objects::token::{create_named_token, create_token_seed};
+    use aptos_token_objects::collection::create_fixed_collection;
+    use example_addr::managed_fungible_asset;
+
+    const ASSET_SYMBOL: vector = b"YOLO";
+
+    /// Initialize metadata object and store the refs.
+    fun init_module(admin: &signer) {
+        let collection_name: String = utf8(b"test collection name");
+        let token_name: String = utf8(b"test token name");
+        create_fixed_collection(
+            admin,
+            utf8(b"test collection description"),
+            1,
+            collection_name,
+            option::none(),
+            utf8(b"http://aptoslabs.com/collection"),
+        );
+        let constructor_ref = &create_named_token(admin,
+            collection_name,
+            utf8(b"test token description"),
+            token_name,
+            option::none(),
+            utf8(b"http://aptoslabs.com/token"),
+        );
+
+        managed_fungible_asset::initialize(
+            constructor_ref,
+            0, /* maximum_supply. 0 means no maximum */
+            utf8(b"test fungible token"), /* name */
+            utf8(ASSET_SYMBOL), /* symbol */
+            0, /* decimals */
+            utf8(b"http://example.com/favicon.ico"), /* icon */
+            utf8(b"http://example.com"), /* project */
+            vector[true, true, true], /* mint_ref, transfer_ref, burn_ref */
+        );
+    }
+
+    #[view]
+    /// Return the address of the managed fungible asset that's created when this module is deployed.
+    /// This function is optional as a helper function for offline applications.
+    public fun get_metadata(): Object {
+        let collection_name: String = utf8(b"test collection name");
+        let token_name: String = utf8(b"test token name");
+        let asset_address = object::create_object_address(
+            &@example_addr,
+            create_token_seed(&collection_name, &token_name)
+        );
+        object::address_to_object(asset_address)
+    }
+
+    #[test(creator = @example_addr)]
+    fun test_init(creator: &signer) {
+        init_module(creator);
+    }
+}
diff --git a/aptos-move/move-examples/fungible_asset/preminted_managed_coin/Move.toml b/aptos-move/move-examples/fungible_asset/preminted_managed_coin/Move.toml
new file mode 100644
index 0000000000000..29cae9c2511fe
--- /dev/null
+++ b/aptos-move/move-examples/fungible_asset/preminted_managed_coin/Move.toml
@@ -0,0 +1,11 @@
+[package]
+name = "ManagedFungibleToken"
+version = "0.0.0"
+
+[addresses]
+aptos_framework = "0x1"
+example_addr = "_"
+
+[dependencies]
+AptosFramework = { local = "../../../framework/aptos-framework" }
+ManagedFungibleAsset = { local = "../managed_fungible_asset" }
diff --git a/aptos-move/move-examples/fungible_asset/preminted_managed_coin/sources/preminted_managed_coin.move b/aptos-move/move-examples/fungible_asset/preminted_managed_coin/sources/preminted_managed_coin.move
new file mode 100644
index 0000000000000..8993acebcecd5
--- /dev/null
+++ b/aptos-move/move-examples/fungible_asset/preminted_managed_coin/sources/preminted_managed_coin.move
@@ -0,0 +1,63 @@
+/// This module shows an example how to issue preminted coin with only `transfer` and `burn` managing capabilities.
+/// It leveraged `managed_fungible_asset` module with only `TransferRef` and `BurnRef` stored after pre-minting a
+/// pre-defined totally supply to a reserve account. After the initialization, the total supply can increase by no means
+/// since `MintRef` of this fungible asset does not exist anymore.
+/// The `init_module()` code can be modified to customize the managing refs as needed.
+module example_addr::preminted_managed_coin {
+    use aptos_framework::fungible_asset::{Self, Metadata};
+    use aptos_framework::object::{Self, Object};
+    use aptos_framework::primary_fungible_store;
+    use example_addr::managed_fungible_asset;
+    use std::signer;
+    use std::string::utf8;
+
+    const ASSET_SYMBOL: vector = b"MEME";
+    const PRE_MINTED_TOTAL_SUPPLY: u64 = 10000;
+
+    /// Initialize metadata object and store the refs.
+    fun init_module(admin: &signer) {
+        let constructor_ref = &object::create_named_object(admin, ASSET_SYMBOL);
+        managed_fungible_asset::initialize(
+            constructor_ref,
+            1000000000, /* maximum_supply */
+            utf8(b"preminted coin"), /* name */
+            utf8(ASSET_SYMBOL), /* symbol */
+            8, /* decimals */
+            utf8(b"http://example.com/favicon.ico"), /* icon */
+            utf8(b"http://example.com"), /* project */
+            vector[false, true, true], /* mint_ref, transfer_ref, burn_ref */
+        );
+
+        // Create mint ref to premint fungible asset with a fixed supply volume into a specific account.
+        // This account can be any account including normal user account, resource account, multi-sig account, etc.
+        // We just use the creator account to show the proof of concept.
+        let mint_ref = fungible_asset::generate_mint_ref(constructor_ref);
+        let admin_primary_store = primary_fungible_store::ensure_primary_store_exists(
+            signer::address_of(admin),
+            get_metadata()
+        );
+        fungible_asset::mint_to(&mint_ref, admin_primary_store, PRE_MINTED_TOTAL_SUPPLY);
+    }
+
+    #[view]
+    /// Return the address of the metadata that's created when this module is deployed.
+    /// This function is optional as a helper function for offline applications.
+    public fun get_metadata(): Object {
+        let metadata_address = object::create_object_address(&@example_addr, ASSET_SYMBOL);
+        object::address_to_object(metadata_address)
+    }
+
+    #[test_only]
+    use std::option;
+
+    #[test(creator = @example_addr)]
+    #[expected_failure(abort_code = 0x60004, location = example_addr::managed_fungible_asset)]
+    fun test_basic_flow(creator: &signer) {
+        init_module(creator);
+        let creator_address = signer::address_of(creator);
+        let metadata = get_metadata();
+
+        assert!(option::destroy_some(fungible_asset::supply(metadata)) == (PRE_MINTED_TOTAL_SUPPLY as u128), 1);
+        managed_fungible_asset::mint_to_primary_stores(creator, metadata, vector[creator_address], vector[100]);
+    }
+}
diff --git a/aptos-move/move-examples/fungible_asset/Move.toml b/aptos-move/move-examples/fungible_asset/simple_managed_coin/Move.toml
similarity index 51%
rename from aptos-move/move-examples/fungible_asset/Move.toml
rename to aptos-move/move-examples/fungible_asset/simple_managed_coin/Move.toml
index 13e36a1b8502e..77d11359f270d 100644
--- a/aptos-move/move-examples/fungible_asset/Move.toml
+++ b/aptos-move/move-examples/fungible_asset/simple_managed_coin/Move.toml
@@ -1,5 +1,5 @@
 [package]
-name = "FungibleAsset"
+name = "SimpleManagedCoin"
 version = "0.0.0"
 
 [addresses]
@@ -7,4 +7,4 @@ aptos_framework = "0x1"
 example_addr = "_"
 
 [dependencies]
-AptosFramework = { local = "../../framework/aptos-framework" }
+AptosFramework = { local = "../../../framework/aptos-framework" }
diff --git a/aptos-move/move-examples/fungible_asset/sources/simple_managed_coin.move b/aptos-move/move-examples/fungible_asset/simple_managed_coin/sources/simple_managed_coin.move
similarity index 98%
rename from aptos-move/move-examples/fungible_asset/sources/simple_managed_coin.move
rename to aptos-move/move-examples/fungible_asset/simple_managed_coin/sources/simple_managed_coin.move
index 78e8cac010eb9..3a0c77fff44e3 100644
--- a/aptos-move/move-examples/fungible_asset/sources/simple_managed_coin.move
+++ b/aptos-move/move-examples/fungible_asset/simple_managed_coin/sources/simple_managed_coin.move
@@ -122,7 +122,7 @@ module example_addr::simple_managed_coin {
         borrow_global(object::object_address(&asset))
     }
 
-    #[test(creator = @0xcafe)]
+    #[test(creator = @example_addr)]
     fun test_basic_flow(
         creator: &signer,
     ) acquires ManagedFungibleAsset {
@@ -143,7 +143,7 @@ module example_addr::simple_managed_coin {
         burn(creator, creator_address, 90);
     }
 
-    #[test(creator = @0xcafe, aaron = @0xface)]
+    #[test(creator = @example_addr, aaron = @0xface)]
     #[expected_failure(abort_code = 0x50001, location = Self)]
     fun test_permission_denied(
         creator: &signer,
diff --git a/aptos-move/move-examples/fungible_token/Move.toml b/aptos-move/move-examples/fungible_token/Move.toml
deleted file mode 100644
index 08298dd4627eb..0000000000000
--- a/aptos-move/move-examples/fungible_token/Move.toml
+++ /dev/null
@@ -1,12 +0,0 @@
-[package]
-name = "FungibleToken"
-version = "0.0.0"
-
-[addresses]
-aptos_framework = "0x1"
-aptos_token_objects = "0x4"
-fungible_token = "_"
-
-[dependencies]
-AptosFramework = { local = "../../framework/aptos-framework" }
-AptosTokenObjects = { local = "../../framework/aptos-token-objects" }
diff --git a/aptos-move/move-examples/fungible_token/sources/managed_fungible_token.move b/aptos-move/move-examples/fungible_token/sources/managed_fungible_token.move
deleted file mode 100644
index 5f576d8daa48a..0000000000000
--- a/aptos-move/move-examples/fungible_token/sources/managed_fungible_token.move
+++ /dev/null
@@ -1,179 +0,0 @@
-/// An example combining fungible assets with token as fungible token. In this example, a token object is used as
-/// metadata to create fungible units, aka, fungible tokens.
-module fungible_token::managed_fungible_token {
-    use aptos_framework::fungible_asset::{Self, MintRef, TransferRef, BurnRef, Metadata, FungibleAsset};
-    use aptos_framework::object::{Self, Object};
-    use aptos_framework::primary_fungible_store;
-    use std::error;
-    use std::signer;
-    use std::string::{utf8, String};
-    use std::option;
-    use aptos_token_objects::token::{create_named_token, create_token_seed};
-    use aptos_token_objects::collection::create_fixed_collection;
-
-    /// Only fungible asset metadata owner can make changes.
-    const ENOT_OWNER: u64 = 1;
-
-    const ASSET_SYMBOL: vector = b"TEST";
-
-    #[resource_group_member(group = aptos_framework::object::ObjectGroup)]
-    /// Hold refs to control the minting, transfer and burning of fungible assets.
-    struct ManagedFungibleAsset has key {
-        mint_ref: MintRef,
-        transfer_ref: TransferRef,
-        burn_ref: BurnRef,
-    }
-
-    /// Initialize metadata object and store the refs.
-    fun init_module(admin: &signer) {
-        let collection_name: String = utf8(b"test collection name");
-        let token_name: String = utf8(b"test token name");
-        create_fixed_collection(
-            admin,
-            utf8(b"test collection description"),
-            1,
-            collection_name,
-            option::none(),
-            utf8(b"http://aptoslabs.com/collection"),
-        );
-        let constructor_ref = &create_named_token(admin,
-            collection_name,
-            utf8(b"test token description"),
-            token_name,
-            option::none(),
-            utf8(b"http://aptoslabs.com/token"),
-        );
-
-        primary_fungible_store::create_primary_store_enabled_fungible_asset(
-            constructor_ref,
-            option::none(),
-            utf8(b"test fungible asset name"), /* name */
-            utf8(ASSET_SYMBOL), /* symbol */
-            2, /* decimals */
-            utf8(b"http://aptoslabs.com/favicon.ico"),
-            utf8(b"http://aptoslabs.com/")
-        );
-
-        // Create mint/burn/transfer refs to allow creator to manage the fungible asset.
-        let mint_ref = fungible_asset::generate_mint_ref(constructor_ref);
-        let burn_ref = fungible_asset::generate_burn_ref(constructor_ref);
-        let transfer_ref = fungible_asset::generate_transfer_ref(constructor_ref);
-        let metadata_object_signer = object::generate_signer(constructor_ref);
-        move_to(
-            &metadata_object_signer,
-            ManagedFungibleAsset { mint_ref, transfer_ref, burn_ref }
-        )
-    }
-
-    #[view]
-    /// Return the address of the managed fungible asset that's created when this module is deployed.
-    public fun get_metadata(): Object {
-        let collection_name: String = utf8(b"test collection name");
-        let token_name: String = utf8(b"test token name");
-        let asset_address = object::create_object_address(
-            &@fungible_token,
-            create_token_seed(&collection_name, &token_name)
-        );
-        object::address_to_object(asset_address)
-    }
-
-    /// Mint as the owner of metadata object.
-    public entry fun mint(admin: &signer, amount: u64, to: address) acquires ManagedFungibleAsset {
-        let asset = get_metadata();
-        let managed_fungible_asset = authorized_borrow_refs(admin, asset);
-        let to_wallet = primary_fungible_store::ensure_primary_store_exists(to, asset);
-        let fa = fungible_asset::mint(&managed_fungible_asset.mint_ref, amount);
-        fungible_asset::deposit_with_ref(&managed_fungible_asset.transfer_ref, to_wallet, fa);
-    }
-
-    /// Transfer as the owner of metadata object ignoring `allow_ungated_transfer` field.
-    public entry fun transfer(admin: &signer, from: address, to: address, amount: u64) acquires ManagedFungibleAsset {
-        let asset = get_metadata();
-        let transfer_ref = &authorized_borrow_refs(admin, asset).transfer_ref;
-        let from_wallet = primary_fungible_store::ensure_primary_store_exists(from, asset);
-        let to_wallet = primary_fungible_store::ensure_primary_store_exists(to, asset);
-        fungible_asset::transfer_with_ref(transfer_ref, from_wallet, to_wallet, amount);
-    }
-
-    /// Burn fungible assets as the owner of metadata object.
-    public entry fun burn(admin: &signer, from: address, amount: u64) acquires ManagedFungibleAsset {
-        let asset = get_metadata();
-        let burn_ref = &authorized_borrow_refs(admin, asset).burn_ref;
-        let from_wallet = primary_fungible_store::ensure_primary_store_exists(from, asset);
-        fungible_asset::burn_from(burn_ref, from_wallet, amount);
-    }
-
-    /// Freeze an account so it cannot transfer or receive fungible assets.
-    public entry fun freeze_account(admin: &signer, account: address) acquires ManagedFungibleAsset {
-        let asset = get_metadata();
-        let transfer_ref = &authorized_borrow_refs(admin, asset).transfer_ref;
-        let wallet = primary_fungible_store::ensure_primary_store_exists(account, asset);
-        fungible_asset::set_frozen_flag(transfer_ref, wallet, true);
-    }
-
-    /// Unfreeze an account so it can transfer or receive fungible assets.
-    public entry fun unfreeze_account(admin: &signer, account: address) acquires ManagedFungibleAsset {
-        let asset = get_metadata();
-        let transfer_ref = &authorized_borrow_refs(admin, asset).transfer_ref;
-        let wallet = primary_fungible_store::ensure_primary_store_exists(account, asset);
-        fungible_asset::set_frozen_flag(transfer_ref, wallet, false);
-    }
-
-    /// Withdraw as the owner of metadata object ignoring `allow_ungated_transfer` field.
-    public fun withdraw(admin: &signer, amount: u64, from: address): FungibleAsset acquires ManagedFungibleAsset {
-        let asset = get_metadata();
-        let transfer_ref = &authorized_borrow_refs(admin, asset).transfer_ref;
-        let from_wallet = primary_fungible_store::ensure_primary_store_exists(from, asset);
-        fungible_asset::withdraw_with_ref(transfer_ref, from_wallet, amount)
-    }
-
-    /// Deposit as the owner of metadata object ignoring `allow_ungated_transfer` field.
-    public fun deposit(admin: &signer, to: address, fa: FungibleAsset) acquires ManagedFungibleAsset {
-        let asset = get_metadata();
-        let transfer_ref = &authorized_borrow_refs(admin, asset).transfer_ref;
-        let to_wallet = primary_fungible_store::ensure_primary_store_exists(to, asset);
-        fungible_asset::deposit_with_ref(transfer_ref, to_wallet, fa);
-    }
-
-    /// Borrow the immutable reference of the refs of `metadata`.
-    /// This validates that the signer is the metadata object's owner.
-    inline fun authorized_borrow_refs(
-        owner: &signer,
-        asset: Object,
-    ): &ManagedFungibleAsset acquires ManagedFungibleAsset {
-        assert!(object::is_owner(asset, signer::address_of(owner)), error::permission_denied(ENOT_OWNER));
-        borrow_global(object::object_address(&asset))
-    }
-
-    #[test(creator = @fungible_token)]
-    fun test_basic_flow(
-        creator: &signer,
-    ) acquires ManagedFungibleAsset {
-        init_module(creator);
-        let creator_address = signer::address_of(creator);
-        let aaron_address = @0xface;
-
-        mint(creator, 100, creator_address);
-        let asset = get_metadata();
-        assert!(primary_fungible_store::balance(creator_address, asset) == 100, 4);
-        freeze_account(creator, creator_address);
-        assert!(primary_fungible_store::is_frozen(creator_address, asset), 5);
-        transfer(creator, creator_address, aaron_address, 10);
-        assert!(primary_fungible_store::balance(aaron_address, asset) == 10, 6);
-
-        unfreeze_account(creator, creator_address);
-        assert!(!primary_fungible_store::is_frozen(creator_address, asset), 7);
-        burn(creator, creator_address, 90);
-    }
-
-    #[test(creator = @fungible_token, aaron = @0xface)]
-    #[expected_failure(abort_code = 0x50001, location = Self)]
-    fun test_permission_denied(
-        creator: &signer,
-        aaron: &signer
-    ) acquires ManagedFungibleAsset {
-        init_module(creator);
-        let creator_address = signer::address_of(creator);
-        mint(aaron, 100, creator_address);
-    }
-}
diff --git a/aptos-move/move-examples/tests/move_unit_tests.rs b/aptos-move/move-examples/tests/move_unit_tests.rs
index bfdcb8d86ceb7..b59c434c51510 100644
--- a/aptos-move/move-examples/tests/move_unit_tests.rs
+++ b/aptos-move/move-examples/tests/move_unit_tests.rs
@@ -113,10 +113,22 @@ fn test_message_board() {
 #[test]
 fn test_fungible_asset() {
     let named_address = BTreeMap::from([(
-        String::from("fungible_asset_extension"),
+        String::from("example_addr"),
         AccountAddress::from_hex_literal("0xcafe").unwrap(),
     )]);
-    run_tests_for_pkg("fungible_asset", named_address);
+    run_tests_for_pkg(
+        "fungible_asset/managed_fungible_asset",
+        named_address.clone(),
+    );
+    run_tests_for_pkg(
+        "fungible_asset/managed_fungible_token",
+        named_address.clone(),
+    );
+    run_tests_for_pkg(
+        "fungible_asset/preminted_managed_coin",
+        named_address.clone(),
+    );
+    run_tests_for_pkg("fungible_asset/simple_managed_coin", named_address);
 }
 
 #[test]

From d9232c9ec6e8d9e1b73ae154e95765c4da3f965b Mon Sep 17 00:00:00 2001
From: igor-aptos <110557261+igor-aptos@users.noreply.github.com>
Date: Tue, 13 Jun 2023 12:06:55 -0700
Subject: [PATCH 152/200] Forge test for testing throughput on network purely
 tuned for throughput (#8595)

---
 config/src/config/consensus_config.rs |  4 +-
 testsuite/forge-cli/src/main.rs       | 70 +++++++++++++++++++++++++--
 2 files changed, 67 insertions(+), 7 deletions(-)

diff --git a/config/src/config/consensus_config.rs b/config/src/config/consensus_config.rs
index bd72be00347fc..d240ab9f8d5bc 100644
--- a/config/src/config/consensus_config.rs
+++ b/config/src/config/consensus_config.rs
@@ -102,8 +102,8 @@ impl Default for ConsensusConfig {
             max_sending_block_bytes: 600 * 1024, // 600 KB
             max_sending_block_bytes_quorum_store_override: 5 * 1024 * 1024, // 5MB
             max_receiving_block_txns: 10000,
-            max_receiving_block_txns_quorum_store_override: 2
-                * MAX_SENDING_BLOCK_TXNS_QUORUM_STORE_OVERRIDE,
+            max_receiving_block_txns_quorum_store_override: 10000
+                .max(2 * MAX_SENDING_BLOCK_TXNS_QUORUM_STORE_OVERRIDE),
             max_receiving_block_bytes: 3 * 1024 * 1024, // 3MB
             max_receiving_block_bytes_quorum_store_override: 6 * 1024 * 1024, // 6MB
             max_pruned_blocks_in_mem: 100,
diff --git a/testsuite/forge-cli/src/main.rs b/testsuite/forge-cli/src/main.rs
index a9147872d90f0..d6dd38b9d4124 100644
--- a/testsuite/forge-cli/src/main.rs
+++ b/testsuite/forge-cli/src/main.rs
@@ -3,7 +3,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use anyhow::{format_err, Context, Result};
-use aptos_config::config::ConsensusConfig;
+use aptos_config::config::{ChainHealthBackoffValues, ConsensusConfig, PipelineBackpressureValues};
 use aptos_forge::{
     args::TransactionTypeArg,
     success_criteria::{LatencyType, StateProgressThreshold, SuccessCriteria},
@@ -488,11 +488,12 @@ fn single_test_suite(test_name: &str, duration: Duration) -> Result
     let single_test_suite = match test_name {
         // Land-blocking tests to be run on every PR:
         "land_blocking" => land_blocking_test_suite(duration), // to remove land_blocking, superseeded by the below
-        "realistic_env_max_throughput" => realistic_env_max_throughput_test_suite(duration),
+        "realistic_env_max_throughput" => realistic_env_max_throughput_test(duration),
         "compat" => compat(),
         "framework_upgrade" => upgrade(),
         // Rest of the tests:
         "realistic_env_load_sweep" => realistic_env_load_sweep_test(),
+        "realistic_network_tuned_for_throughput" => realistic_network_tuned_for_throughput_test(),
         "epoch_changer_performance" => epoch_changer_performance(),
         "state_sync_perf_fullnodes_apply_outputs" => state_sync_perf_fullnodes_apply_outputs(),
         "state_sync_perf_fullnodes_execute_transactions" => {
@@ -910,7 +911,7 @@ fn graceful_overload() -> ForgeConfig {
     ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(10).unwrap())
         // if we have full nodes for subset of validators, TPS drops.
-        // Validators without VFN are proposing almost empty blocks,
+        // Validators without VFN are not creating batches,
         // as no useful transaction reach their mempool.
         // something to potentially improve upon.
         // So having VFNs for all validators
@@ -957,7 +958,7 @@ fn three_region_sim_graceful_overload() -> ForgeConfig {
     ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
         // if we have full nodes for subset of validators, TPS drops.
-        // Validators without VFN are proposing almost empty blocks,
+        // Validators without VFN are not creating batches,
         // as no useful transaction reach their mempool.
         // something to potentially improve upon.
         // So having VFNs for all validators
@@ -1367,7 +1368,7 @@ fn land_blocking_test_suite(duration: Duration) -> ForgeConfig {
 }
 
 // TODO: Replace land_blocking when performance reaches on par with current land_blocking
-fn realistic_env_max_throughput_test_suite(duration: Duration) -> ForgeConfig {
+fn realistic_env_max_throughput_test(duration: Duration) -> ForgeConfig {
     ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
         .with_initial_fullnode_count(10)
@@ -1420,6 +1421,65 @@ fn realistic_env_max_throughput_test_suite(duration: Duration) -> ForgeConfig {
         )
 }
 
+fn realistic_network_tuned_for_throughput_test() -> ForgeConfig {
+    ForgeConfig::default()
+        .with_initial_validator_count(NonZeroUsize::new(12).unwrap())
+        // if we have full nodes for subset of validators, TPS drops.
+        // Validators without VFN are not creating batches,
+        // as no useful transaction reach their mempool.
+        // something to potentially improve upon.
+        // So having VFNs for all validators
+        .with_initial_fullnode_count(12)
+        .add_network_test(MultiRegionNetworkEmulationTest {
+            override_config: None,
+        })
+        .with_emit_job(EmitJobRequest::default().mode(EmitJobMode::MaxLoad {
+            mempool_backlog: 150000,
+        }))
+        .with_node_helm_config_fn(Arc::new(move |helm_values| {
+            helm_values["validator"]["config"]["consensus"]
+                ["max_sending_block_txns_quorum_store_override"] = 10000.into();
+            helm_values["validator"]["config"]["consensus"]["pipeline_backpressure"] =
+                serde_yaml::to_value(Vec::::new()).unwrap();
+            helm_values["validator"]["config"]["consensus"]["chain_health_backoff"] =
+                serde_yaml::to_value(Vec::::new()).unwrap();
+
+            helm_values["validator"]["config"]["consensus"]
+                ["wait_for_full_blocks_above_recent_fill_threshold"] = (0.8).into();
+            helm_values["validator"]["config"]["consensus"]
+                ["wait_for_full_blocks_above_pending_blocks"] = 8.into();
+
+            helm_values["validator"]["config"]["consensus"]["quorum_store"]["back_pressure"]
+                ["backlog_txn_limit_count"] = 100000.into();
+            helm_values["validator"]["config"]["consensus"]["quorum_store"]["back_pressure"]
+                ["backlog_per_validator_batch_limit_count"] = 10.into();
+
+            helm_values["validator"]["config"]["consensus"]["quorum_store"]["back_pressure"]
+                ["dynamic_max_txn_per_s"] = 6000.into();
+
+            // Experimental storage optimizations
+            helm_values["validator"]["config"]["storage"]["rocksdb_configs"]["use_state_kv_db"] =
+                true.into();
+            helm_values["validator"]["config"]["storage"]["rocksdb_configs"]
+                ["use_sharded_state_merkle_db"] = true.into();
+        }))
+        .with_success_criteria(
+            SuccessCriteria::new(8000)
+                .add_no_restarts()
+                .add_wait_for_catchup_s(60)
+                .add_system_metrics_threshold(SystemMetricsThreshold::new(
+                    // Check that we don't use more than 12 CPU cores for 30% of the time.
+                    MetricsThreshold::new(12, 30),
+                    // Check that we don't use more than 10 GB of memory for 30% of the time.
+                    MetricsThreshold::new(10 * 1024 * 1024 * 1024, 30),
+                ))
+                .add_chain_progress(StateProgressThreshold {
+                    max_no_progress_secs: 10.0,
+                    max_round_gap: 4,
+                }),
+        )
+}
+
 fn pre_release_suite() -> ForgeConfig {
     ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(30).unwrap())

From f8385b3c9a365f32696b256b85158bf750765b20 Mon Sep 17 00:00:00 2001
From: Guoteng Rao <3603304+grao1991@users.noreply.github.com>
Date: Tue, 13 Jun 2023 12:23:41 -0700
Subject: [PATCH 153/200] [Storage][Sharding] Implement create_checkpoint for
 LedgerDb, and deprecate use_state_kv_db flag. (#8602)

---
 aptos-node/src/storage.rs                     |  1 +
 config/src/config/storage_config.rs           |  4 --
 .../executor-benchmark/src/db_generator.rs    | 15 ++++--
 execution/executor-benchmark/src/lib.rs       | 24 ++++++---
 execution/executor-benchmark/src/main.rs      |  8 +--
 .../aptosdb/src/db_debugger/checkpoint/mod.rs |  4 +-
 .../db_debugger/examine/print_db_versions.rs  |  4 +-
 .../aptosdb/src/db_debugger/truncate/mod.rs   | 13 +++--
 storage/aptosdb/src/ledger_db.rs              | 50 +++++++++++++++++--
 storage/aptosdb/src/lib.rs                    | 26 ++++------
 storage/aptosdb/src/state_kv_db.rs            |  2 +-
 storage/backup/backup-cli/src/utils/mod.rs    |  3 --
 testsuite/single_node_performance.py          |  4 +-
 testsuite/smoke-test/src/genesis.rs           |  2 +-
 testsuite/smoke-test/src/storage.rs           |  8 +--
 15 files changed, 108 insertions(+), 60 deletions(-)

diff --git a/aptos-node/src/storage.rs b/aptos-node/src/storage.rs
index 5a71240ff61e7..84b44a7b3d82a 100644
--- a/aptos-node/src/storage.rs
+++ b/aptos-node/src/storage.rs
@@ -62,6 +62,7 @@ fn create_rocksdb_checkpoint_and_change_working_dir(
     AptosDB::create_checkpoint(
         &source_dir,
         &checkpoint_dir,
+        node_config.storage.rocksdb_configs.split_ledger_db,
         node_config
             .storage
             .rocksdb_configs
diff --git a/config/src/config/storage_config.rs b/config/src/config/storage_config.rs
index c9f29cd240ade..933fd1d940db4 100644
--- a/config/src/config/storage_config.rs
+++ b/config/src/config/storage_config.rs
@@ -65,9 +65,6 @@ pub struct RocksdbConfigs {
     pub ledger_db_config: RocksdbConfig,
     pub state_merkle_db_config: RocksdbConfig,
     // Note: Not ready for production use yet.
-    // TODO(grao): Deprecate this flag and use the split_ledger_db_to_individual_dbs below.
-    pub use_state_kv_db: bool,
-    // Note: Not ready for production use yet.
     pub use_sharded_state_merkle_db: bool,
     // Note: Not ready for production use yet.
     // TODO(grao): Add RocksdbConfig for individual DBs when necessary.
@@ -81,7 +78,6 @@ impl Default for RocksdbConfigs {
         Self {
             ledger_db_config: RocksdbConfig::default(),
             state_merkle_db_config: RocksdbConfig::default(),
-            use_state_kv_db: false,
             use_sharded_state_merkle_db: false,
             split_ledger_db: false,
             state_kv_db_config: RocksdbConfig::default(),
diff --git a/execution/executor-benchmark/src/db_generator.rs b/execution/executor-benchmark/src/db_generator.rs
index 1faf1d8d1c8f3..1cd8c43a032af 100644
--- a/execution/executor-benchmark/src/db_generator.rs
+++ b/execution/executor-benchmark/src/db_generator.rs
@@ -26,7 +26,7 @@ pub fn create_db_with_accounts(
     db_dir: impl AsRef,
     storage_pruner_config: PrunerConfig,
     verify_sequence_numbers: bool,
-    use_state_kv_db: bool,
+    split_ledger_db: bool,
     use_sharded_state_merkle_db: bool,
     pipeline_config: PipelineConfig,
 ) where
@@ -40,7 +40,7 @@ pub fn create_db_with_accounts(
     // create if not exists
     fs::create_dir_all(db_dir.as_ref()).unwrap();
 
-    bootstrap_with_genesis(&db_dir, use_state_kv_db);
+    bootstrap_with_genesis(&db_dir, split_ledger_db, use_sharded_state_merkle_db);
 
     println!(
         "Finished empty DB creation, DB dir: {}. Creating accounts now...",
@@ -55,18 +55,23 @@ pub fn create_db_with_accounts(
         &db_dir,
         storage_pruner_config,
         verify_sequence_numbers,
-        use_state_kv_db,
+        split_ledger_db,
         use_sharded_state_merkle_db,
         pipeline_config,
     );
 }
 
-fn bootstrap_with_genesis(db_dir: impl AsRef, use_state_kv_db: bool) {
+fn bootstrap_with_genesis(
+    db_dir: impl AsRef,
+    split_ledger_db: bool,
+    use_sharded_state_merkle_db: bool,
+) {
     let (config, _genesis_key) = aptos_genesis::test_utils::test_config();
 
     let mut rocksdb_configs = RocksdbConfigs::default();
     rocksdb_configs.state_merkle_db_config.max_open_files = -1;
-    rocksdb_configs.use_state_kv_db = use_state_kv_db;
+    rocksdb_configs.split_ledger_db = split_ledger_db;
+    rocksdb_configs.use_sharded_state_merkle_db = use_sharded_state_merkle_db;
     let (_db, db_rw) = DbReaderWriter::wrap(
         AptosDB::open(
             &db_dir,
diff --git a/execution/executor-benchmark/src/lib.rs b/execution/executor-benchmark/src/lib.rs
index 061b88dd5328f..143a93d6a58df 100644
--- a/execution/executor-benchmark/src/lib.rs
+++ b/execution/executor-benchmark/src/lib.rs
@@ -73,6 +73,7 @@ where
 fn create_checkpoint(
     source_dir: impl AsRef,
     checkpoint_dir: impl AsRef,
+    split_ledger_db: bool,
     use_sharded_state_merkle_db: bool,
 ) {
     // Create rocksdb checkpoint.
@@ -81,8 +82,13 @@ fn create_checkpoint(
     }
     std::fs::create_dir_all(checkpoint_dir.as_ref()).unwrap();
 
-    AptosDB::create_checkpoint(source_dir, checkpoint_dir, use_sharded_state_merkle_db)
-        .expect("db checkpoint creation fails.");
+    AptosDB::create_checkpoint(
+        source_dir,
+        checkpoint_dir,
+        split_ledger_db,
+        use_sharded_state_merkle_db,
+    )
+    .expect("db checkpoint creation fails.");
 }
 
 /// Runs the benchmark with given parameters.
@@ -98,7 +104,7 @@ pub fn run_benchmark(
     checkpoint_dir: impl AsRef,
     verify_sequence_numbers: bool,
     pruner_config: PrunerConfig,
-    use_state_kv_db: bool,
+    split_ledger_db: bool,
     use_sharded_state_merkle_db: bool,
     pipeline_config: PipelineConfig,
 ) where
@@ -107,13 +113,14 @@ pub fn run_benchmark(
     create_checkpoint(
         source_dir.as_ref(),
         checkpoint_dir.as_ref(),
+        split_ledger_db,
         use_sharded_state_merkle_db,
     );
 
     let (mut config, genesis_key) = aptos_genesis::test_utils::test_config();
     config.storage.dir = checkpoint_dir.as_ref().to_path_buf();
     config.storage.storage_pruner_config = pruner_config;
-    config.storage.rocksdb_configs.use_state_kv_db = use_state_kv_db;
+    config.storage.rocksdb_configs.split_ledger_db = split_ledger_db;
     config.storage.rocksdb_configs.use_sharded_state_merkle_db = use_sharded_state_merkle_db;
 
     let (db, executor) = init_db_and_executor::(&config);
@@ -349,7 +356,7 @@ pub fn add_accounts(
     checkpoint_dir: impl AsRef,
     pruner_config: PrunerConfig,
     verify_sequence_numbers: bool,
-    use_state_kv_db: bool,
+    split_ledger_db: bool,
     use_sharded_state_merkle_db: bool,
     pipeline_config: PipelineConfig,
 ) where
@@ -359,6 +366,7 @@ pub fn add_accounts(
     create_checkpoint(
         source_dir.as_ref(),
         checkpoint_dir.as_ref(),
+        split_ledger_db,
         use_sharded_state_merkle_db,
     );
     add_accounts_impl::(
@@ -369,7 +377,7 @@ pub fn add_accounts(
         checkpoint_dir,
         pruner_config,
         verify_sequence_numbers,
-        use_state_kv_db,
+        split_ledger_db,
         use_sharded_state_merkle_db,
         pipeline_config,
     );
@@ -383,7 +391,7 @@ fn add_accounts_impl(
     output_dir: impl AsRef,
     pruner_config: PrunerConfig,
     verify_sequence_numbers: bool,
-    use_state_kv_db: bool,
+    split_ledger_db: bool,
     use_sharded_state_merkle_db: bool,
     pipeline_config: PipelineConfig,
 ) where
@@ -392,7 +400,7 @@ fn add_accounts_impl(
     let (mut config, genesis_key) = aptos_genesis::test_utils::test_config();
     config.storage.dir = output_dir.as_ref().to_path_buf();
     config.storage.storage_pruner_config = pruner_config;
-    config.storage.rocksdb_configs.use_state_kv_db = use_state_kv_db;
+    config.storage.rocksdb_configs.split_ledger_db = split_ledger_db;
     config.storage.rocksdb_configs.use_sharded_state_merkle_db = use_sharded_state_merkle_db;
     let (db, executor) = init_db_and_executor::(&config);
 
diff --git a/execution/executor-benchmark/src/main.rs b/execution/executor-benchmark/src/main.rs
index 44494f3e48562..4fa2e9cc25373 100644
--- a/execution/executor-benchmark/src/main.rs
+++ b/execution/executor-benchmark/src/main.rs
@@ -124,7 +124,7 @@ struct Opt {
     pruner_opt: PrunerOpt,
 
     #[clap(long)]
-    use_state_kv_db: bool,
+    split_ledger_db: bool,
 
     #[clap(long)]
     use_sharded_state_merkle_db: bool,
@@ -229,7 +229,7 @@ where
                 data_dir,
                 opt.pruner_opt.pruner_config(),
                 opt.verify_sequence_numbers,
-                opt.use_state_kv_db,
+                opt.split_ledger_db,
                 opt.use_sharded_state_merkle_db,
                 opt.pipeline_opt.pipeline_config(),
             );
@@ -254,7 +254,7 @@ where
                 checkpoint_dir,
                 opt.verify_sequence_numbers,
                 opt.pruner_opt.pruner_config(),
-                opt.use_state_kv_db,
+                opt.split_ledger_db,
                 opt.use_sharded_state_merkle_db,
                 opt.pipeline_opt.pipeline_config(),
             );
@@ -273,7 +273,7 @@ where
                 checkpoint_dir,
                 opt.pruner_opt.pruner_config(),
                 opt.verify_sequence_numbers,
-                opt.use_state_kv_db,
+                opt.split_ledger_db,
                 opt.use_sharded_state_merkle_db,
                 opt.pipeline_opt.pipeline_config(),
             );
diff --git a/storage/aptosdb/src/db_debugger/checkpoint/mod.rs b/storage/aptosdb/src/db_debugger/checkpoint/mod.rs
index e71618e31e3ad..d9cb4b03773b4 100644
--- a/storage/aptosdb/src/db_debugger/checkpoint/mod.rs
+++ b/storage/aptosdb/src/db_debugger/checkpoint/mod.rs
@@ -21,7 +21,7 @@ impl Cmd {
         ensure!(!self.output_dir.exists(), "Output dir already exists.");
         fs::create_dir_all(&self.output_dir)?;
 
-        // TODO(grao): Support sharded state merkle db here.
-        AptosDB::create_checkpoint(self.db_dir, self.output_dir, false)
+        // TODO(grao): Support sharded state merkle db and split_ledger_db here.
+        AptosDB::create_checkpoint(self.db_dir, self.output_dir, false, false)
     }
 }
diff --git a/storage/aptosdb/src/db_debugger/examine/print_db_versions.rs b/storage/aptosdb/src/db_debugger/examine/print_db_versions.rs
index 10a8d094616e3..f3384d70f6c3b 100644
--- a/storage/aptosdb/src/db_debugger/examine/print_db_versions.rs
+++ b/storage/aptosdb/src/db_debugger/examine/print_db_versions.rs
@@ -33,13 +33,13 @@ pub struct Cmd {
     db_dir: PathBuf,
 
     #[clap(long)]
-    use_state_kv_db: bool,
+    split_ledger_db: bool,
 }
 
 impl Cmd {
     pub fn run(self) -> Result<()> {
         let rocksdb_config = RocksdbConfigs {
-            use_state_kv_db: self.use_state_kv_db,
+            split_ledger_db: self.split_ledger_db,
             ..Default::default()
         };
         let (ledger_db, state_merkle_db, state_kv_db) = AptosDB::open_dbs(
diff --git a/storage/aptosdb/src/db_debugger/truncate/mod.rs b/storage/aptosdb/src/db_debugger/truncate/mod.rs
index ce9c0f309113d..04c953abfae6d 100644
--- a/storage/aptosdb/src/db_debugger/truncate/mod.rs
+++ b/storage/aptosdb/src/db_debugger/truncate/mod.rs
@@ -47,7 +47,7 @@ pub struct Cmd {
     opt_out_backup_checkpoint: bool,
 
     #[clap(long)]
-    use_state_kv_db: bool,
+    split_ledger_db: bool,
 }
 
 impl Cmd {
@@ -61,14 +61,19 @@ impl Cmd {
             println!("Creating backup at: {:?}", &backup_checkpoint_dir);
             fs::create_dir_all(&backup_checkpoint_dir)?;
             // TODO(grao): Support sharded state merkle db here.
-            AptosDB::create_checkpoint(&self.db_dir, backup_checkpoint_dir, false)?;
+            AptosDB::create_checkpoint(
+                &self.db_dir,
+                backup_checkpoint_dir,
+                self.split_ledger_db,
+                false,
+            )?;
             println!("Done!");
         } else {
             println!("Opted out backup creation!.");
         }
 
         let rocksdb_config = RocksdbConfigs {
-            use_state_kv_db: self.use_state_kv_db,
+            split_ledger_db: self.split_ledger_db,
             ..Default::default()
         };
         let (ledger_db, state_merkle_db, state_kv_db) = AptosDB::open_dbs(
@@ -242,7 +247,7 @@ mod test {
                 ledger_db_batch_size: 15,
                 opt_out_backup_checkpoint: true,
                 backup_checkpoint_dir: None,
-                use_state_kv_db: false,
+                split_ledger_db: false,
             };
 
             cmd.run().unwrap();
diff --git a/storage/aptosdb/src/ledger_db.rs b/storage/aptosdb/src/ledger_db.rs
index 9438d4c7bfda7..a2c46fcf67486 100644
--- a/storage/aptosdb/src/ledger_db.rs
+++ b/storage/aptosdb/src/ledger_db.rs
@@ -133,11 +133,53 @@ impl LedgerDb {
     }
 
     pub(crate) fn create_checkpoint(
-        _db_root_path: impl AsRef,
-        _cp_root_path: impl AsRef,
+        db_root_path: impl AsRef,
+        cp_root_path: impl AsRef,
+        split_ledger_db: bool,
     ) -> Result<()> {
-        // TODO(grao): Implement this function.
-        todo!()
+        let rocksdb_configs = RocksdbConfigs {
+            split_ledger_db,
+            ..Default::default()
+        };
+        let ledger_db = Self::new(db_root_path, rocksdb_configs, /*readonly=*/ false)?;
+        let cp_ledger_db_folder = cp_root_path.as_ref().join(LEDGER_DB_FOLDER_NAME);
+
+        info!(
+            split_ledger_db = split_ledger_db,
+            "Creating ledger_db checkpoint at: {cp_ledger_db_folder:?}"
+        );
+
+        std::fs::remove_dir_all(&cp_ledger_db_folder).unwrap_or(());
+        if split_ledger_db {
+            std::fs::create_dir_all(&cp_ledger_db_folder).unwrap_or(());
+        }
+
+        ledger_db
+            .metadata_db()
+            .create_checkpoint(Self::metadata_db_path(
+                cp_root_path.as_ref(),
+                split_ledger_db,
+            ))?;
+
+        if split_ledger_db {
+            ledger_db
+                .event_db()
+                .create_checkpoint(cp_ledger_db_folder.join(EVENT_DB_NAME))?;
+            ledger_db
+                .transaction_accumulator_db()
+                .create_checkpoint(cp_ledger_db_folder.join(TRANSACTION_ACCUMULATOR_DB_NAME))?;
+            ledger_db
+                .transaction_db()
+                .create_checkpoint(cp_ledger_db_folder.join(TRANSACTION_DB_NAME))?;
+            ledger_db
+                .transaction_info_db()
+                .create_checkpoint(cp_ledger_db_folder.join(TRANSACTION_INFO_DB_NAME))?;
+            ledger_db
+                .write_set_db()
+                .create_checkpoint(cp_ledger_db_folder.join(WRITE_SET_DB_NAME))?;
+        }
+
+        Ok(())
     }
 
     pub(crate) fn write_pruner_progress(&self, version: Version) -> Result<()> {
diff --git a/storage/aptosdb/src/lib.rs b/storage/aptosdb/src/lib.rs
index d43f1741d0e91..50885c6c22a6b 100644
--- a/storage/aptosdb/src/lib.rs
+++ b/storage/aptosdb/src/lib.rs
@@ -703,27 +703,21 @@ impl AptosDB {
     pub fn create_checkpoint(
         db_path: impl AsRef,
         cp_path: impl AsRef,
+        use_split_ledger_db: bool,
         use_sharded_state_merkle_db: bool,
     ) -> Result<()> {
         let start = Instant::now();
-        let ledger_db_path = db_path.as_ref().join(LEDGER_DB_NAME);
-        let ledger_cp_path = cp_path.as_ref().join(LEDGER_DB_NAME);
 
-        info!("Creating ledger_db checkpoint at: {ledger_cp_path:?}");
-
-        std::fs::remove_dir_all(&ledger_cp_path).unwrap_or(());
-
-        // Weird enough, checkpoint doesn't work with readonly or secondary mode (gets stuck).
-        // https://github.com/facebook/rocksdb/issues/11167
-        let ledger_db = aptos_schemadb::DB::open(
-            ledger_db_path,
-            LEDGER_DB_NAME,
-            ledger_db_column_families(),
-            &aptos_schemadb::Options::default(),
-        )?;
-        ledger_db.create_checkpoint(ledger_cp_path)?;
+        info!(
+            use_split_ledger_db = use_split_ledger_db,
+            use_sharded_state_merkle_db = use_sharded_state_merkle_db,
+            "Creating checkpoint for AptosDB."
+        );
 
-        StateKvDb::create_checkpoint(db_path.as_ref(), cp_path.as_ref())?;
+        LedgerDb::create_checkpoint(db_path.as_ref(), cp_path.as_ref(), use_split_ledger_db)?;
+        if use_split_ledger_db {
+            StateKvDb::create_checkpoint(db_path.as_ref(), cp_path.as_ref())?;
+        }
         StateMerkleDb::create_checkpoint(
             db_path.as_ref(),
             cp_path.as_ref(),
diff --git a/storage/aptosdb/src/state_kv_db.rs b/storage/aptosdb/src/state_kv_db.rs
index fb20066ee267b..d37a385343168 100644
--- a/storage/aptosdb/src/state_kv_db.rs
+++ b/storage/aptosdb/src/state_kv_db.rs
@@ -38,7 +38,7 @@ impl StateKvDb {
         readonly: bool,
         ledger_db: Arc,
     ) -> Result {
-        if !rocksdb_configs.use_state_kv_db {
+        if !rocksdb_configs.split_ledger_db {
             info!("State K/V DB is not enabled!");
             return Ok(Self {
                 state_kv_metadata_db: Arc::clone(&ledger_db),
diff --git a/storage/backup/backup-cli/src/utils/mod.rs b/storage/backup/backup-cli/src/utils/mod.rs
index 3067cf0f6c825..948b05f9be0f4 100644
--- a/storage/backup/backup-cli/src/utils/mod.rs
+++ b/storage/backup/backup-cli/src/utils/mod.rs
@@ -69,8 +69,6 @@ pub struct RocksdbOpt {
     #[clap(long, hidden(true))]
     split_ledger_db: bool,
     #[clap(long, hidden(true))]
-    use_state_kv_db: bool,
-    #[clap(long, hidden(true))]
     use_sharded_state_merkle_db: bool,
     #[clap(long, hidden(true), default_value = "5000")]
     state_kv_db_max_open_files: i32,
@@ -100,7 +98,6 @@ impl From for RocksdbConfigs {
                 ..Default::default()
             },
             split_ledger_db: opt.split_ledger_db,
-            use_state_kv_db: opt.use_state_kv_db,
             use_sharded_state_merkle_db: opt.use_sharded_state_merkle_db,
             state_kv_db_config: RocksdbConfig {
                 max_open_files: opt.state_kv_db_max_open_files,
diff --git a/testsuite/single_node_performance.py b/testsuite/single_node_performance.py
index 301af0a791232..deeea5f6d4e17 100755
--- a/testsuite/single_node_performance.py
+++ b/testsuite/single_node_performance.py
@@ -222,7 +222,7 @@ def print_table(
 warnings = []
 
 with tempfile.TemporaryDirectory() as tmpdirname:
-    create_db_command = f"cargo run {BUILD_FLAG} -- --block-size {BLOCK_SIZE} --concurrency-level {CONCURRENCY_LEVEL} --use-state-kv-db --use-sharded-state-merkle-db create-db --data-dir {tmpdirname}/db --num-accounts {NUM_ACCOUNTS}"
+    create_db_command = f"cargo run {BUILD_FLAG} -- --block-size {BLOCK_SIZE} --concurrency-level {CONCURRENCY_LEVEL} --split-ledger-db --use-sharded-state-merkle-db create-db --data-dir {tmpdirname}/db --num-accounts {NUM_ACCOUNTS}"
     output = execute_command(create_db_command)
 
     results = []
@@ -237,7 +237,7 @@ def print_table(
         executor_type = "native" if use_native_executor else "VM"
 
         use_native_executor_str = "--use-native-executor" if use_native_executor else ""
-        common_command_suffix = f"{use_native_executor_str} --generate-then-execute --transactions-per-sender 1 --block-size {cur_block_size} --use-state-kv-db --use-sharded-state-merkle-db run-executor --transaction-type {transaction_type} --module-working-set-size {module_working_set_size} --main-signer-accounts {MAIN_SIGNER_ACCOUNTS} --additional-dst-pool-accounts {ADDITIONAL_DST_POOL_ACCOUNTS} --data-dir {tmpdirname}/db  --checkpoint-dir {tmpdirname}/cp"
+        common_command_suffix = f"{use_native_executor_str} --generate-then-execute --transactions-per-sender 1 --block-size {cur_block_size} --split-ledger-db --use-sharded-state-merkle-db run-executor --transaction-type {transaction_type} --module-working-set-size {module_working_set_size} --main-signer-accounts {MAIN_SIGNER_ACCOUNTS} --additional-dst-pool-accounts {ADDITIONAL_DST_POOL_ACCOUNTS} --data-dir {tmpdirname}/db  --checkpoint-dir {tmpdirname}/cp"
 
         concurrency_level_results = {}
 
diff --git a/testsuite/smoke-test/src/genesis.rs b/testsuite/smoke-test/src/genesis.rs
index abf21ef8bb505..75ae619ace1bd 100644
--- a/testsuite/smoke-test/src/genesis.rs
+++ b/testsuite/smoke-test/src/genesis.rs
@@ -271,7 +271,7 @@ async fn test_genesis_transaction_flow() {
         backup_path.path(),
         db_dir.as_path(),
         &[waypoint],
-        node.config().storage.rocksdb_configs.use_state_kv_db,
+        node.config().storage.rocksdb_configs.split_ledger_db,
         None,
     );
 
diff --git a/testsuite/smoke-test/src/storage.rs b/testsuite/smoke-test/src/storage.rs
index 8c1cfc99d684c..a40490037e639 100644
--- a/testsuite/smoke-test/src/storage.rs
+++ b/testsuite/smoke-test/src/storage.rs
@@ -131,7 +131,7 @@ async fn test_db_restore() {
         backup_path.path(),
         db_dir.as_path(),
         &[],
-        node0_config.storage.rocksdb_configs.use_state_kv_db,
+        node0_config.storage.rocksdb_configs.split_ledger_db,
         None,
     );
 
@@ -408,7 +408,7 @@ pub(crate) fn db_restore(
     backup_path: &Path,
     db_path: &Path,
     trusted_waypoints: &[Waypoint],
-    use_state_kv_db: bool,
+    split_ledger_db: bool,
     target_verion: Option, /* target version should be same as epoch ending version to start a node */
 ) {
     let now = Instant::now();
@@ -424,8 +424,8 @@ pub(crate) fn db_restore(
         cmd.arg(&w.to_string());
     });
 
-    if use_state_kv_db {
-        cmd.arg("--use-state-kv-db");
+    if split_ledger_db {
+        cmd.arg("--split-ledger-db");
     }
     if let Some(version) = target_verion {
         cmd.arg("--target-version");

From bb0de9837cf2a44652898871231b4f4139a1b916 Mon Sep 17 00:00:00 2001
From: 0xTraderTrou <109982124+0xTraderTrou@users.noreply.github.com>
Date: Wed, 14 Jun 2023 03:24:44 +0700
Subject: [PATCH 154/200] feat: added bcsSerializeU256 (#8619)

---
 ecosystem/typescript/sdk/src/bcs/helper.ts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/ecosystem/typescript/sdk/src/bcs/helper.ts b/ecosystem/typescript/sdk/src/bcs/helper.ts
index 21059c0ae43b6..327e29449263e 100644
--- a/ecosystem/typescript/sdk/src/bcs/helper.ts
+++ b/ecosystem/typescript/sdk/src/bcs/helper.ts
@@ -81,6 +81,12 @@ export function bcsSerializeU128(value: AnyNumber): Bytes {
   return serializer.getBytes();
 }
 
+export function bcsSerializeU256(value: AnyNumber): Bytes {
+  const serializer = new Serializer();
+  serializer.serializeU256(value);
+  return serializer.getBytes();
+}
+
 export function bcsSerializeBool(value: boolean): Bytes {
   const serializer = new Serializer();
   serializer.serializeBool(value);

From 166a931d87a217b05f05e49ad6568b32fd969d19 Mon Sep 17 00:00:00 2001
From: aldenhu 
Date: Fri, 9 Jun 2023 19:37:55 +0000
Subject: [PATCH 155/200] refactor: storage gas parameters: load onchain config
 from within constructors

Whether or not to load the curve values will be depending on the gas
feature verion, so refactoring to bring the logic consolidated into the
StorageGasParameters constructors.
---
 .../aptos-gas/src/transaction/storage.rs      | 60 ++++++++++++-------
 aptos-move/aptos-vm/src/aptos_vm_impl.rs      | 14 +----
 2 files changed, 41 insertions(+), 33 deletions(-)

diff --git a/aptos-move/aptos-gas/src/transaction/storage.rs b/aptos-move/aptos-gas/src/transaction/storage.rs
index 8aa7c38593b69..bbfee866c5c8d 100644
--- a/aptos-move/aptos-gas/src/transaction/storage.rs
+++ b/aptos-move/aptos-gas/src/transaction/storage.rs
@@ -3,7 +3,9 @@
 
 use crate::{AptosGasParameters, LATEST_GAS_FEATURE_VERSION};
 use aptos_types::{
-    on_chain_config::StorageGasSchedule, state_store::state_key::StateKey, write_set::WriteOp,
+    on_chain_config::{ConfigStorage, OnChainConfig, StorageGasSchedule},
+    state_store::state_key::StateKey,
+    write_set::WriteOp,
 };
 use aptos_vm_types::{change_set::VMChangeSet, check_change_set::CheckChangeSet};
 use move_core_types::{
@@ -101,21 +103,9 @@ impl StoragePricingV2 {
         storage_gas_schedule: &StorageGasSchedule,
         gas_params: &AptosGasParameters,
     ) -> Self {
-        assert!(feature_version > 0);
-
-        let free_write_bytes_quota = if feature_version >= 5 {
-            gas_params.txn.free_write_bytes_quota
-        } else if feature_version >= 3 {
-            1024.into()
-        } else {
-            // for feature_version 2 and below `free_write_bytes_quota` won't be used anyway
-            // but let's set it properly to reduce confusion.
-            0.into()
-        };
-
         Self {
             feature_version,
-            free_write_bytes_quota,
+            free_write_bytes_quota: Self::get_free_write_bytes_quota(feature_version, gas_params),
             per_item_read: storage_gas_schedule.per_item_read.into(),
             per_item_create: storage_gas_schedule.per_item_create.into(),
             per_item_write: storage_gas_schedule.per_item_write.into(),
@@ -125,6 +115,18 @@ impl StoragePricingV2 {
         }
     }
 
+    fn get_free_write_bytes_quota(
+        feature_version: u64,
+        gas_params: &AptosGasParameters,
+    ) -> NumBytes {
+        match feature_version {
+            0 => unreachable!("PricingV2 not applicable for feature version 0"),
+            1..=2 => 0.into(),
+            3..=4 => 1024.into(),
+            5.. => gas_params.txn.free_write_bytes_quota,
+        }
+    }
+
     fn write_op_size(&self, key: &StateKey, value: &[u8]) -> NumBytes {
         let value_size = NumBytes::new(value.len() as u64);
 
@@ -171,6 +173,26 @@ pub enum StoragePricing {
 }
 
 impl StoragePricing {
+    pub fn new(
+        feature_version: u64,
+        gas_params: &AptosGasParameters,
+        config_storage: &impl ConfigStorage,
+    ) -> StoragePricing {
+        use StoragePricing::*;
+
+        match feature_version {
+            0 => V1(StoragePricingV1::new(gas_params)),
+            1.. => match StorageGasSchedule::fetch_config(config_storage) {
+                None => V1(StoragePricingV1::new(gas_params)),
+                Some(schedule) => V2(StoragePricingV2::new(
+                    feature_version,
+                    &schedule,
+                    gas_params,
+                )),
+            },
+        }
+    }
+
     pub fn calculate_read_gas(&self, resource_exists: bool, bytes_loaded: NumBytes) -> InternalGas {
         use StoragePricing::*;
 
@@ -309,15 +331,9 @@ impl StorageGasParameters {
     pub fn new(
         feature_version: u64,
         gas_params: &AptosGasParameters,
-        storage_gas_schedule: Option<&StorageGasSchedule>,
+        config_storage: &impl ConfigStorage,
     ) -> Self {
-        let pricing = match storage_gas_schedule {
-            Some(schedule) => {
-                StoragePricing::V2(StoragePricingV2::new(feature_version, schedule, gas_params))
-            },
-            None => StoragePricing::V1(StoragePricingV1::new(gas_params)),
-        };
-
+        let pricing = StoragePricing::new(feature_version, gas_params, config_storage);
         let change_set_configs = ChangeSetConfigs::new(feature_version, gas_params);
 
         Self {
diff --git a/aptos-move/aptos-vm/src/aptos_vm_impl.rs b/aptos-move/aptos-vm/src/aptos_vm_impl.rs
index 724b315273e3e..2e54f2f2a9fee 100644
--- a/aptos-move/aptos-vm/src/aptos_vm_impl.rs
+++ b/aptos-move/aptos-vm/src/aptos_vm_impl.rs
@@ -22,7 +22,7 @@ use aptos_types::{
     chain_id::ChainId,
     on_chain_config::{
         ApprovedExecutionHashes, ConfigurationResource, FeatureFlag, Features, GasSchedule,
-        GasScheduleV2, OnChainConfig, StorageGasSchedule, TimedFeatures, Version,
+        GasScheduleV2, OnChainConfig, TimedFeatures, Version,
     },
     transaction::{AbortInfo, ExecutionStatus, Multisig, TransactionStatus},
     vm_status::{StatusCode, VMStatus},
@@ -84,16 +84,8 @@ impl AptosVMImpl {
             gas_config(&storage);
 
         let storage_gas_params = if let Some(gas_params) = &mut gas_params {
-            let storage_gas_schedule = match gas_feature_version {
-                0 => None,
-                _ => StorageGasSchedule::fetch_config(&storage),
-            };
-
-            let storage_gas_params = StorageGasParameters::new(
-                gas_feature_version,
-                gas_params,
-                storage_gas_schedule.as_ref(),
-            );
+            let storage_gas_params =
+                StorageGasParameters::new(gas_feature_version, gas_params, &storage);
 
             if let StoragePricing::V2(pricing) = &storage_gas_params.pricing {
                 // Overwrite table io gas parameters with global io pricing.

From 38f60b316a74042f0b2e17c1e518ddd337f14d20 Mon Sep 17 00:00:00 2001
From: aldenhu 
Date: Fri, 9 Jun 2023 21:39:15 +0000
Subject: [PATCH 156/200] Deprecate the storage gas curves

On gas feature version 10, skip loading the storage gas schedule from
the storage curves. Rather, the gas schedule is updated with the gas
curve initial values loaded in a few (static) entries that don't
change with the growth of the global state storage.
---
 ...ansaction_with_entry_function_payload.json |  2 +-
 ...e_when_start_version_is_not_specified.json | 16 ++++----
 aptos-move/aptos-gas/src/gas_meter.rs         |  4 +-
 aptos-move/aptos-gas/src/params.rs            |  1 +
 aptos-move/aptos-gas/src/transaction/mod.rs   | 24 ++++++-----
 .../aptos-gas/src/transaction/storage.rs      | 40 +++++++++++++------
 ..._tests__create_account__create_account.exp |  2 +-
 ...__tests__data_store__borrow_after_move.exp |  4 +-
 ...__tests__data_store__change_after_move.exp |  4 +-
 ...s__data_store__move_from_across_blocks.exp |  6 +--
 ...s__module_publishing__duplicate_module.exp |  2 +-
 ...e_publishing__layout_compatible_module.exp |  2 +-
 ...incompatible_module_with_changed_field.exp |  2 +-
 ...out_incompatible_module_with_new_field.exp |  2 +-
 ...incompatible_module_with_removed_field.exp |  2 +-
 ...ncompatible_module_with_removed_struct.exp |  2 +-
 ..._publishing__linking_compatible_module.exp |  2 +-
 ...g_incompatible_module_with_added_param.exp |  2 +-
 ...incompatible_module_with_changed_param.exp |  2 +-
 ...ncompatible_module_with_removed_pub_fn.exp |  2 +-
 ...lishing__test_publishing_allow_modules.exp |  2 +-
 ..._test_publishing_modules_proper_sender.exp |  2 +-
 ...ests__verify_txn__test_open_publishing.exp |  6 +--
 23 files changed, 78 insertions(+), 55 deletions(-)

diff --git a/api/goldens/aptos_api__tests__transactions_test__test_get_transactions_output_user_transaction_with_entry_function_payload.json b/api/goldens/aptos_api__tests__transactions_test__test_get_transactions_output_user_transaction_with_entry_function_payload.json
index f391eb2756dfe..43518fccbf8f6 100644
--- a/api/goldens/aptos_api__tests__transactions_test__test_get_transactions_output_user_transaction_with_entry_function_payload.json
+++ b/api/goldens/aptos_api__tests__transactions_test__test_get_transactions_output_user_transaction_with_entry_function_payload.json
@@ -114,7 +114,7 @@
     "state_change_hash": "",
     "event_root_hash": "",
     "state_checkpoint_hash": null,
-    "gas_used": "16",
+    "gas_used": "6",
     "success": true,
     "vm_status": "Executed successfully",
     "accumulator_root_hash": "",
diff --git a/api/goldens/aptos_api__tests__transactions_test__test_get_transactions_returns_last_page_when_start_version_is_not_specified.json b/api/goldens/aptos_api__tests__transactions_test__test_get_transactions_returns_last_page_when_start_version_is_not_specified.json
index d2034bc4b4f8b..9952e5d835109 100644
--- a/api/goldens/aptos_api__tests__transactions_test__test_get_transactions_returns_last_page_when_start_version_is_not_specified.json
+++ b/api/goldens/aptos_api__tests__transactions_test__test_get_transactions_returns_last_page_when_start_version_is_not_specified.json
@@ -119,7 +119,7 @@
     "state_change_hash": "",
     "event_root_hash": "",
     "state_checkpoint_hash": null,
-    "gas_used": "16",
+    "gas_used": "6",
     "success": true,
     "vm_status": "Executed successfully",
     "accumulator_root_hash": "",
@@ -397,7 +397,7 @@
     "state_change_hash": "",
     "event_root_hash": "",
     "state_checkpoint_hash": null,
-    "gas_used": "16",
+    "gas_used": "6",
     "success": true,
     "vm_status": "Executed successfully",
     "accumulator_root_hash": "",
@@ -675,7 +675,7 @@
     "state_change_hash": "",
     "event_root_hash": "",
     "state_checkpoint_hash": null,
-    "gas_used": "16",
+    "gas_used": "6",
     "success": true,
     "vm_status": "Executed successfully",
     "accumulator_root_hash": "",
@@ -953,7 +953,7 @@
     "state_change_hash": "",
     "event_root_hash": "",
     "state_checkpoint_hash": null,
-    "gas_used": "16",
+    "gas_used": "6",
     "success": true,
     "vm_status": "Executed successfully",
     "accumulator_root_hash": "",
@@ -1231,7 +1231,7 @@
     "state_change_hash": "",
     "event_root_hash": "",
     "state_checkpoint_hash": null,
-    "gas_used": "16",
+    "gas_used": "6",
     "success": true,
     "vm_status": "Executed successfully",
     "accumulator_root_hash": "",
@@ -1509,7 +1509,7 @@
     "state_change_hash": "",
     "event_root_hash": "",
     "state_checkpoint_hash": null,
-    "gas_used": "16",
+    "gas_used": "6",
     "success": true,
     "vm_status": "Executed successfully",
     "accumulator_root_hash": "",
@@ -1787,7 +1787,7 @@
     "state_change_hash": "",
     "event_root_hash": "",
     "state_checkpoint_hash": null,
-    "gas_used": "16",
+    "gas_used": "6",
     "success": true,
     "vm_status": "Executed successfully",
     "accumulator_root_hash": "",
@@ -2065,7 +2065,7 @@
     "state_change_hash": "",
     "event_root_hash": "",
     "state_checkpoint_hash": null,
-    "gas_used": "16",
+    "gas_used": "6",
     "success": true,
     "vm_status": "Executed successfully",
     "accumulator_root_hash": "",
diff --git a/aptos-move/aptos-gas/src/gas_meter.rs b/aptos-move/aptos-gas/src/gas_meter.rs
index f27088a44907a..8ec9b746020cc 100644
--- a/aptos-move/aptos-gas/src/gas_meter.rs
+++ b/aptos-move/aptos-gas/src/gas_meter.rs
@@ -33,6 +33,8 @@ use move_vm_types::{
 use std::collections::BTreeMap;
 
 // Change log:
+// - V10
+//   - Storage gas charges (excluding "storage fees") stop respecting the storage gas curves
 // - V9
 //   - Accurate tracking of the cost of loading resource groups
 // - V8
@@ -61,7 +63,7 @@ use std::collections::BTreeMap;
 //       global operations.
 // - V1
 //   - TBA
-pub const LATEST_GAS_FEATURE_VERSION: u64 = 9;
+pub const LATEST_GAS_FEATURE_VERSION: u64 = 10;
 
 pub(crate) const EXECUTION_GAS_MULTIPLIER: u64 = 20;
 
diff --git a/aptos-move/aptos-gas/src/params.rs b/aptos-move/aptos-gas/src/params.rs
index 5aa7079b82a09..a394ba691fc7d 100644
--- a/aptos-move/aptos-gas/src/params.rs
+++ b/aptos-move/aptos-gas/src/params.rs
@@ -9,6 +9,7 @@ macro_rules! define_gas_parameters_extract_key_at_version {
     ({ $($ver: pat => $key: literal),+ }, $cur_ver: expr) => {
         match $cur_ver {
             $($ver => Some($key)),+,
+            #[allow(unreachable_patterns)]
             _ => None,
         }
     }
diff --git a/aptos-move/aptos-gas/src/transaction/mod.rs b/aptos-move/aptos-gas/src/transaction/mod.rs
index f2f9533347abf..df8f71898ef3f 100644
--- a/aptos-move/aptos-gas/src/transaction/mod.rs
+++ b/aptos-move/aptos-gas/src/transaction/mod.rs
@@ -79,18 +79,22 @@ crate::params::define_gas_parameters!(
             GAS_SCALING_FACTOR
         ],
         // Gas Parameters for reading data from storage.
-        [load_data_base: InternalGas, "load_data.base", 16_000],
         [
-            load_data_per_byte: InternalGasPerByte,
-            "load_data.per_byte",
-            1_000
+            storage_io_per_state_slot_read: InternalGasPerArg,
+            { 0..=9 => "load_data.base", 10.. => "storage_io_per_state_slot_read"},
+            300_000,
+        ],
+        [
+            storage_io_per_state_byte_read: InternalGasPerByte,
+            { 0..=9 => "load_data.per_byte", 10.. => "storage_io_per_state_byte_read"},
+            300,
         ],
         [load_data_failure: InternalGas, "load_data.failure", 0],
         // Gas parameters for writing data to storage.
         [
-            write_data_per_op: InternalGasPerArg,
-            "write_data.per_op",
-            160_000
+            storage_io_per_state_slot_write: InternalGasPerArg,
+            { 0..=9 => "write_data.per_op", 10.. => "storage_io_per_state_slot_write"},
+            300_000,
         ],
         [
             write_data_per_new_item: InternalGasPerArg,
@@ -98,9 +102,9 @@ crate::params::define_gas_parameters!(
             1_280_000
         ],
         [
-            write_data_per_byte_in_key: InternalGasPerByte,
-            "write_data.per_byte_in_key",
-            10_000
+            storage_io_per_state_byte_write: InternalGasPerByte,
+            { 0..=9 => "write_data.per_byte_in_key", 10.. => "storage_io_per_state_byte_write"},
+            5_000
         ],
         [
             write_data_per_byte_in_val: InternalGasPerByte,
diff --git a/aptos-move/aptos-gas/src/transaction/storage.rs b/aptos-move/aptos-gas/src/transaction/storage.rs
index bbfee866c5c8d..00197e0bb111d 100644
--- a/aptos-move/aptos-gas/src/transaction/storage.rs
+++ b/aptos-move/aptos-gas/src/transaction/storage.rs
@@ -28,12 +28,12 @@ pub struct StoragePricingV1 {
 impl StoragePricingV1 {
     fn new(gas_params: &AptosGasParameters) -> Self {
         Self {
-            write_data_per_op: gas_params.txn.write_data_per_op,
+            write_data_per_op: gas_params.txn.storage_io_per_state_slot_write,
             write_data_per_new_item: gas_params.txn.write_data_per_new_item,
-            write_data_per_byte_in_key: gas_params.txn.write_data_per_byte_in_key,
+            write_data_per_byte_in_key: gas_params.txn.storage_io_per_state_byte_write,
             write_data_per_byte_in_val: gas_params.txn.write_data_per_byte_in_val,
-            load_data_base: gas_params.txn.load_data_base,
-            load_data_per_byte: gas_params.txn.load_data_per_byte,
+            load_data_base: gas_params.txn.storage_io_per_state_slot_read * NumArgs::new(1),
+            load_data_per_byte: gas_params.txn.storage_io_per_state_byte_read,
             load_data_failure: gas_params.txn.load_data_failure,
         }
     }
@@ -91,14 +91,10 @@ pub struct StoragePricingV2 {
 
 impl StoragePricingV2 {
     pub fn zeros() -> Self {
-        Self::new(
-            LATEST_GAS_FEATURE_VERSION,
-            &StorageGasSchedule::zeros(),
-            &AptosGasParameters::zeros(),
-        )
+        Self::new_without_storage_curves(LATEST_GAS_FEATURE_VERSION, &AptosGasParameters::zeros())
     }
 
-    pub fn new(
+    pub fn new_with_storage_curves(
         feature_version: u64,
         storage_gas_schedule: &StorageGasSchedule,
         gas_params: &AptosGasParameters,
@@ -115,6 +111,22 @@ impl StoragePricingV2 {
         }
     }
 
+    pub fn new_without_storage_curves(
+        feature_version: u64,
+        gas_params: &AptosGasParameters,
+    ) -> Self {
+        Self {
+            feature_version,
+            free_write_bytes_quota: Self::get_free_write_bytes_quota(feature_version, gas_params),
+            per_item_read: gas_params.txn.storage_io_per_state_slot_read,
+            per_item_create: gas_params.txn.storage_io_per_state_slot_write,
+            per_item_write: gas_params.txn.storage_io_per_state_slot_write,
+            per_byte_read: gas_params.txn.storage_io_per_state_byte_read,
+            per_byte_create: gas_params.txn.storage_io_per_state_byte_write,
+            per_byte_write: gas_params.txn.storage_io_per_state_byte_write,
+        }
+    }
+
     fn get_free_write_bytes_quota(
         feature_version: u64,
         gas_params: &AptosGasParameters,
@@ -182,14 +194,18 @@ impl StoragePricing {
 
         match feature_version {
             0 => V1(StoragePricingV1::new(gas_params)),
-            1.. => match StorageGasSchedule::fetch_config(config_storage) {
+            1..=9 => match StorageGasSchedule::fetch_config(config_storage) {
                 None => V1(StoragePricingV1::new(gas_params)),
-                Some(schedule) => V2(StoragePricingV2::new(
+                Some(schedule) => V2(StoragePricingV2::new_with_storage_curves(
                     feature_version,
                     &schedule,
                     gas_params,
                 )),
             },
+            10.. => V2(StoragePricingV2::new_without_storage_curves(
+                feature_version,
+                gas_params,
+            )),
         }
     }
 
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__create_account__create_account.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__create_account__create_account.exp
index 562502050d9bf..84263f8206da2 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__create_account__create_account.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__create_account__create_account.exp
@@ -30,7 +30,7 @@ Ok(
             events: [
                 ContractEvent { key: EventKey { creation_number: 0, account_address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1 }, index: 0, type: Struct(StructTag { address: 0000000000000000000000000000000000000000000000000000000000000001, module: Identifier("account"), name: Identifier("CoinRegisterEvent"), type_params: [] }), event_data: "00000000000000000000000000000000000000000000000000000000000000010a6170746f735f636f696e094170746f73436f696e" },
             ],
-            gas_used: 16,
+            gas_used: 6,
             status: Keep(
                 Success,
             ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__borrow_after_move.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__borrow_after_move.exp
index 2c06ccd10ae88..46f394a775780 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__borrow_after_move.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__borrow_after_move.exp
@@ -22,7 +22,7 @@ Ok(
                 ),
             ),
             events: [],
-            gas_used: 7,
+            gas_used: 2,
             status: Keep(
                 Success,
             ),
@@ -82,7 +82,7 @@ Ok(
                 ),
             ),
             events: [],
-            gas_used: 7,
+            gas_used: 3,
             status: Keep(
                 Success,
             ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__change_after_move.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__change_after_move.exp
index 0631757ebbff4..34e03fa9b7997 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__change_after_move.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__change_after_move.exp
@@ -22,7 +22,7 @@ Ok(
                 ),
             ),
             events: [],
-            gas_used: 7,
+            gas_used: 2,
             status: Keep(
                 Success,
             ),
@@ -82,7 +82,7 @@ Ok(
                 ),
             ),
             events: [],
-            gas_used: 7,
+            gas_used: 3,
             status: Keep(
                 Success,
             ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__move_from_across_blocks.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__move_from_across_blocks.exp
index 93307a8dc18fb..58b3ad0ddb48e 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__move_from_across_blocks.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__move_from_across_blocks.exp
@@ -22,7 +22,7 @@ Ok(
                 ),
             ),
             events: [],
-            gas_used: 7,
+            gas_used: 2,
             status: Keep(
                 Success,
             ),
@@ -82,7 +82,7 @@ Ok(
                 ),
             ),
             events: [],
-            gas_used: 7,
+            gas_used: 3,
             status: Keep(
                 Success,
             ),
@@ -227,7 +227,7 @@ Ok(
                 ),
             ),
             events: [],
-            gas_used: 7,
+            gas_used: 3,
             status: Keep(
                 Success,
             ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__duplicate_module.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__duplicate_module.exp
index 1714537199d03..c24a0e1dd2c19 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__duplicate_module.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__duplicate_module.exp
@@ -22,7 +22,7 @@ Ok(
                 ),
             ),
             events: [],
-            gas_used: 7,
+            gas_used: 2,
             status: Keep(
                 Success,
             ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_compatible_module.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_compatible_module.exp
index ee51e8228631b..ee8f4d0153450 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_compatible_module.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_compatible_module.exp
@@ -22,7 +22,7 @@ Ok(
                 ),
             ),
             events: [],
-            gas_used: 7,
+            gas_used: 2,
             status: Keep(
                 Success,
             ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_changed_field.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_changed_field.exp
index 3d6a6852dc42e..8bd4038e2d42a 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_changed_field.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_changed_field.exp
@@ -22,7 +22,7 @@ Ok(
                 ),
             ),
             events: [],
-            gas_used: 7,
+            gas_used: 2,
             status: Keep(
                 Success,
             ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_new_field.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_new_field.exp
index 3d6a6852dc42e..8bd4038e2d42a 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_new_field.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_new_field.exp
@@ -22,7 +22,7 @@ Ok(
                 ),
             ),
             events: [],
-            gas_used: 7,
+            gas_used: 2,
             status: Keep(
                 Success,
             ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_removed_field.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_removed_field.exp
index 3d6a6852dc42e..8bd4038e2d42a 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_removed_field.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_removed_field.exp
@@ -22,7 +22,7 @@ Ok(
                 ),
             ),
             events: [],
-            gas_used: 7,
+            gas_used: 2,
             status: Keep(
                 Success,
             ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_removed_struct.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_removed_struct.exp
index 3d6a6852dc42e..8bd4038e2d42a 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_removed_struct.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_removed_struct.exp
@@ -22,7 +22,7 @@ Ok(
                 ),
             ),
             events: [],
-            gas_used: 7,
+            gas_used: 2,
             status: Keep(
                 Success,
             ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_compatible_module.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_compatible_module.exp
index ee51e8228631b..ee8f4d0153450 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_compatible_module.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_compatible_module.exp
@@ -22,7 +22,7 @@ Ok(
                 ),
             ),
             events: [],
-            gas_used: 7,
+            gas_used: 2,
             status: Keep(
                 Success,
             ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_added_param.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_added_param.exp
index afa912978f8de..8668be844e8f5 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_added_param.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_added_param.exp
@@ -22,7 +22,7 @@ Ok(
                 ),
             ),
             events: [],
-            gas_used: 7,
+            gas_used: 2,
             status: Keep(
                 Success,
             ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_changed_param.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_changed_param.exp
index 62125bf1c6b61..5eb0507d71852 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_changed_param.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_changed_param.exp
@@ -22,7 +22,7 @@ Ok(
                 ),
             ),
             events: [],
-            gas_used: 7,
+            gas_used: 2,
             status: Keep(
                 Success,
             ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_removed_pub_fn.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_removed_pub_fn.exp
index afa912978f8de..8668be844e8f5 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_removed_pub_fn.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_removed_pub_fn.exp
@@ -22,7 +22,7 @@ Ok(
                 ),
             ),
             events: [],
-            gas_used: 7,
+            gas_used: 2,
             status: Keep(
                 Success,
             ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__test_publishing_allow_modules.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__test_publishing_allow_modules.exp
index 450e0a735b5a2..595e781ad7ea7 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__test_publishing_allow_modules.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__test_publishing_allow_modules.exp
@@ -22,7 +22,7 @@ Ok(
                 ),
             ),
             events: [],
-            gas_used: 7,
+            gas_used: 2,
             status: Keep(
                 Success,
             ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__test_publishing_modules_proper_sender.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__test_publishing_modules_proper_sender.exp
index 514bd8a87900e..ee6cb35fe097c 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__test_publishing_modules_proper_sender.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__test_publishing_modules_proper_sender.exp
@@ -22,7 +22,7 @@ Ok(
                 ),
             ),
             events: [],
-            gas_used: 7,
+            gas_used: 2,
             status: Keep(
                 Success,
             ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__verify_txn__test_open_publishing.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__verify_txn__test_open_publishing.exp
index 8a6c83e9dbd9f..05f6d9dbac873 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__verify_txn__test_open_publishing.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__verify_txn__test_open_publishing.exp
@@ -16,7 +16,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 01000000000000000000000000000000000000000000000000000000000000000104636f696e09436f696e53746f7265010700000000000000000000000000000000000000000000000000000000000000010a6170746f735f636f696e094170746f73436f696e00 },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: Modification(f4039a3b000000000000000000000000000000000000000000f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100000000000000000000000000000000f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1),
+                            }: Modification(e8059a3b000000000000000000000000000000000000000000f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100000000000000000000000000000000f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1),
                             StateKey {
                                 inner: AccessPath(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 010000000000000000000000000000000000000000000000000000000000000001076163636f756e74074163636f756e7400 },
@@ -64,13 +64,13 @@ Ok(
                                     ],
                                 },
                                 hash: OnceCell(Uninit),
-                            }: Modification(f31af505000000000100000000000000),
+                            }: Modification(e71cf505000000000100000000000000),
                         },
                     },
                 ),
             ),
             events: [],
-            gas_used: 507,
+            gas_used: 502,
             status: Keep(
                 Success,
             ),

From c1f0411925d0c902458e45a02916d142cb55cb22 Mon Sep 17 00:00:00 2001
From: bowenyang007 
Date: Tue, 13 Jun 2023 14:08:37 -0700
Subject: [PATCH 157/200] [Indexer] Token v2 improvement (#8436)

* resync schema

* add header

* add token v2 metadata

* suppport fungible tokens

* address comments

* lint
---
 .../down.sql                                  |   7 +
 .../up.sql                                    |  32 +++
 crates/indexer/src/models/coin_models/mod.rs  |   1 +
 .../coin_models/v2_fungible_asset_utils.rs    | 220 +++++++++++++++
 crates/indexer/src/models/token_models/mod.rs |   1 +
 .../token_models/v2_token_activities.rs       |   2 +-
 .../src/models/token_models/v2_token_datas.rs |  19 +-
 .../models/token_models/v2_token_metadata.rs  |  71 +++++
 .../token_models/v2_token_ownerships.rs       | 130 ++++++++-
 .../src/models/token_models/v2_token_utils.rs |  49 +++-
 crates/indexer/src/models/v2_objects.rs       |  17 +-
 .../indexer/src/processors/token_processor.rs | 263 +++++++++++++-----
 crates/indexer/src/schema.rs                  |  16 ++
 13 files changed, 726 insertions(+), 102 deletions(-)
 create mode 100644 crates/indexer/migrations/2023-05-24-052435_token_properties_v2/down.sql
 create mode 100644 crates/indexer/migrations/2023-05-24-052435_token_properties_v2/up.sql
 create mode 100644 crates/indexer/src/models/coin_models/v2_fungible_asset_utils.rs
 create mode 100644 crates/indexer/src/models/token_models/v2_token_metadata.rs

diff --git a/crates/indexer/migrations/2023-05-24-052435_token_properties_v2/down.sql b/crates/indexer/migrations/2023-05-24-052435_token_properties_v2/down.sql
new file mode 100644
index 0000000000000..759d57bc385cb
--- /dev/null
+++ b/crates/indexer/migrations/2023-05-24-052435_token_properties_v2/down.sql
@@ -0,0 +1,7 @@
+-- This file should undo anything in `up.sql`
+DROP VIEW IF EXISTS current_collection_ownership_v2_view;
+DROP TABLE IF EXISTS current_token_v2_metadata;
+ALTER TABLE token_datas_v2 DROP COLUMN IF EXISTS decimals;
+ALTER TABLE current_token_datas_v2 DROP COLUMN IF EXISTS decimals;
+ALTER TABLE token_ownerships_v2 DROP COLUMN IF EXISTS non_transferrable_by_owner;
+ALTER TABLE current_token_ownerships_v2 DROP COLUMN IF EXISTS non_transferrable_by_owner;
\ No newline at end of file
diff --git a/crates/indexer/migrations/2023-05-24-052435_token_properties_v2/up.sql b/crates/indexer/migrations/2023-05-24-052435_token_properties_v2/up.sql
new file mode 100644
index 0000000000000..a8f630220496a
--- /dev/null
+++ b/crates/indexer/migrations/2023-05-24-052435_token_properties_v2/up.sql
@@ -0,0 +1,32 @@
+-- Your SQL goes here
+-- need this for getting NFTs grouped by collections
+create or replace view current_collection_ownership_v2_view as
+select owner_address,
+  b.collection_id,
+  MAX(a.last_transaction_version) as last_transaction_version,
+  COUNT(distinct a.token_data_id) as distinct_tokens
+from current_token_ownerships_v2 a
+  join current_token_datas_v2 b on a.token_data_id = b.token_data_id
+where a.amount > 0
+group by 1,
+  2;
+-- create table for all structs in token object core
+CREATE TABLE IF NOT EXISTS current_token_v2_metadata (
+  object_address VARCHAR(66) NOT NULL,
+  resource_type VARCHAR(128) NOT NULL,
+  data jsonb NOT NULL,
+  state_key_hash VARCHAR(66) NOT NULL,
+  last_transaction_version BIGINT NOT NULL,
+  inserted_at TIMESTAMP NOT NULL DEFAULT NOW(),
+  -- constraints
+  PRIMARY KEY (object_address, resource_type)
+);
+-- create table for all structs in token object core
+ALTER TABLE token_datas_v2
+ADD COLUMN IF NOT EXISTS decimals BIGINT NOT NULL DEFAULT 0;
+ALTER TABLE current_token_datas_v2
+ADD COLUMN IF NOT EXISTS decimals BIGINT NOT NULL DEFAULT 0;
+ALTER TABLE token_ownerships_v2
+ADD COLUMN IF NOT EXISTS non_transferrable_by_owner BOOLEAN;
+ALTER TABLE current_token_ownerships_v2
+ADD COLUMN IF NOT EXISTS non_transferrable_by_owner BOOLEAN;
\ No newline at end of file
diff --git a/crates/indexer/src/models/coin_models/mod.rs b/crates/indexer/src/models/coin_models/mod.rs
index c748a32a04e99..f898fec32f381 100644
--- a/crates/indexer/src/models/coin_models/mod.rs
+++ b/crates/indexer/src/models/coin_models/mod.rs
@@ -6,3 +6,4 @@ pub mod coin_balances;
 pub mod coin_infos;
 pub mod coin_supply;
 pub mod coin_utils;
+pub mod v2_fungible_asset_utils;
diff --git a/crates/indexer/src/models/coin_models/v2_fungible_asset_utils.rs b/crates/indexer/src/models/coin_models/v2_fungible_asset_utils.rs
new file mode 100644
index 0000000000000..5bb0455dc79a6
--- /dev/null
+++ b/crates/indexer/src/models/coin_models/v2_fungible_asset_utils.rs
@@ -0,0 +1,220 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+// This is required because a diesel macro makes clippy sad
+#![allow(clippy::extra_unused_lifetimes)]
+
+use crate::{
+    models::{
+        move_resources::MoveResource,
+        token_models::{token_utils::URI_LENGTH, v2_token_utils::ResourceReference},
+    },
+    util::truncate_str,
+};
+use anyhow::{Context, Result};
+use aptos_api_types::{deserialize_from_string, WriteResource};
+use bigdecimal::BigDecimal;
+use serde::{Deserialize, Serialize};
+
+const FUNGIBLE_ASSET_LENGTH: usize = 32;
+const FUNGIBLE_ASSET_SYMBOL: usize = 10;
+
+/* Section on fungible assets resources */
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct FungibleAssetMetadata {
+    name: String,
+    symbol: String,
+    pub decimals: i32,
+    icon_uri: String,
+    project_uri: String,
+}
+
+impl FungibleAssetMetadata {
+    pub fn from_write_resource(
+        write_resource: &WriteResource,
+        txn_version: i64,
+    ) -> anyhow::Result> {
+        let type_str = format!(
+            "{}::{}::{}",
+            write_resource.data.typ.address,
+            write_resource.data.typ.module,
+            write_resource.data.typ.name
+        );
+        if !V2FungibleAssetResource::is_resource_supported(type_str.as_str()) {
+            return Ok(None);
+        }
+        let resource = MoveResource::from_write_resource(
+            write_resource,
+            0, // Placeholder, this isn't used anyway
+            txn_version,
+            0, // Placeholder, this isn't used anyway
+        );
+
+        if let V2FungibleAssetResource::FungibleAssetMetadata(inner) =
+            V2FungibleAssetResource::from_resource(
+                &type_str,
+                resource.data.as_ref().unwrap(),
+                txn_version,
+            )?
+        {
+            Ok(Some(inner))
+        } else {
+            Ok(None)
+        }
+    }
+
+    pub fn get_name(&self) -> String {
+        truncate_str(&self.name, FUNGIBLE_ASSET_LENGTH)
+    }
+
+    pub fn get_symbol(&self) -> String {
+        truncate_str(&self.name, FUNGIBLE_ASSET_SYMBOL)
+    }
+
+    pub fn get_icon_uri(&self) -> String {
+        truncate_str(&self.icon_uri, URI_LENGTH)
+    }
+
+    pub fn get_project_uri(&self) -> String {
+        truncate_str(&self.project_uri, URI_LENGTH)
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct FungibleAssetStore {
+    pub metadata: ResourceReference,
+    #[serde(deserialize_with = "deserialize_from_string")]
+    pub balance: BigDecimal,
+    pub frozen: bool,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct FungibleAssetSupply {
+    #[serde(deserialize_with = "deserialize_from_string")]
+    pub current: BigDecimal,
+    pub maximum: OptionalBigDecimal,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct OptionalBigDecimal {
+    vec: Vec,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+struct BigDecimalWrapper(#[serde(deserialize_with = "deserialize_from_string")] pub BigDecimal);
+
+impl FungibleAssetSupply {
+    pub fn from_write_resource(
+        write_resource: &WriteResource,
+        txn_version: i64,
+    ) -> anyhow::Result> {
+        let type_str = format!(
+            "{}::{}::{}",
+            write_resource.data.typ.address,
+            write_resource.data.typ.module,
+            write_resource.data.typ.name
+        );
+        if !V2FungibleAssetResource::is_resource_supported(type_str.as_str()) {
+            return Ok(None);
+        }
+        let resource = MoveResource::from_write_resource(
+            write_resource,
+            0, // Placeholder, this isn't used anyway
+            txn_version,
+            0, // Placeholder, this isn't used anyway
+        );
+
+        if let V2FungibleAssetResource::FungibleAssetSupply(inner) =
+            V2FungibleAssetResource::from_resource(
+                &type_str,
+                resource.data.as_ref().unwrap(),
+                txn_version,
+            )?
+        {
+            Ok(Some(inner))
+        } else {
+            Ok(None)
+        }
+    }
+
+    pub fn get_maximum(&self) -> Option {
+        self.maximum.vec.first().map(|x| x.0.clone())
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub enum V2FungibleAssetResource {
+    FungibleAssetMetadata(FungibleAssetMetadata),
+    FungibleAssetStore(FungibleAssetStore),
+    FungibleAssetSupply(FungibleAssetSupply),
+}
+
+impl V2FungibleAssetResource {
+    pub fn is_resource_supported(data_type: &str) -> bool {
+        matches!(
+            data_type,
+            "0x1::fungible_asset::Supply"
+                | "0x1::fungible_asset::Metadata"
+                | "0x1::fungible_asset::FungibleStore"
+        )
+    }
+
+    pub fn from_resource(
+        data_type: &str,
+        data: &serde_json::Value,
+        txn_version: i64,
+    ) -> Result {
+        match data_type {
+            "0x1::fungible_asset::Supply" => serde_json::from_value(data.clone())
+                .map(|inner| Some(Self::FungibleAssetSupply(inner))),
+            "0x1::fungible_asset::Metadata" => serde_json::from_value(data.clone())
+                .map(|inner| Some(Self::FungibleAssetMetadata(inner))),
+            "0x1::fungible_asset::FungibleStore" => serde_json::from_value(data.clone())
+                .map(|inner| Some(Self::FungibleAssetStore(inner))),
+            _ => Ok(None),
+        }
+        .context(format!(
+            "version {} failed! failed to parse type {}, data {:?}",
+            txn_version, data_type, data
+        ))?
+        .context(format!(
+            "Resource unsupported! Call is_resource_supported first. version {} type {}",
+            txn_version, data_type
+        ))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_fungible_asset_supply_null() {
+        let test = r#"{"current": "0", "maximum": {"vec": []}}"#;
+        let test: serde_json::Value = serde_json::from_str(test).unwrap();
+        let supply = serde_json::from_value(test)
+            .map(V2FungibleAssetResource::FungibleAssetSupply)
+            .unwrap();
+        if let V2FungibleAssetResource::FungibleAssetSupply(supply) = supply {
+            assert_eq!(supply.current, BigDecimal::from(0));
+            assert_eq!(supply.get_maximum(), None);
+        } else {
+            panic!("Wrong type")
+        }
+    }
+
+    #[test]
+    fn test_fungible_asset_supply_nonnull() {
+        let test = r#"{"current": "100", "maximum": {"vec": ["5000"]}}"#;
+        let test: serde_json::Value = serde_json::from_str(test).unwrap();
+        let supply = serde_json::from_value(test)
+            .map(V2FungibleAssetResource::FungibleAssetSupply)
+            .unwrap();
+        if let V2FungibleAssetResource::FungibleAssetSupply(supply) = supply {
+            assert_eq!(supply.current, BigDecimal::from(100));
+            assert_eq!(supply.get_maximum(), Some(BigDecimal::from(5000)));
+        } else {
+            panic!("Wrong type")
+        }
+    }
+}
diff --git a/crates/indexer/src/models/token_models/mod.rs b/crates/indexer/src/models/token_models/mod.rs
index acde51b236948..c6c6d17f7b951 100644
--- a/crates/indexer/src/models/token_models/mod.rs
+++ b/crates/indexer/src/models/token_models/mod.rs
@@ -13,5 +13,6 @@ pub mod tokens;
 pub mod v2_collections;
 pub mod v2_token_activities;
 pub mod v2_token_datas;
+pub mod v2_token_metadata;
 pub mod v2_token_ownerships;
 pub mod v2_token_utils;
diff --git a/crates/indexer/src/models/token_models/v2_token_activities.rs b/crates/indexer/src/models/token_models/v2_token_activities.rs
index a5cd7873170f6..1f94bb4bfe1f9 100644
--- a/crates/indexer/src/models/token_models/v2_token_activities.rs
+++ b/crates/indexer/src/models/token_models/v2_token_activities.rs
@@ -78,7 +78,7 @@ impl TokenActivityV2 {
             };
 
             if let Some(metadata) = token_v2_metadata.get(&token_data_id) {
-                let object_core = &metadata.object;
+                let object_core = &metadata.object.object_core;
                 let token_activity_helper = match token_event {
                     V2TokenEvent::MintEvent(_) => TokenActivityHelperV2 {
                         from_address: Some(object_core.get_owner_address()),
diff --git a/crates/indexer/src/models/token_models/v2_token_datas.rs b/crates/indexer/src/models/token_models/v2_token_datas.rs
index ddad577fefecc..0200ebcfa143c 100644
--- a/crates/indexer/src/models/token_models/v2_token_datas.rs
+++ b/crates/indexer/src/models/token_models/v2_token_datas.rs
@@ -39,6 +39,7 @@ pub struct TokenDataV2 {
     pub token_standard: String,
     pub is_fungible_v2: Option,
     pub transaction_timestamp: chrono::NaiveDateTime,
+    pub decimals: i64,
 }
 
 #[derive(Debug, Deserialize, FieldCount, Identifiable, Insertable, Serialize)]
@@ -58,6 +59,7 @@ pub struct CurrentTokenDataV2 {
     pub is_fungible_v2: Option,
     pub last_transaction_version: i64,
     pub last_transaction_timestamp: chrono::NaiveDateTime,
+    pub decimals: i64,
 }
 
 impl TokenDataV2 {
@@ -71,10 +73,21 @@ impl TokenDataV2 {
         if let Some(inner) = &TokenV2::from_write_resource(write_resource, txn_version)? {
             let token_data_id = standardize_address(&write_resource.address.to_string());
             // Get maximum, supply, and is fungible from fungible asset if this is a fungible token
-            let (maximum, supply, is_fungible_v2) = (None, BigDecimal::zero(), Some(false));
+            let (mut maximum, mut supply, mut decimals, mut is_fungible_v2) =
+                (None, BigDecimal::zero(), 0, Some(false));
             // Get token properties from 0x4::property_map::PropertyMap
             let mut token_properties = serde_json::Value::Null;
             if let Some(metadata) = token_v2_metadata.get(&token_data_id) {
+                let fungible_asset_metadata = metadata.fungible_asset_metadata.as_ref();
+                let fungible_asset_supply = metadata.fungible_asset_supply.as_ref();
+                if let Some(metadata) = fungible_asset_metadata {
+                    if let Some(fa_supply) = fungible_asset_supply {
+                        maximum = fa_supply.get_maximum();
+                        supply = fa_supply.current.clone();
+                        decimals = metadata.decimals as i64;
+                        is_fungible_v2 = Some(true);
+                    }
+                }
                 token_properties = metadata
                     .property_map
                     .as_ref()
@@ -105,6 +118,7 @@ impl TokenDataV2 {
                     token_standard: TokenStandard::V2.to_string(),
                     is_fungible_v2,
                     transaction_timestamp: txn_timestamp,
+                    decimals,
                 },
                 CurrentTokenDataV2 {
                     token_data_id,
@@ -120,6 +134,7 @@ impl TokenDataV2 {
                     is_fungible_v2,
                     last_transaction_version: txn_version,
                     last_transaction_timestamp: txn_timestamp,
+                    decimals,
                 },
             )))
         } else {
@@ -177,6 +192,7 @@ impl TokenDataV2 {
                         token_standard: TokenStandard::V1.to_string(),
                         is_fungible_v2: None,
                         transaction_timestamp: txn_timestamp,
+                        decimals: 0,
                     },
                     CurrentTokenDataV2 {
                         token_data_id,
@@ -192,6 +208,7 @@ impl TokenDataV2 {
                         is_fungible_v2: None,
                         last_transaction_version: txn_version,
                         last_transaction_timestamp: txn_timestamp,
+                        decimals: 0,
                     },
                 )));
             } else {
diff --git a/crates/indexer/src/models/token_models/v2_token_metadata.rs b/crates/indexer/src/models/token_models/v2_token_metadata.rs
new file mode 100644
index 0000000000000..f5e86065877dd
--- /dev/null
+++ b/crates/indexer/src/models/token_models/v2_token_metadata.rs
@@ -0,0 +1,71 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+// This is required because a diesel macro makes clippy sad
+#![allow(clippy::extra_unused_lifetimes)]
+#![allow(clippy::unused_unit)]
+
+use super::{token_utils::NAME_LENGTH, v2_token_utils::TokenV2AggregatedDataMapping};
+use crate::{
+    models::move_resources::MoveResource,
+    schema::current_token_v2_metadata,
+    util::{standardize_address, truncate_str},
+};
+use anyhow::Context;
+use aptos_api_types::WriteResource;
+use field_count::FieldCount;
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+// PK of current_objects, i.e. object_address, resource_type
+pub type CurrentTokenV2MetadataPK = (String, String);
+
+#[derive(Debug, Deserialize, FieldCount, Identifiable, Insertable, Serialize)]
+#[diesel(primary_key(object_address, resource_type))]
+#[diesel(table_name = current_token_v2_metadata)]
+pub struct CurrentTokenV2Metadata {
+    pub object_address: String,
+    pub resource_type: String,
+    pub data: Value,
+    pub state_key_hash: String,
+    pub last_transaction_version: i64,
+}
+
+impl CurrentTokenV2Metadata {
+    /// Parsing unknown resources with 0x4::token::Token
+    pub fn from_write_resource(
+        write_resource: &WriteResource,
+        txn_version: i64,
+        token_v2_metadata: &TokenV2AggregatedDataMapping,
+    ) -> anyhow::Result> {
+        let object_address = standardize_address(&write_resource.address.to_string());
+        if let Some(metadata) = token_v2_metadata.get(&object_address) {
+            // checking if token_v2
+            if metadata.token.is_some() {
+                let resource_type_addr = write_resource.data.typ.address.to_string();
+                if matches!(resource_type_addr.as_str(), "0x1" | "0x3" | "0x4") {
+                    return Ok(None);
+                }
+
+                let resource = MoveResource::from_write_resource(write_resource, 0, txn_version, 0);
+
+                let state_key_hash = metadata.object.get_state_key_hash();
+                if state_key_hash != resource.state_key_hash {
+                    return Ok(None);
+                }
+
+                let resource_type = truncate_str(&resource.type_, NAME_LENGTH);
+                return Ok(Some(CurrentTokenV2Metadata {
+                    object_address,
+                    resource_type,
+                    data: resource
+                        .data
+                        .context("data must be present in write resource")?,
+                    state_key_hash: resource.state_key_hash,
+                    last_transaction_version: txn_version,
+                }));
+            }
+        }
+        Ok(None)
+    }
+}
diff --git a/crates/indexer/src/models/token_models/v2_token_ownerships.rs b/crates/indexer/src/models/token_models/v2_token_ownerships.rs
index 0c3a50d22c101..8da58f398ec10 100644
--- a/crates/indexer/src/models/token_models/v2_token_ownerships.rs
+++ b/crates/indexer/src/models/token_models/v2_token_ownerships.rs
@@ -10,10 +10,15 @@ use super::{
     token_utils::TokenWriteSet,
     tokens::TableHandleToOwner,
     v2_token_datas::TokenDataV2,
-    v2_token_utils::{ObjectCore, TokenStandard, TokenV2AggregatedDataMapping, TokenV2Burned},
+    v2_token_utils::{
+        ObjectWithMetadata, TokenStandard, TokenV2AggregatedDataMapping, TokenV2Burned,
+    },
 };
 use crate::{
     database::PgPoolConnection,
+    models::{
+        coin_models::v2_fungible_asset_utils::V2FungibleAssetResource, move_resources::MoveResource,
+    },
     schema::{current_token_ownerships_v2, token_ownerships_v2},
     util::{ensure_not_negative, standardize_address},
 };
@@ -48,6 +53,7 @@ pub struct TokenOwnershipV2 {
     pub token_standard: String,
     pub is_fungible_v2: Option,
     pub transaction_timestamp: chrono::NaiveDateTime,
+    pub non_transferrable_by_owner: Option,
 }
 
 #[derive(Debug, Deserialize, FieldCount, Identifiable, Insertable, Serialize)]
@@ -66,6 +72,7 @@ pub struct CurrentTokenOwnershipV2 {
     pub is_fungible_v2: Option,
     pub last_transaction_version: i64,
     pub last_transaction_timestamp: chrono::NaiveDateTime,
+    pub non_transferrable_by_owner: Option,
 }
 
 // Facilitate tracking when a token is burned
@@ -94,6 +101,7 @@ pub struct CurrentTokenOwnershipV2Query {
     pub last_transaction_version: i64,
     pub last_transaction_timestamp: chrono::NaiveDateTime,
     pub inserted_at: chrono::NaiveDateTime,
+    pub non_transferrable_by_owner: Option,
 }
 
 impl TokenOwnershipV2 {
@@ -101,16 +109,22 @@ impl TokenOwnershipV2 {
     pub fn get_nft_v2_from_token_data(
         token_data: &TokenDataV2,
         token_v2_metadata: &TokenV2AggregatedDataMapping,
-    ) -> anyhow::Result<(
-        Self,
-        CurrentTokenOwnershipV2,
-        Option, // If token was transferred, the previous ownership record
-        Option, // If token was transferred, the previous ownership record
-    )> {
+    ) -> anyhow::Result<
+        Option<(
+            Self,
+            CurrentTokenOwnershipV2,
+            Option, // If token was transferred, the previous ownership record
+            Option, // If token was transferred, the previous ownership record
+        )>,
+    > {
+        // We should be indexing v1 token or v2 fungible token here
+        if token_data.is_fungible_v2 != Some(false) {
+            return Ok(None);
+        }
         let metadata = token_v2_metadata
             .get(&token_data.token_data_id)
             .context("If token data exists objectcore must exist")?;
-        let object_core = metadata.object.clone();
+        let object_core = metadata.object.object_core.clone();
         let token_data_id = token_data.token_data_id.clone();
         let owner_address = object_core.get_owner_address();
         let storage_id = token_data_id.clone();
@@ -130,6 +144,7 @@ impl TokenOwnershipV2 {
             token_standard: TokenStandard::V2.to_string(),
             is_fungible_v2: token_data.is_fungible_v2,
             transaction_timestamp: token_data.transaction_timestamp,
+            non_transferrable_by_owner: Some(is_soulbound),
         };
         let current_ownership = CurrentTokenOwnershipV2 {
             token_data_id: token_data_id.clone(),
@@ -144,11 +159,12 @@ impl TokenOwnershipV2 {
             is_fungible_v2: token_data.is_fungible_v2,
             last_transaction_version: token_data.transaction_version,
             last_transaction_timestamp: token_data.transaction_timestamp,
+            non_transferrable_by_owner: Some(is_soulbound),
         };
 
         // check if token was transferred
         if let Some((event_index, transfer_event)) = &metadata.transfer_event {
-            Ok((
+            Ok(Some((
                 ownership,
                 current_ownership,
                 Some(Self {
@@ -168,6 +184,7 @@ impl TokenOwnershipV2 {
                     token_standard: TokenStandard::V2.to_string(),
                     is_fungible_v2: token_data.is_fungible_v2,
                     transaction_timestamp: token_data.transaction_timestamp,
+                    non_transferrable_by_owner: Some(is_soulbound),
                 }),
                 Some(CurrentTokenOwnershipV2 {
                     token_data_id,
@@ -184,10 +201,11 @@ impl TokenOwnershipV2 {
                     is_fungible_v2: token_data.is_fungible_v2,
                     last_transaction_version: token_data.transaction_version,
                     last_transaction_timestamp: token_data.transaction_timestamp,
+                    non_transferrable_by_owner: Some(is_soulbound),
                 }),
-            ))
+            )))
         } else {
-            Ok((ownership, current_ownership, None, None))
+            Ok(Some((ownership, current_ownership, None, None)))
         }
     }
 
@@ -202,9 +220,10 @@ impl TokenOwnershipV2 {
         if let Some(token_address) =
             tokens_burned.get(&standardize_address(&write_resource.address.to_string()))
         {
-            if let Some(object_core) =
-                &ObjectCore::from_write_resource(write_resource, txn_version)?
+            if let Some(object) =
+                &ObjectWithMetadata::from_write_resource(write_resource, txn_version)?
             {
+                let object_core = &object.object_core;
                 let token_data_id = token_address.clone();
                 let owner_address = object_core.get_owner_address();
                 let storage_id = token_data_id.clone();
@@ -225,6 +244,7 @@ impl TokenOwnershipV2 {
                         token_standard: TokenStandard::V2.to_string(),
                         is_fungible_v2: Some(false),
                         transaction_timestamp: txn_timestamp,
+                        non_transferrable_by_owner: Some(is_soulbound),
                     },
                     CurrentTokenOwnershipV2 {
                         token_data_id,
@@ -239,6 +259,7 @@ impl TokenOwnershipV2 {
                         is_fungible_v2: Some(false),
                         last_transaction_version: txn_version,
                         last_transaction_timestamp: txn_timestamp,
+                        non_transferrable_by_owner: Some(is_soulbound),
                     },
                 )));
             }
@@ -287,6 +308,7 @@ impl TokenOwnershipV2 {
                     token_standard: TokenStandard::V2.to_string(),
                     is_fungible_v2: Some(false),
                     transaction_timestamp: txn_timestamp,
+                    non_transferrable_by_owner: is_soulbound,
                 },
                 CurrentTokenOwnershipV2 {
                     token_data_id,
@@ -301,12 +323,90 @@ impl TokenOwnershipV2 {
                     is_fungible_v2: Some(false),
                     last_transaction_version: txn_version,
                     last_transaction_timestamp: txn_timestamp,
+                    non_transferrable_by_owner: is_soulbound,
                 },
             )));
         }
         Ok(None)
     }
 
+    // Getting this from 0x1::fungible_asset::FungibleStore
+    pub fn get_ft_v2_from_write_resource(
+        write_resource: &WriteResource,
+        txn_version: i64,
+        write_set_change_index: i64,
+        txn_timestamp: chrono::NaiveDateTime,
+        token_v2_metadata: &TokenV2AggregatedDataMapping,
+    ) -> anyhow::Result> {
+        let type_str = format!(
+            "{}::{}::{}",
+            write_resource.data.typ.address,
+            write_resource.data.typ.module,
+            write_resource.data.typ.name
+        );
+        if !V2FungibleAssetResource::is_resource_supported(type_str.as_str()) {
+            return Ok(None);
+        }
+        let resource = MoveResource::from_write_resource(
+            write_resource,
+            0, // Placeholder, this isn't used anyway
+            txn_version,
+            0, // Placeholder, this isn't used anyway
+        );
+
+        if let V2FungibleAssetResource::FungibleAssetStore(inner) =
+            V2FungibleAssetResource::from_resource(
+                &type_str,
+                resource.data.as_ref().unwrap(),
+                txn_version,
+            )?
+        {
+            if let Some(metadata) = token_v2_metadata.get(&resource.address) {
+                let object_core = &metadata.object.object_core;
+                let token_data_id = inner.metadata.get_reference_address();
+                let storage_id = token_data_id.clone();
+                let is_soulbound = inner.frozen;
+                let amount = inner.balance;
+                let owner_address = object_core.get_owner_address();
+
+                return Ok(Some((
+                    Self {
+                        transaction_version: txn_version,
+                        write_set_change_index,
+                        token_data_id: token_data_id.clone(),
+                        property_version_v1: BigDecimal::zero(),
+                        owner_address: Some(owner_address.clone()),
+                        storage_id: storage_id.clone(),
+                        amount: amount.clone(),
+                        table_type_v1: None,
+                        token_properties_mutated_v1: None,
+                        is_soulbound_v2: Some(is_soulbound),
+                        token_standard: TokenStandard::V2.to_string(),
+                        is_fungible_v2: Some(true),
+                        transaction_timestamp: txn_timestamp,
+                        non_transferrable_by_owner: Some(is_soulbound),
+                    },
+                    CurrentTokenOwnershipV2 {
+                        token_data_id,
+                        property_version_v1: BigDecimal::zero(),
+                        owner_address,
+                        storage_id,
+                        amount,
+                        table_type_v1: None,
+                        token_properties_mutated_v1: None,
+                        is_soulbound_v2: Some(is_soulbound),
+                        token_standard: TokenStandard::V2.to_string(),
+                        is_fungible_v2: Some(true),
+                        last_transaction_version: txn_version,
+                        last_transaction_timestamp: txn_timestamp,
+                        non_transferrable_by_owner: Some(is_soulbound),
+                    },
+                )));
+            }
+        }
+        Ok(None)
+    }
+
     /// We want to track tokens in any offer/claims and tokenstore
     pub fn get_v1_from_write_table_item(
         table_item: &APIWriteTableItem,
@@ -354,6 +454,7 @@ impl TokenOwnershipV2 {
                             is_fungible_v2: None,
                             last_transaction_version: txn_version,
                             last_transaction_timestamp: txn_timestamp,
+                            non_transferrable_by_owner: None,
                         }),
                         Some(owner_address),
                         Some(tm.table_type.clone()),
@@ -385,6 +486,7 @@ impl TokenOwnershipV2 {
                     token_standard: TokenStandard::V1.to_string(),
                     is_fungible_v2: None,
                     transaction_timestamp: txn_timestamp,
+                    non_transferrable_by_owner: None,
                 },
                 curr_token_ownership,
             )))
@@ -438,6 +540,7 @@ impl TokenOwnershipV2 {
                             is_fungible_v2: None,
                             last_transaction_version: txn_version,
                             last_transaction_timestamp: txn_timestamp,
+                            non_transferrable_by_owner: None,
                         }),
                         Some(owner_address),
                         Some(tm.table_type.clone()),
@@ -469,6 +572,7 @@ impl TokenOwnershipV2 {
                     token_standard: TokenStandard::V1.to_string(),
                     is_fungible_v2: None,
                     transaction_timestamp: txn_timestamp,
+                    non_transferrable_by_owner: None,
                 },
                 curr_token_ownership,
             )))
diff --git a/crates/indexer/src/models/token_models/v2_token_utils.rs b/crates/indexer/src/models/token_models/v2_token_utils.rs
index 62c8f366dc6ff..f4e36600298bd 100644
--- a/crates/indexer/src/models/token_models/v2_token_utils.rs
+++ b/crates/indexer/src/models/token_models/v2_token_utils.rs
@@ -6,7 +6,11 @@
 
 use super::token_utils::{NAME_LENGTH, URI_LENGTH};
 use crate::{
-    models::{move_resources::MoveResource, v2_objects::CurrentObjectPK},
+    models::{
+        coin_models::v2_fungible_asset_utils::{FungibleAssetMetadata, FungibleAssetSupply},
+        move_resources::MoveResource,
+        v2_objects::CurrentObjectPK,
+    },
     util::{
         deserialize_token_object_property_map_from_bcs_hexstring, standardize_address, truncate_str,
     },
@@ -31,11 +35,13 @@ pub type EventIndex = i64;
 pub struct TokenV2AggregatedData {
     pub aptos_collection: Option,
     pub fixed_supply: Option,
-    pub object: ObjectCore,
-    pub unlimited_supply: Option,
+    pub fungible_asset_metadata: Option,
+    pub fungible_asset_supply: Option,
+    pub object: ObjectWithMetadata,
     pub property_map: Option,
-    pub transfer_event: Option<(EventIndex, TransferEvent)>,
     pub token: Option,
+    pub transfer_event: Option<(EventIndex, TransferEvent)>,
+    pub unlimited_supply: Option,
 }
 
 /// Tracks which token standard a token / collection is built upon
@@ -64,6 +70,18 @@ pub struct ObjectCore {
 }
 
 impl ObjectCore {
+    pub fn get_owner_address(&self) -> String {
+        standardize_address(&self.owner)
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct ObjectWithMetadata {
+    pub object_core: ObjectCore,
+    state_key_hash: String,
+}
+
+impl ObjectWithMetadata {
     pub fn from_write_resource(
         write_resource: &WriteResource,
         txn_version: i64,
@@ -82,17 +100,21 @@ impl ObjectCore {
             &serde_json::to_value(&write_resource.data.data).unwrap(),
             txn_version,
         )? {
-            Ok(Some(inner))
+            Ok(Some(Self {
+                object_core: inner,
+                state_key_hash: standardize_address(write_resource.state_key_hash.as_str()),
+            }))
         } else {
             Ok(None)
         }
     }
 
-    pub fn get_owner_address(&self) -> String {
-        standardize_address(&self.owner)
+    pub fn get_state_key_hash(&self) -> String {
+        standardize_address(&self.state_key_hash)
     }
 }
 
+/* Section on Collection / Token */
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct Collection {
     creator: String,
@@ -164,7 +186,7 @@ pub struct TokenV2 {
 
 impl TokenV2 {
     pub fn get_collection_address(&self) -> String {
-        standardize_address(&self.collection.inner)
+        self.collection.get_reference_address()
     }
 
     pub fn get_uri_trunc(&self) -> String {
@@ -210,6 +232,13 @@ pub struct ResourceReference {
     inner: String,
 }
 
+impl ResourceReference {
+    pub fn get_reference_address(&self) -> String {
+        standardize_address(&self.inner)
+    }
+}
+
+/* Section on Supply */
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct FixedSupply {
     #[serde(deserialize_with = "deserialize_from_string")]
@@ -290,6 +319,7 @@ impl UnlimitedSupply {
     }
 }
 
+/* Section on Events */
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct MintEvent {
     #[serde(deserialize_with = "deserialize_from_string")]
@@ -366,6 +396,7 @@ impl TransferEvent {
     }
 }
 
+/* Section on Property Maps */
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct PropertyMap {
     #[serde(deserialize_with = "deserialize_token_object_property_map_from_bcs_hexstring")]
@@ -481,7 +512,7 @@ impl V2TokenEvent {
         data_type: &str,
         data: &serde_json::Value,
         txn_version: i64,
-    ) -> Result> {
+    ) -> Result> {
         match data_type {
             "0x4::collection::MintEvent" => {
                 serde_json::from_value(data.clone()).map(|inner| Some(Self::MintEvent(inner)))
diff --git a/crates/indexer/src/models/v2_objects.rs b/crates/indexer/src/models/v2_objects.rs
index 1cab00cfac1ae..517450bebfc13 100644
--- a/crates/indexer/src/models/v2_objects.rs
+++ b/crates/indexer/src/models/v2_objects.rs
@@ -5,7 +5,7 @@
 #![allow(clippy::extra_unused_lifetimes)]
 #![allow(clippy::unused_unit)]
 
-use super::token_models::v2_token_utils::ObjectCore;
+use super::token_models::v2_token_utils::ObjectWithMetadata;
 use crate::{
     models::move_resources::MoveResource,
     schema::{current_objects, objects},
@@ -83,30 +83,31 @@ impl Object {
         txn_version: i64,
         write_set_change_index: i64,
     ) -> anyhow::Result> {
-        if let Some(inner) = ObjectCore::from_write_resource(write_resource, txn_version)? {
+        if let Some(inner) = ObjectWithMetadata::from_write_resource(write_resource, txn_version)? {
             let resource = MoveResource::from_write_resource(
                 write_resource,
                 0, // Placeholder, this isn't used anyway
                 txn_version,
                 0, // Placeholder, this isn't used anyway
             );
+            let object_core = &inner.object_core;
             Ok(Some((
                 Self {
                     transaction_version: txn_version,
                     write_set_change_index,
                     object_address: resource.address.clone(),
-                    owner_address: Some(inner.get_owner_address()),
+                    owner_address: Some(object_core.get_owner_address()),
                     state_key_hash: resource.state_key_hash.clone(),
-                    guid_creation_num: Some(inner.guid_creation_num.clone()),
-                    allow_ungated_transfer: Some(inner.allow_ungated_transfer),
+                    guid_creation_num: Some(object_core.guid_creation_num.clone()),
+                    allow_ungated_transfer: Some(object_core.allow_ungated_transfer),
                     is_deleted: false,
                 },
                 CurrentObject {
                     object_address: resource.address,
-                    owner_address: Some(inner.get_owner_address()),
+                    owner_address: Some(object_core.get_owner_address()),
                     state_key_hash: resource.state_key_hash,
-                    allow_ungated_transfer: Some(inner.allow_ungated_transfer),
-                    last_guid_creation_num: Some(inner.guid_creation_num),
+                    allow_ungated_transfer: Some(object_core.allow_ungated_transfer),
+                    last_guid_creation_num: Some(object_core.guid_creation_num.clone()),
                     last_transaction_version: txn_version,
                     is_deleted: false,
                 },
diff --git a/crates/indexer/src/processors/token_processor.rs b/crates/indexer/src/processors/token_processor.rs
index c4102ac6743cb..5dec69b6c6118 100644
--- a/crates/indexer/src/processors/token_processor.rs
+++ b/crates/indexer/src/processors/token_processor.rs
@@ -10,7 +10,10 @@ use crate::{
         transaction_processor::TransactionProcessor,
     },
     models::{
-        coin_models::coin_activities::MAX_ENTRY_FUNCTION_LENGTH,
+        coin_models::{
+            coin_activities::MAX_ENTRY_FUNCTION_LENGTH,
+            v2_fungible_asset_utils::{FungibleAssetMetadata, FungibleAssetSupply},
+        },
         token_models::{
             ans_lookup::{CurrentAnsLookup, CurrentAnsLookupPK},
             collection_datas::{CollectionData, CurrentCollectionData},
@@ -26,12 +29,13 @@ use crate::{
             v2_collections::{CollectionV2, CurrentCollectionV2, CurrentCollectionV2PK},
             v2_token_activities::TokenActivityV2,
             v2_token_datas::{CurrentTokenDataV2, CurrentTokenDataV2PK, TokenDataV2},
+            v2_token_metadata::{CurrentTokenV2Metadata, CurrentTokenV2MetadataPK},
             v2_token_ownerships::{
                 CurrentTokenOwnershipV2, CurrentTokenOwnershipV2PK, NFTOwnershipV2,
                 TokenOwnershipV2,
             },
             v2_token_utils::{
-                AptosCollection, BurnEvent, FixedSupply, ObjectCore, PropertyMap, TokenV2,
+                AptosCollection, BurnEvent, FixedSupply, ObjectWithMetadata, PropertyMap, TokenV2,
                 TokenV2AggregatedData, TokenV2AggregatedDataMapping, TokenV2Burned, TransferEvent,
                 UnlimitedSupply,
             },
@@ -105,6 +109,7 @@ fn insert_to_db_impl(
         current_token_datas_v2,
         current_token_ownerships_v2,
         token_activities_v2,
+        current_token_v2_metadata,
     ): (
         &[CollectionV2],
         &[TokenDataV2],
@@ -113,6 +118,7 @@ fn insert_to_db_impl(
         &[CurrentTokenDataV2],
         &[CurrentTokenOwnershipV2],
         &[TokenActivityV2],
+        &[CurrentTokenV2Metadata],
     ),
 ) -> Result<(), diesel::result::Error> {
     let (tokens, token_ownerships, token_datas, collection_datas) = basic_token_transaction_lists;
@@ -136,6 +142,7 @@ fn insert_to_db_impl(
     insert_current_token_datas_v2(conn, current_token_datas_v2)?;
     insert_current_token_ownerships_v2(conn, current_token_ownerships_v2)?;
     insert_token_activities_v2(conn, token_activities_v2)?;
+    insert_current_token_v2_metadatas(conn, current_token_v2_metadata)?;
     Ok(())
 }
 
@@ -167,6 +174,7 @@ fn insert_to_db(
         current_token_datas_v2,
         current_token_ownerships_v2,
         token_activities_v2,
+        current_token_v2_metadata,
     ): (
         Vec,
         Vec,
@@ -175,6 +183,7 @@ fn insert_to_db(
         Vec,
         Vec,
         Vec,
+        Vec,
     ),
 ) -> Result<(), diesel::result::Error> {
     aptos_logger::trace!(
@@ -210,6 +219,7 @@ fn insert_to_db(
                     ¤t_token_datas_v2,
                     ¤t_token_ownerships_v2,
                     &token_activities_v2,
+                    ¤t_token_v2_metadata,
                 ),
             )
         }) {
@@ -237,6 +247,7 @@ fn insert_to_db(
                 let current_token_ownerships_v2 =
                     clean_data_for_db(current_token_ownerships_v2, true);
                 let token_activities_v2 = clean_data_for_db(token_activities_v2, true);
+                let current_token_v2_metadata = clean_data_for_db(current_token_v2_metadata, true);
 
                 insert_to_db_impl(
                     pg_conn,
@@ -258,6 +269,7 @@ fn insert_to_db(
                         ¤t_token_datas_v2,
                         ¤t_token_ownerships_v2,
                         &token_activities_v2,
+                        ¤t_token_v2_metadata,
                     ),
                 )
             }),
@@ -626,10 +638,8 @@ fn insert_token_datas_v2(
                 .on_conflict((transaction_version, write_set_change_index))
                 .do_update()
                 .set((
-                    maximum.eq(excluded(maximum)),
-                    supply.eq(excluded(supply)),
-                    token_properties.eq(excluded(token_properties)),
                     inserted_at.eq(excluded(inserted_at)),
+                    decimals.eq(excluded(decimals)),
                 )),
             None,
         )?;
@@ -651,7 +661,22 @@ fn insert_token_ownerships_v2(
             diesel::insert_into(schema::token_ownerships_v2::table)
                 .values(&items_to_insert[start_ind..end_ind])
                 .on_conflict((transaction_version, write_set_change_index))
-                .do_nothing(),
+                .do_update()
+                .set((
+                    token_data_id.eq(excluded(token_data_id)),
+                    property_version_v1.eq(excluded(property_version_v1)),
+                    owner_address.eq(excluded(owner_address)),
+                    storage_id.eq(excluded(storage_id)),
+                    amount.eq(excluded(amount)),
+                    table_type_v1.eq(excluded(table_type_v1)),
+                    token_properties_mutated_v1.eq(excluded(token_properties_mutated_v1)),
+                    is_soulbound_v2.eq(excluded(is_soulbound_v2)),
+                    token_standard.eq(excluded(token_standard)),
+                    is_fungible_v2.eq(excluded(is_fungible_v2)),
+                    transaction_timestamp.eq(excluded(transaction_timestamp)),
+                    inserted_at.eq(excluded(inserted_at)),
+                    non_transferrable_by_owner.eq(excluded(non_transferrable_by_owner)),
+                )),
             None,
         )?;
     }
@@ -724,6 +749,7 @@ fn insert_current_token_datas_v2(
                     last_transaction_version.eq(excluded(last_transaction_version)),
                     last_transaction_timestamp.eq(excluded(last_transaction_timestamp)),
                     inserted_at.eq(excluded(inserted_at)),
+                    decimals.eq(excluded(decimals)),
                 )),
             Some(" WHERE current_token_datas_v2.last_transaction_version <= excluded.last_transaction_version "),
         )?;
@@ -753,11 +779,13 @@ fn insert_current_token_ownerships_v2(
                     amount.eq(excluded(amount)),
                     table_type_v1.eq(excluded(table_type_v1)),
                     token_properties_mutated_v1.eq(excluded(token_properties_mutated_v1)),
+                    is_soulbound_v2.eq(excluded(is_soulbound_v2)),
                     token_standard.eq(excluded(token_standard)),
                     is_fungible_v2.eq(excluded(is_fungible_v2)),
                     last_transaction_version.eq(excluded(last_transaction_version)),
                     last_transaction_timestamp.eq(excluded(last_transaction_timestamp)),
                     inserted_at.eq(excluded(inserted_at)),
+                    non_transferrable_by_owner.eq(excluded(non_transferrable_by_owner)),
                 )),
             Some(" WHERE current_token_ownerships_v2.last_transaction_version <= excluded.last_transaction_version "),
         )?;
@@ -786,6 +814,33 @@ fn insert_token_activities_v2(
     Ok(())
 }
 
+fn insert_current_token_v2_metadatas(
+    conn: &mut PgConnection,
+    items_to_insert: &[CurrentTokenV2Metadata],
+) -> Result<(), diesel::result::Error> {
+    use schema::current_token_v2_metadata::dsl::*;
+
+    let chunks = get_chunks(items_to_insert.len(), CurrentTokenV2Metadata::field_count());
+
+    for (start_ind, end_ind) in chunks {
+        execute_with_better_error(
+            conn,
+            diesel::insert_into(schema::current_token_v2_metadata::table)
+                .values(&items_to_insert[start_ind..end_ind])
+                .on_conflict((object_address, resource_type))
+                .do_update()
+                .set((
+                    data.eq(excluded(data)),
+                    state_key_hash.eq(excluded(state_key_hash)),
+                    last_transaction_version.eq(excluded(last_transaction_version)),
+                    inserted_at.eq(excluded(inserted_at)),
+                )),
+            Some(" WHERE current_token_v2_metadata.last_transaction_version <= excluded.last_transaction_version "),
+        )?;
+    }
+    Ok(())
+}
+
 #[async_trait]
 impl TransactionProcessor for TokenTransactionProcessor {
     fn name(&self) -> &'static str {
@@ -925,6 +980,7 @@ impl TransactionProcessor for TokenTransactionProcessor {
             current_token_ownerships_v2,
             current_token_datas_v2,
             token_activities_v2,
+            current_token_v2_metadata,
         ) = parse_v2_token(&transactions, &table_handle_to_owner, &mut conn);
 
         let tx_result = insert_to_db(
@@ -956,6 +1012,7 @@ impl TransactionProcessor for TokenTransactionProcessor {
                 current_token_ownerships_v2,
                 current_token_datas_v2,
                 token_activities_v2,
+                current_token_v2_metadata,
             ),
         );
         match tx_result {
@@ -990,6 +1047,7 @@ fn parse_v2_token(
     Vec,
     Vec,
     Vec,
+    Vec,
 ) {
     // Token V2 and V1 combined
     let mut collections_v2 = vec![];
@@ -1009,7 +1067,10 @@ fn parse_v2_token(
     // Get Metadata for token v2 by object
     // We want to persist this through the entire batch so that even if a token is burned,
     // we can still get the object core metadata for it
-    let mut token_v2_metadata: TokenV2AggregatedDataMapping = HashMap::new();
+    let mut token_v2_metadata_helper: TokenV2AggregatedDataMapping = HashMap::new();
+    // Basically token properties
+    let mut current_token_v2_metadata: HashMap =
+        HashMap::new();
 
     // Code above is inefficient (multiple passthroughs) so I'm approaching TokenV2 with a cleaner code structure
     for txn in transactions {
@@ -1029,19 +1090,21 @@ fn parse_v2_token(
             // Need to do a first pass to get all the objects
             for (_, wsc) in user_txn.info.changes.iter().enumerate() {
                 if let WriteSetChange::WriteResource(wr) = wsc {
-                    if let Some(object_core) =
-                        ObjectCore::from_write_resource(wr, txn_version).unwrap()
+                    if let Some(object) =
+                        ObjectWithMetadata::from_write_resource(wr, txn_version).unwrap()
                     {
-                        token_v2_metadata.insert(
+                        token_v2_metadata_helper.insert(
                             standardize_address(&wr.address.to_string()),
                             TokenV2AggregatedData {
                                 aptos_collection: None,
                                 fixed_supply: None,
-                                object: object_core,
+                                object,
                                 unlimited_supply: None,
                                 property_map: None,
                                 transfer_event: None,
                                 token: None,
+                                fungible_asset_metadata: None,
+                                fungible_asset_supply: None,
                             },
                         );
                     }
@@ -1052,7 +1115,7 @@ fn parse_v2_token(
             for (_, wsc) in user_txn.info.changes.iter().enumerate() {
                 if let WriteSetChange::WriteResource(wr) = wsc {
                     let address = standardize_address(&wr.address.to_string());
-                    if let Some(aggregated_data) = token_v2_metadata.get_mut(&address) {
+                    if let Some(aggregated_data) = token_v2_metadata_helper.get_mut(&address) {
                         if let Some(fixed_supply) =
                             FixedSupply::from_write_resource(wr, txn_version).unwrap()
                         {
@@ -1077,6 +1140,16 @@ fn parse_v2_token(
                         {
                             aggregated_data.token = Some(token);
                         }
+                        if let Some(fungible_asset_metadata) =
+                            FungibleAssetMetadata::from_write_resource(wr, txn_version).unwrap()
+                        {
+                            aggregated_data.fungible_asset_metadata = Some(fungible_asset_metadata);
+                        }
+                        if let Some(fungible_asset_supply) =
+                            FungibleAssetSupply::from_write_resource(wr, txn_version).unwrap()
+                        {
+                            aggregated_data.fungible_asset_supply = Some(fungible_asset_supply);
+                        }
                     }
                 }
             }
@@ -1091,7 +1164,7 @@ fn parse_v2_token(
                 if let Some(transfer_event) = TransferEvent::from_event(event, txn_version).unwrap()
                 {
                     if let Some(aggregated_data) =
-                        token_v2_metadata.get_mut(&transfer_event.get_object_address())
+                        token_v2_metadata_helper.get_mut(&transfer_event.get_object_address())
                     {
                         // we don't want index to be 0 otherwise we might have collision with write set change index
                         let index = if index == 0 {
@@ -1121,7 +1194,7 @@ fn parse_v2_token(
                     txn_timestamp,
                     index as i64,
                     &entry_function_id_str,
-                    &token_v2_metadata,
+                    &token_v2_metadata_helper,
                 )
                 .unwrap()
                 {
@@ -1237,7 +1310,7 @@ fn parse_v2_token(
                                 txn_version,
                                 wsc_index,
                                 txn_timestamp,
-                                &token_v2_metadata,
+                                &token_v2_metadata_helper,
                             )
                             .unwrap()
                         {
@@ -1253,28 +1326,77 @@ fn parse_v2_token(
                                 txn_version,
                                 wsc_index,
                                 txn_timestamp,
-                                &token_v2_metadata,
+                                &token_v2_metadata_helper,
                             )
                             .unwrap()
                         {
                             // Add NFT ownership
-                            let (
-                                nft_ownership,
-                                current_nft_ownership,
-                                from_nft_ownership,
-                                from_current_nft_ownership,
-                            ) = TokenOwnershipV2::get_nft_v2_from_token_data(
+                            if let Some(inner) = TokenOwnershipV2::get_nft_v2_from_token_data(
                                 &token_data,
-                                &token_v2_metadata,
+                                &token_v2_metadata_helper,
                             )
-                            .unwrap();
+                            .unwrap()
+                            {
+                                let (
+                                    nft_ownership,
+                                    current_nft_ownership,
+                                    from_nft_ownership,
+                                    from_current_nft_ownership,
+                                ) = inner;
+                                token_ownerships_v2.push(nft_ownership);
+                                // this is used to persist latest owner for burn event handling
+                                prior_nft_ownership.insert(
+                                    current_nft_ownership.token_data_id.clone(),
+                                    NFTOwnershipV2 {
+                                        token_data_id: current_nft_ownership.token_data_id.clone(),
+                                        owner_address: current_nft_ownership.owner_address.clone(),
+                                        is_soulbound: current_nft_ownership.is_soulbound_v2,
+                                    },
+                                );
+                                current_token_ownerships_v2.insert(
+                                    (
+                                        current_nft_ownership.token_data_id.clone(),
+                                        current_nft_ownership.property_version_v1.clone(),
+                                        current_nft_ownership.owner_address.clone(),
+                                        current_nft_ownership.storage_id.clone(),
+                                    ),
+                                    current_nft_ownership,
+                                );
+                                // Add the previous owner of the token transfer
+                                if let Some(from_nft_ownership) = from_nft_ownership {
+                                    let from_current_nft_ownership =
+                                        from_current_nft_ownership.unwrap();
+                                    token_ownerships_v2.push(from_nft_ownership);
+                                    current_token_ownerships_v2.insert(
+                                        (
+                                            from_current_nft_ownership.token_data_id.clone(),
+                                            from_current_nft_ownership.property_version_v1.clone(),
+                                            from_current_nft_ownership.owner_address.clone(),
+                                            from_current_nft_ownership.storage_id.clone(),
+                                        ),
+                                        from_current_nft_ownership,
+                                    );
+                                }
+                            }
                             token_datas_v2.push(token_data);
                             current_token_datas_v2.insert(
                                 current_token_data.token_data_id.clone(),
                                 current_token_data,
                             );
+                        }
+
+                        // Add burned NFT handling
+                        if let Some((nft_ownership, current_nft_ownership)) =
+                            TokenOwnershipV2::get_burned_nft_v2_from_write_resource(
+                                resource,
+                                txn_version,
+                                wsc_index,
+                                txn_timestamp,
+                                &tokens_burned,
+                            )
+                            .unwrap()
+                        {
                             token_ownerships_v2.push(nft_ownership);
-                            // this is used to persist latest owner for burn event handling
                             prior_nft_ownership.insert(
                                 current_nft_ownership.token_data_id.clone(),
                                 NFTOwnershipV2 {
@@ -1292,52 +1414,46 @@ fn parse_v2_token(
                                 ),
                                 current_nft_ownership,
                             );
-                            // Add the previous owner of the token transfer
-                            if let Some(from_nft_ownership) = from_nft_ownership {
-                                let from_current_nft_ownership =
-                                    from_current_nft_ownership.unwrap();
-                                token_ownerships_v2.push(from_nft_ownership);
-                                current_token_ownerships_v2.insert(
-                                    (
-                                        from_current_nft_ownership.token_data_id.clone(),
-                                        from_current_nft_ownership.property_version_v1.clone(),
-                                        from_current_nft_ownership.owner_address.clone(),
-                                        from_current_nft_ownership.storage_id.clone(),
-                                    ),
-                                    from_current_nft_ownership,
-                                );
-                            }
+                        }
 
-                            // Add burned NFT handling
-                            if let Some((nft_ownership, current_nft_ownership)) =
-                                TokenOwnershipV2::get_burned_nft_v2_from_write_resource(
-                                    resource,
-                                    txn_version,
-                                    wsc_index,
-                                    txn_timestamp,
-                                    &tokens_burned,
-                                )
-                                .unwrap()
-                            {
-                                token_ownerships_v2.push(nft_ownership);
-                                prior_nft_ownership.insert(
-                                    current_nft_ownership.token_data_id.clone(),
-                                    NFTOwnershipV2 {
-                                        token_data_id: current_nft_ownership.token_data_id.clone(),
-                                        owner_address: current_nft_ownership.owner_address.clone(),
-                                        is_soulbound: current_nft_ownership.is_soulbound_v2,
-                                    },
-                                );
-                                current_token_ownerships_v2.insert(
-                                    (
-                                        current_nft_ownership.token_data_id.clone(),
-                                        current_nft_ownership.property_version_v1.clone(),
-                                        current_nft_ownership.owner_address.clone(),
-                                        current_nft_ownership.storage_id.clone(),
-                                    ),
-                                    current_nft_ownership,
-                                );
-                            }
+                        // Add fungible token handling
+                        if let Some((ft_ownership, current_ft_ownership)) =
+                            TokenOwnershipV2::get_ft_v2_from_write_resource(
+                                resource,
+                                txn_version,
+                                wsc_index,
+                                txn_timestamp,
+                                &token_v2_metadata_helper,
+                            )
+                            .unwrap()
+                        {
+                            token_ownerships_v2.push(ft_ownership);
+                            current_token_ownerships_v2.insert(
+                                (
+                                    current_ft_ownership.token_data_id.clone(),
+                                    current_ft_ownership.property_version_v1.clone(),
+                                    current_ft_ownership.owner_address.clone(),
+                                    current_ft_ownership.storage_id.clone(),
+                                ),
+                                current_ft_ownership,
+                            );
+                        }
+
+                        // Track token properties
+                        if let Some(token_metadata) = CurrentTokenV2Metadata::from_write_resource(
+                            resource,
+                            txn_version,
+                            &token_v2_metadata_helper,
+                        )
+                        .unwrap()
+                        {
+                            current_token_v2_metadata.insert(
+                                (
+                                    token_metadata.object_address.clone(),
+                                    token_metadata.resource_type.clone(),
+                                ),
+                                token_metadata,
+                            );
                         }
                     },
                     WriteSetChange::DeleteResource(resource) => {
@@ -1390,6 +1506,9 @@ fn parse_v2_token(
     let mut current_token_ownerships_v2 = current_token_ownerships_v2
         .into_values()
         .collect::>();
+    let mut current_token_v2_metadata = current_token_v2_metadata
+        .into_values()
+        .collect::>();
 
     // Sort by PK
     current_collections_v2.sort_by(|a, b| a.collection_id.cmp(&b.collection_id));
@@ -1408,6 +1527,9 @@ fn parse_v2_token(
                 &b.storage_id,
             ))
     });
+    current_token_v2_metadata.sort_by(|a, b| {
+        (&a.object_address, &a.resource_type).cmp(&(&b.object_address, &b.resource_type))
+    });
 
     (
         collections_v2,
@@ -1417,5 +1539,6 @@ fn parse_v2_token(
         current_token_datas_v2,
         current_token_ownerships_v2,
         token_activities_v2,
+        current_token_v2_metadata,
     )
 }
diff --git a/crates/indexer/src/schema.rs b/crates/indexer/src/schema.rs
index acdff3ee82739..72e28c765dfea 100644
--- a/crates/indexer/src/schema.rs
+++ b/crates/indexer/src/schema.rs
@@ -285,6 +285,7 @@ diesel::table! {
         last_transaction_version -> Int8,
         last_transaction_timestamp -> Timestamp,
         inserted_at -> Timestamp,
+        decimals -> Int8,
     }
 }
 
@@ -321,6 +322,7 @@ diesel::table! {
         last_transaction_version -> Int8,
         last_transaction_timestamp -> Timestamp,
         inserted_at -> Timestamp,
+        non_transferrable_by_owner -> Nullable,
     }
 }
 
@@ -344,6 +346,17 @@ diesel::table! {
     }
 }
 
+diesel::table! {
+    current_token_v2_metadata (object_address, resource_type) {
+        object_address -> Varchar,
+        resource_type -> Varchar,
+        data -> Jsonb,
+        state_key_hash -> Varchar,
+        last_transaction_version -> Int8,
+        inserted_at -> Timestamp,
+    }
+}
+
 diesel::table! {
     delegated_staking_activities (transaction_version, event_index) {
         transaction_version -> Int8,
@@ -628,6 +641,7 @@ diesel::table! {
         is_fungible_v2 -> Nullable,
         transaction_timestamp -> Timestamp,
         inserted_at -> Timestamp,
+        decimals -> Int8,
     }
 }
 
@@ -665,6 +679,7 @@ diesel::table! {
         is_fungible_v2 -> Nullable,
         transaction_timestamp -> Timestamp,
         inserted_at -> Timestamp,
+        non_transferrable_by_owner -> Nullable,
     }
 }
 
@@ -757,6 +772,7 @@ diesel::allow_tables_to_appear_in_same_query!(
     current_token_ownerships,
     current_token_ownerships_v2,
     current_token_pending_claims,
+    current_token_v2_metadata,
     delegated_staking_activities,
     delegated_staking_pool_balances,
     delegated_staking_pools,

From 015bc88e7091c423ac454a886d0706b8c61ec77d Mon Sep 17 00:00:00 2001
From: Teng Zhang 
Date: Tue, 13 Jun 2023 16:05:56 -0700
Subject: [PATCH 158/200] fix aptos account spec block (#8640)

---
 .../aptos-framework/doc/aptos_account.md      | 28 ++++++-------------
 .../sources/aptos_account.move                | 23 ++++-----------
 .../sources/aptos_account.spec.move           |  5 +++-
 3 files changed, 18 insertions(+), 38 deletions(-)

diff --git a/aptos-move/framework/aptos-framework/doc/aptos_account.md b/aptos-move/framework/aptos-framework/doc/aptos_account.md
index 6ee25c8673858..80fc8816f34f9 100644
--- a/aptos-move/framework/aptos-framework/doc/aptos_account.md
+++ b/aptos-move/framework/aptos-framework/doc/aptos_account.md
@@ -273,12 +273,6 @@ Batch version of transfer_coins.
 
 
public entry fun batch_transfer_coins<CoinType>(
     from: &signer, recipients: vector<address>, amounts: vector<u64>) acquires DirectTransferConfig {
-    spec {
-    // Cointype should not be aptoscoin, otherwise it will automaticly create an account.
-    // Meanwhile, aptoscoin has already been proved in normal tranfer
-    use aptos_std::type_info;
-    assume type_info::type_of<CoinType>() != type_info::type_of<AptosCoin>();
-    };
     let recipients_len = vector::length(&recipients);
     assert!(
         recipients_len == vector::length(&amounts),
@@ -314,12 +308,6 @@ This would create the recipient account first and register it to receive the Coi
 
 
 
public entry fun transfer_coins<CoinType>(from: &signer, to: address, amount: u64) acquires DirectTransferConfig {
-    spec {
-    // Cointype should not be aptoscoin, otherwise it will automaticly create an account.
-    // Meanwhile, aptoscoin has already been proved in normal tranfer
-    use aptos_std::type_info;
-    assume type_info::type_of<CoinType>() != type_info::type_of<AptosCoin>();
-    };
     deposit_coins(to, coin::withdraw<CoinType>(from, amount));
 }
 

@@ -346,14 +334,13 @@ This would create the recipient account first and register it to receive the Coi
 
 
 
public fun deposit_coins<CoinType>(to: address, coins: Coin<CoinType>) acquires DirectTransferConfig {
-    spec {
-    // Cointype should not be aptoscoin, otherwise it will automaticly create an account.
-    // Meanwhile, aptoscoin has already been proved in normal tranfer
-    use aptos_std::type_info;
-    assume type_info::type_of<CoinType>() != type_info::type_of<AptosCoin>();
-    };
     if (!account::exists_at(to)) {
         create_account(to);
+        spec {
+            assert coin::is_account_registered<AptosCoin>(to);
+            assume aptos_std::type_info::type_of<CoinType>() == aptos_std::type_info::type_of<AptosCoin>() ==>
+                coin::is_account_registered<CoinType>(to);
+        };
     };
     if (!coin::is_account_registered<CoinType>(to)) {
         assert!(
@@ -741,7 +728,10 @@ Limit the address of auth_key is not @vm_reserved / @aptos_framework / @aptos_to
 
schema RegistCoinAbortsIf<CoinType> {
     to: address;
     aborts_if !coin::is_account_registered<CoinType>(to) && !type_info::spec_is_struct<CoinType>();
-    aborts_if !coin::is_account_registered<CoinType>(to) && !can_receive_direct_coin_transfers(to);
+    aborts_if exists<aptos_framework::account::Account>(to)
+        && !coin::is_account_registered<CoinType>(to) && !can_receive_direct_coin_transfers(to);
+    aborts_if type_info::type_of<CoinType>() != type_info::type_of<AptosCoin>()
+        && !coin::is_account_registered<CoinType>(to) && !can_receive_direct_coin_transfers(to);
 }
 

 
diff --git a/aptos-move/framework/aptos-framework/sources/aptos_account.move b/aptos-move/framework/aptos-framework/sources/aptos_account.move
index 9eeb66bdab2e8..c58395714d113 100644
--- a/aptos-move/framework/aptos-framework/sources/aptos_account.move
+++ b/aptos-move/framework/aptos-framework/sources/aptos_account.move
@@ -75,12 +75,6 @@ module aptos_framework::aptos_account {
     /// Batch version of transfer_coins.
     public entry fun batch_transfer_coins(
         from: &signer, recipients: vector
, amounts: vector) acquires DirectTransferConfig {
-        spec {
-        // Cointype should not be aptoscoin, otherwise it will automaticly create an account.
-        // Meanwhile, aptoscoin has already been proved in normal tranfer
-        use aptos_std::type_info;
-        assume type_info::type_of() != type_info::type_of();
-        };
         let recipients_len = vector::length(&recipients);
         assert!(
             recipients_len == vector::length(&amounts),
@@ -96,26 +90,19 @@ module aptos_framework::aptos_account {
     /// Convenient function to transfer a custom CoinType to a recipient account that might not exist.
     /// This would create the recipient account first and register it to receive the CoinType, before transferring.
     public entry fun transfer_coins(from: &signer, to: address, amount: u64) acquires DirectTransferConfig {
-        spec {
-        // Cointype should not be aptoscoin, otherwise it will automaticly create an account.
-        // Meanwhile, aptoscoin has already been proved in normal tranfer
-        use aptos_std::type_info;
-        assume type_info::type_of() != type_info::type_of();
-        };
         deposit_coins(to, coin::withdraw(from, amount));
     }
 
     /// Convenient function to deposit a custom CoinType into a recipient account that might not exist.
     /// This would create the recipient account first and register it to receive the CoinType, before transferring.
     public fun deposit_coins(to: address, coins: Coin) acquires DirectTransferConfig {
-        spec {
-        // Cointype should not be aptoscoin, otherwise it will automaticly create an account.
-        // Meanwhile, aptoscoin has already been proved in normal tranfer
-        use aptos_std::type_info;
-        assume type_info::type_of() != type_info::type_of();
-        };
         if (!account::exists_at(to)) {
             create_account(to);
+            spec {
+                assert coin::is_account_registered(to);
+                assume aptos_std::type_info::type_of() == aptos_std::type_info::type_of() ==>
+                    coin::is_account_registered(to);
+            };
         };
         if (!coin::is_account_registered(to)) {
             assert!(
diff --git a/aptos-move/framework/aptos-framework/sources/aptos_account.spec.move b/aptos-move/framework/aptos-framework/sources/aptos_account.spec.move
index d1a4e18cee1b8..661bd0414a3c2 100644
--- a/aptos-move/framework/aptos-framework/sources/aptos_account.spec.move
+++ b/aptos-move/framework/aptos-framework/sources/aptos_account.spec.move
@@ -206,6 +206,9 @@ spec aptos_framework::aptos_account {
         use aptos_std::type_info;
         to: address;
         aborts_if !coin::is_account_registered(to) && !type_info::spec_is_struct();
-        aborts_if !coin::is_account_registered(to) && !can_receive_direct_coin_transfers(to);
+        aborts_if exists(to)
+            && !coin::is_account_registered(to) && !can_receive_direct_coin_transfers(to);
+        aborts_if type_info::type_of() != type_info::type_of()
+            && !coin::is_account_registered(to) && !can_receive_direct_coin_transfers(to);
     }
 }

From 37280edb9f3a0a5ea68e823e81cd1ef61da44ce7 Mon Sep 17 00:00:00 2001
From: Jin <128556004+0xjinn@users.noreply.github.com>
Date: Tue, 13 Jun 2023 18:01:44 -0700
Subject: [PATCH 159/200] set timeout to telemetry (#8647)

---
 crates/aptos/src/common/utils.rs | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/crates/aptos/src/common/utils.rs b/crates/aptos/src/common/utils.rs
index 8bacbd1b4d849..0a9c766ff3074 100644
--- a/crates/aptos/src/common/utils.rs
+++ b/crates/aptos/src/common/utils.rs
@@ -35,6 +35,7 @@ use std::{
     str::FromStr,
     time::{Duration, Instant, SystemTime},
 };
+use tokio::time::timeout;
 
 /// Prompts for confirmation until a yes or no is given explicitly
 pub fn prompt_yes(prompt: &str) -> bool {
@@ -81,7 +82,15 @@ pub async fn to_common_result(
         } else {
             None
         };
-        send_telemetry_event(command, latency, !is_err, error).await;
+
+        if let Err(err) = timeout(
+            Duration::from_millis(2000),
+            send_telemetry_event(command, latency, !is_err, error),
+        )
+        .await
+        {
+            debug!("send_telemetry_event timeout from CLI: {}", err.to_string())
+        }
     }
 
     let result: ResultWrapper = result.into();

From c9a3d5cd9c999da0d7d2b8871d6456da175e0c9d Mon Sep 17 00:00:00 2001
From: Kevin <105028215+movekevin@users.noreply.github.com>
Date: Tue, 13 Jun 2023 20:03:23 -0500
Subject: [PATCH 160/200] Fix the order of signer and non-signer tx arg
 validation to maintain backward compatibility (#8649)

---
 .../verifier/transaction_arg_validation.rs    | 25 +++++++++++--------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/aptos-move/aptos-vm/src/verifier/transaction_arg_validation.rs b/aptos-move/aptos-vm/src/verifier/transaction_arg_validation.rs
index ec00229ebe57d..3807eceb29e4d 100644
--- a/aptos-move/aptos-vm/src/verifier/transaction_arg_validation.rs
+++ b/aptos-move/aptos-vm/src/verifier/transaction_arg_validation.rs
@@ -149,6 +149,20 @@ pub(crate) fn validate_combine_signer_and_txn_args(
         ));
     }
 
+    // If the invoked function expects one or more signers, we need to check that the number of
+    // signers actually passed is matching first to maintain backward compatibility before
+    // moving on to the validation of non-signer args.
+    // the number of txn senders should be the same number of signers
+    if signer_param_cnt > 0 && senders.len() != signer_param_cnt {
+        return Err(VMStatus::Error(
+            StatusCode::NUMBER_OF_SIGNER_ARGUMENTS_MISMATCH,
+            None,
+        ));
+    }
+
+    // This also validates that the args are valid. If they are structs, they have to be allowed
+    // and must be constructed successfully. If construction fails, this would fail with a
+    // FAILED_TO_DESERIALIZE_ARGUMENT error.
     let args = construct_args(
         session,
         &func.parameters[signer_param_cnt..],
@@ -158,19 +172,10 @@ pub(crate) fn validate_combine_signer_and_txn_args(
         false,
     )?;
 
-    // if function doesn't require signer, we reuse txn args
-    // if the function require signer, we check senders number same as signers
-    // and then combine senders with txn args.
+    // Combine signer and non-signer arguments.
     let combined_args = if signer_param_cnt == 0 {
         args
     } else {
-        // the number of txn senders should be the same number of signers
-        if senders.len() != signer_param_cnt {
-            return Err(VMStatus::Error(
-                StatusCode::NUMBER_OF_SIGNER_ARGUMENTS_MISMATCH,
-                None,
-            ));
-        }
         senders
             .into_iter()
             .map(|s| MoveValue::Signer(s).simple_serialize().unwrap())

From 89f950b28b2c2f5e270d877160e6007a2d8d25a6 Mon Sep 17 00:00:00 2001
From: aldenhu 
Date: Tue, 13 Jun 2023 20:59:36 +0000
Subject: [PATCH 161/200] disable state metadata tracking for devnet

---
 ...estsuite__tests__create_account__create_account.exp |  4 ++--
 ...testsuite__tests__data_store__borrow_after_move.exp |  6 +++---
 ...testsuite__tests__data_store__change_after_move.exp |  6 +++---
 ...ite__tests__data_store__move_from_across_blocks.exp | 10 +++++-----
 ...ite__tests__module_publishing__duplicate_module.exp |  2 +-
 ...ts__module_publishing__layout_compatible_module.exp |  2 +-
 ...__layout_incompatible_module_with_changed_field.exp |  2 +-
 ...hing__layout_incompatible_module_with_new_field.exp |  2 +-
 ...__layout_incompatible_module_with_removed_field.exp |  2 +-
 ..._layout_incompatible_module_with_removed_struct.exp |  2 +-
 ...s__module_publishing__linking_compatible_module.exp |  2 +-
 ...g__linking_incompatible_module_with_added_param.exp |  2 +-
 ..._linking_incompatible_module_with_changed_param.exp |  2 +-
 ...linking_incompatible_module_with_removed_pub_fn.exp |  2 +-
 ...odule_publishing__test_publishing_allow_modules.exp |  2 +-
 ...blishing__test_publishing_modules_proper_sender.exp |  2 +-
 ...tsuite__tests__verify_txn__test_open_publishing.exp |  2 +-
 aptos-move/vm-genesis/src/lib.rs                       |  1 -
 types/src/on_chain_config/aptos_features.rs            |  2 +-
 19 files changed, 27 insertions(+), 28 deletions(-)

diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__create_account__create_account.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__create_account__create_account.exp
index 84263f8206da2..17341c0156fdb 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__create_account__create_account.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__create_account__create_account.exp
@@ -16,13 +16,13 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 01000000000000000000000000000000000000000000000000000000000000000104636f696e09436f696e53746f7265010700000000000000000000000000000000000000000000000000000000000000010a6170746f735f636f696e094170746f73436f696e00 },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(00000000000000000000000000000000000200000000000000f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100000000000000000300000000000000f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, metadata:V0 { payer: 000000000000000000000000000000000000000000000000000000000a550c18, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(00000000000000000000000000000000000200000000000000f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100000000000000000300000000000000f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1),
                             StateKey {
                                 inner: AccessPath(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 010000000000000000000000000000000000000000000000000000000000000001076163636f756e74074163636f756e7400 },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(20f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe10000000000000000040000000000000001000000000000000000000000000000f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100000000000000000100000000000000f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe10000, metadata:V0 { payer: 000000000000000000000000000000000000000000000000000000000a550c18, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(20f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe10000000000000000040000000000000001000000000000000000000000000000f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100000000000000000100000000000000f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe10000),
                         },
                     },
                 ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__borrow_after_move.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__borrow_after_move.exp
index 46f394a775780..57f85b57237ed 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__borrow_after_move.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__borrow_after_move.exp
@@ -10,7 +10,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 00f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(a11ceb0b06000000090100040204040308190521140735420877400ab701050cbc014f0d8b020200000101000208000003000100000402010000050001000006000100010800040001060c0002060c03010608000105010708000103014d067369676e657202543109626f72726f775f7431096368616e67655f74310972656d6f76655f74310a7075626c6973685f743101760a616464726573735f6f66f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100000000000000000000000000000000000000000000000000000000000000010002010703000100010003050b0011042b000c0102010100010005090b0011042a000c020b010b020f001502020100010006060b0011042c0013000c01020301000001050b0006030000000000000012002d0002000000, metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(a11ceb0b06000000090100040204040308190521140735420877400ab701050cbc014f0d8b020200000101000208000003000100000402010000050001000006000100010800040001060c0002060c03010608000105010708000103014d067369676e657202543109626f72726f775f7431096368616e67655f74310972656d6f76655f74310a7075626c6973685f743101760a616464726573735f6f66f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100000000000000000000000000000000000000000000000000000000000000010002010703000100010003050b0011042b000c0102010100010005090b0011042a000c020b010b020f001502020100010006060b0011042c0013000c01020301000001050b0006030000000000000012002d0002000000),
                             StateKey {
                                 inner: AccessPath(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 010000000000000000000000000000000000000000000000000000000000000001076163636f756e74074163636f756e7400 },
@@ -76,7 +76,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 01f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d02543100 },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(0300000000000000, metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(0300000000000000),
                         },
                     },
                 ),
@@ -132,7 +132,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 01f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d02543100 },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: DeletionWithMetadata(metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Deletion,
                         },
                     },
                 ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__change_after_move.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__change_after_move.exp
index 34e03fa9b7997..07efb5e5c47cb 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__change_after_move.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__change_after_move.exp
@@ -10,7 +10,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 00f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(a11ceb0b06000000090100040204040308190521140735420877400ab701050cbc014f0d8b020200000101000208000003000100000402010000050001000006000100010800040001060c0002060c03010608000105010708000103014d067369676e657202543109626f72726f775f7431096368616e67655f74310972656d6f76655f74310a7075626c6973685f743101760a616464726573735f6f66f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100000000000000000000000000000000000000000000000000000000000000010002010703000100010003050b0011042b000c0102010100010005090b0011042a000c020b010b020f001502020100010006060b0011042c0013000c01020301000001050b0006030000000000000012002d0002000000, metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(a11ceb0b06000000090100040204040308190521140735420877400ab701050cbc014f0d8b020200000101000208000003000100000402010000050001000006000100010800040001060c0002060c03010608000105010708000103014d067369676e657202543109626f72726f775f7431096368616e67655f74310972656d6f76655f74310a7075626c6973685f743101760a616464726573735f6f66f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100000000000000000000000000000000000000000000000000000000000000010002010703000100010003050b0011042b000c0102010100010005090b0011042a000c020b010b020f001502020100010006060b0011042c0013000c01020301000001050b0006030000000000000012002d0002000000),
                             StateKey {
                                 inner: AccessPath(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 010000000000000000000000000000000000000000000000000000000000000001076163636f756e74074163636f756e7400 },
@@ -76,7 +76,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 01f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d02543100 },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(0300000000000000, metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(0300000000000000),
                         },
                     },
                 ),
@@ -132,7 +132,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 01f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d02543100 },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: DeletionWithMetadata(metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Deletion,
                         },
                     },
                 ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__move_from_across_blocks.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__move_from_across_blocks.exp
index 58b3ad0ddb48e..1bec780feaaed 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__move_from_across_blocks.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__data_store__move_from_across_blocks.exp
@@ -10,7 +10,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 00f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(a11ceb0b06000000090100040204040308190521140735420877400ab701050cbc014f0d8b020200000101000208000003000100000402010000050001000006000100010800040001060c0002060c03010608000105010708000103014d067369676e657202543109626f72726f775f7431096368616e67655f74310972656d6f76655f74310a7075626c6973685f743101760a616464726573735f6f66f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100000000000000000000000000000000000000000000000000000000000000010002010703000100010003050b0011042b000c0102010100010005090b0011042a000c020b010b020f001502020100010006060b0011042c0013000c01020301000001050b0006030000000000000012002d0002000000, metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(a11ceb0b06000000090100040204040308190521140735420877400ab701050cbc014f0d8b020200000101000208000003000100000402010000050001000006000100010800040001060c0002060c03010608000105010708000103014d067369676e657202543109626f72726f775f7431096368616e67655f74310972656d6f76655f74310a7075626c6973685f743101760a616464726573735f6f66f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100000000000000000000000000000000000000000000000000000000000000010002010703000100010003050b0011042b000c0102010100010005090b0011042a000c020b010b020f001502020100010006060b0011042c0013000c01020301000001050b0006030000000000000012002d0002000000),
                             StateKey {
                                 inner: AccessPath(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 010000000000000000000000000000000000000000000000000000000000000001076163636f756e74074163636f756e7400 },
@@ -76,7 +76,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 01f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d02543100 },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(0300000000000000, metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(0300000000000000),
                         },
                     },
                 ),
@@ -132,7 +132,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 01f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d02543100 },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: DeletionWithMetadata(metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Deletion,
                         },
                     },
                 ),
@@ -221,7 +221,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 01f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d02543100 },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(0300000000000000, metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(0300000000000000),
                         },
                     },
                 ),
@@ -252,7 +252,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 01f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d02543100 },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: DeletionWithMetadata(metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Deletion,
                         },
                     },
                 ),
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__duplicate_module.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__duplicate_module.exp
index c24a0e1dd2c19..805da66d61fab 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__duplicate_module.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__duplicate_module.exp
@@ -10,7 +10,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 00f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(a11ceb0b0600000008010002020204030605050b01070c060812200a32050c3707000000010000000200000000014d01540166f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100020102030001000000010200, metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(a11ceb0b0600000008010002020204030605050b01070c060812200a32050c3707000000010000000200000000014d01540166f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100020102030001000000010200),
                             StateKey {
                                 inner: AccessPath(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 010000000000000000000000000000000000000000000000000000000000000001076163636f756e74074163636f756e7400 },
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_compatible_module.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_compatible_module.exp
index ee8f4d0153450..e706de32425ce 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_compatible_module.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_compatible_module.exp
@@ -10,7 +10,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 00f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(a11ceb0b06000000030100020702020804200000014df5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100, metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(a11ceb0b06000000030100020702020804200000014df5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100),
                             StateKey {
                                 inner: AccessPath(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 010000000000000000000000000000000000000000000000000000000000000001076163636f756e74074163636f756e7400 },
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_changed_field.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_changed_field.exp
index 8bd4038e2d42a..8548cf8bda8f5 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_changed_field.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_changed_field.exp
@@ -10,7 +10,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 00f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(a11ceb0b0600000005010002020204070606080c200a2c05000000010000014d01540166f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1000201020300, metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(a11ceb0b0600000005010002020204070606080c200a2c05000000010000014d01540166f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1000201020300),
                             StateKey {
                                 inner: AccessPath(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 010000000000000000000000000000000000000000000000000000000000000001076163636f756e74074163636f756e7400 },
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_new_field.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_new_field.exp
index 8bd4038e2d42a..8548cf8bda8f5 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_new_field.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_new_field.exp
@@ -10,7 +10,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 00f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(a11ceb0b0600000005010002020204070606080c200a2c05000000010000014d01540166f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1000201020300, metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(a11ceb0b0600000005010002020204070606080c200a2c05000000010000014d01540166f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1000201020300),
                             StateKey {
                                 inner: AccessPath(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 010000000000000000000000000000000000000000000000000000000000000001076163636f756e74074163636f756e7400 },
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_removed_field.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_removed_field.exp
index 8bd4038e2d42a..8548cf8bda8f5 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_removed_field.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_removed_field.exp
@@ -10,7 +10,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 00f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(a11ceb0b0600000005010002020204070606080c200a2c05000000010000014d01540166f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1000201020300, metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(a11ceb0b0600000005010002020204070606080c200a2c05000000010000014d01540166f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1000201020300),
                             StateKey {
                                 inner: AccessPath(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 010000000000000000000000000000000000000000000000000000000000000001076163636f756e74074163636f756e7400 },
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_removed_struct.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_removed_struct.exp
index 8bd4038e2d42a..8548cf8bda8f5 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_removed_struct.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__layout_incompatible_module_with_removed_struct.exp
@@ -10,7 +10,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 00f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(a11ceb0b0600000005010002020204070606080c200a2c05000000010000014d01540166f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1000201020300, metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(a11ceb0b0600000005010002020204070606080c200a2c05000000010000014d01540166f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1000201020300),
                             StateKey {
                                 inner: AccessPath(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 010000000000000000000000000000000000000000000000000000000000000001076163636f756e74074163636f756e7400 },
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_compatible_module.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_compatible_module.exp
index ee8f4d0153450..e706de32425ce 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_compatible_module.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_compatible_module.exp
@@ -10,7 +10,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 00f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(a11ceb0b06000000030100020702020804200000014df5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100, metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(a11ceb0b06000000030100020702020804200000014df5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100),
                             StateKey {
                                 inner: AccessPath(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 010000000000000000000000000000000000000000000000000000000000000001076163636f756e74074163636f756e7400 },
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_added_param.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_added_param.exp
index 8668be844e8f5..161b4225a8fb9 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_added_param.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_added_param.exp
@@ -10,7 +10,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 00f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(a11ceb0b0600000006010002030205050701070804080c200c2c070000000100000000014d0166f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe10001000000010200, metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(a11ceb0b0600000006010002030205050701070804080c200c2c070000000100000000014d0166f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe10001000000010200),
                             StateKey {
                                 inner: AccessPath(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 010000000000000000000000000000000000000000000000000000000000000001076163636f756e74074163636f756e7400 },
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_changed_param.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_changed_param.exp
index 5eb0507d71852..2ade87987f340 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_changed_param.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_changed_param.exp
@@ -10,7 +10,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 00f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(a11ceb0b0600000006010002030205050703070a04080e200c2e0700000001000100010300014d0166f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe10001000001010200, metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(a11ceb0b0600000006010002030205050703070a04080e200c2e0700000001000100010300014d0166f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe10001000001010200),
                             StateKey {
                                 inner: AccessPath(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 010000000000000000000000000000000000000000000000000000000000000001076163636f756e74074163636f756e7400 },
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_removed_pub_fn.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_removed_pub_fn.exp
index 8668be844e8f5..161b4225a8fb9 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_removed_pub_fn.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__linking_incompatible_module_with_removed_pub_fn.exp
@@ -10,7 +10,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 00f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(a11ceb0b0600000006010002030205050701070804080c200c2c070000000100000000014d0166f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe10001000000010200, metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(a11ceb0b0600000006010002030205050701070804080c200c2c070000000100000000014d0166f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe10001000000010200),
                             StateKey {
                                 inner: AccessPath(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 010000000000000000000000000000000000000000000000000000000000000001076163636f756e74074163636f756e7400 },
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__test_publishing_allow_modules.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__test_publishing_allow_modules.exp
index 595e781ad7ea7..bcf854c1f7b71 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__test_publishing_allow_modules.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__test_publishing_allow_modules.exp
@@ -10,7 +10,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 00f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(a11ceb0b06000000030100020702020804200000014df5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100, metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(a11ceb0b06000000030100020702020804200000014df5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe100),
                             StateKey {
                                 inner: AccessPath(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 010000000000000000000000000000000000000000000000000000000000000001076163636f756e74074163636f756e7400 },
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__test_publishing_modules_proper_sender.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__test_publishing_modules_proper_sender.exp
index ee6cb35fe097c..db6061ec50a87 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__test_publishing_modules_proper_sender.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__module_publishing__test_publishing_modules_proper_sender.exp
@@ -10,7 +10,7 @@ Ok(
                                     AccessPath { address: 000000000000000000000000000000000000000000000000000000000a550c18, path: 00000000000000000000000000000000000000000000000000000000000a550c18014d },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(a11ceb0b06000000030100020702020804200000014d000000000000000000000000000000000000000000000000000000000a550c1800, metadata:V0 { payer: 000000000000000000000000000000000000000000000000000000000a550c18, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(a11ceb0b06000000030100020702020804200000014d000000000000000000000000000000000000000000000000000000000a550c1800),
                             StateKey {
                                 inner: AccessPath(
                                     AccessPath { address: 000000000000000000000000000000000000000000000000000000000a550c18, path: 010000000000000000000000000000000000000000000000000000000000000001076163636f756e74074163636f756e7400 },
diff --git a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__verify_txn__test_open_publishing.exp b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__verify_txn__test_open_publishing.exp
index 05f6d9dbac873..1598d1d9730bd 100644
--- a/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__verify_txn__test_open_publishing.exp
+++ b/aptos-move/e2e-tests/goldens/language_e2e_testsuite__tests__verify_txn__test_open_publishing.exp
@@ -10,7 +10,7 @@ Ok(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 00f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1014d },
                                 ),
                                 hash: OnceCell(Uninit),
-                            }: CreationWithMetadata(a11ceb0b060000000601000203020a050c0607120a081c200c3c23000000010001000002000100020303010300014d036d61780373756df5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe10001000002080a000a012403060a01020a00020101000001060a000a01160c020a020200, metadata:V0 { payer: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, deposit: 0, creation_time_usecs: 0 }),
+                            }: Creation(a11ceb0b060000000601000203020a050c0607120a081c200c3c23000000010001000002000100020303010300014d036d61780373756df5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe10001000002080a000a012403060a01020a00020101000001060a000a01160c020a020200),
                             StateKey {
                                 inner: AccessPath(
                                     AccessPath { address: f5b9d6f01a99e74c790e2f330c092fa05455a8193f1dfc1b113ecc54d067afe1, path: 01000000000000000000000000000000000000000000000000000000000000000104636f696e09436f696e53746f7265010700000000000000000000000000000000000000000000000000000000000000010a6170746f735f636f696e094170746f73436f696e00 },
diff --git a/aptos-move/vm-genesis/src/lib.rs b/aptos-move/vm-genesis/src/lib.rs
index 0d26a9ddf0417..95516deea6444 100644
--- a/aptos-move/vm-genesis/src/lib.rs
+++ b/aptos-move/vm-genesis/src/lib.rs
@@ -409,7 +409,6 @@ pub fn default_features() -> Vec {
         FeatureFlag::STRUCT_CONSTRUCTORS,
         FeatureFlag::CRYPTOGRAPHY_ALGEBRA_NATIVES,
         FeatureFlag::BLS12_381_STRUCTURES,
-        FeatureFlag::STORAGE_SLOT_METADATA,
         FeatureFlag::CHARGE_INVARIANT_VIOLATION,
     ]
 }
diff --git a/types/src/on_chain_config/aptos_features.rs b/types/src/on_chain_config/aptos_features.rs
index 16f38e21189ad..52244f2156731 100644
--- a/types/src/on_chain_config/aptos_features.rs
+++ b/types/src/on_chain_config/aptos_features.rs
@@ -40,7 +40,7 @@ pub struct Features {
 impl Default for Features {
     fn default() -> Self {
         Features {
-            features: vec![0b00100000, 0b00100000, 0b00001100],
+            features: vec![0b00100000, 0b00100000, 0b00000100],
         }
     }
 }

From ddf2463fceeae02d6bb91d3ac869869b398cbef6 Mon Sep 17 00:00:00 2001
From: larry-aptos <112209412+larry-aptos@users.noreply.github.com>
Date: Wed, 14 Jun 2023 00:42:14 -0700
Subject: [PATCH 162/200] update the tls part for data service. (#8632)

---
 .../indexer-grpc-cache-worker/README.md       | 13 +--
 .../indexer-grpc-data-service/README.md       |  3 +
 .../indexer-grpc-data-service/src/main.rs     | 79 ++++++++++++++++---
 .../indexer-grpc-data-service/src/metrics.rs  |  4 +-
 .../indexer-grpc-data-service/src/service.rs  | 24 +++---
 .../indexer-grpc-utils/src/cache_operator.rs  |  2 +-
 6 files changed, 96 insertions(+), 29 deletions(-)

diff --git a/ecosystem/indexer-grpc/indexer-grpc-cache-worker/README.md b/ecosystem/indexer-grpc/indexer-grpc-cache-worker/README.md
index c8478b53b2978..0299c39364a72 100644
--- a/ecosystem/indexer-grpc/indexer-grpc-cache-worker/README.md
+++ b/ecosystem/indexer-grpc/indexer-grpc-cache-worker/README.md
@@ -12,10 +12,11 @@ Cache worker fetches data from fullnode GRPC and push data to Cache.
 
 * Yaml Example 
 ```yaml
-fullnode_grpc_address: 127.0.0.1:50051
-redis_address: 127.0.0.1:6379
-health_check_port: 8081
-file_store:
-    file_store_type: GcsFileStore
-    gcs_file_store_bucket_name: indexer-grpc-file-store-bucketname 
+health_check_port: 8083
+server_config:
+    fullnode_grpc_address: 0.0.0.0:50052
+    file_store_config:
+      file_store_type: GcsFileStore
+      gcs_file_store_bucket_name: indexer-grpc-file-store-bucketname
+    redis_main_instance_address: 127.0.0.1:6379
 ```
diff --git a/ecosystem/indexer-grpc/indexer-grpc-data-service/README.md b/ecosystem/indexer-grpc/indexer-grpc-data-service/README.md
index de6b6fe025496..667452f932fc4 100644
--- a/ecosystem/indexer-grpc/indexer-grpc-data-service/README.md
+++ b/ecosystem/indexer-grpc/indexer-grpc-data-service/README.md
@@ -22,6 +22,9 @@ server_config:
     file_store_config:
       file_store_type: GcsFileStore
       gcs_file_store_bucket_name: indexer-grpc-file-store-bucketname
+    data_service_grpc_tls_config:
+      cert_path: /path/to/cert.cert
+      key_path: /path/to/key.pem
     redis_read_replica_address: 127.0.0.1:6379
 ```
 
diff --git a/ecosystem/indexer-grpc/indexer-grpc-data-service/src/main.rs b/ecosystem/indexer-grpc/indexer-grpc-data-service/src/main.rs
index 646aa1611cd0d..f86b31ba33ff4 100644
--- a/ecosystem/indexer-grpc/indexer-grpc-data-service/src/main.rs
+++ b/ecosystem/indexer-grpc/indexer-grpc-data-service/src/main.rs
@@ -23,8 +23,24 @@ use tonic::{
 
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[serde(deny_unknown_fields)]
-pub struct IndexerGrpcDataServiceConfig {
+pub struct TlsConfig {
+    // TLS config.
     pub data_service_grpc_listen_address: String,
+    pub cert_path: String,
+    pub key_path: String,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct NonTlsConfig {
+    pub data_service_grpc_listen_address: String,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct IndexerGrpcDataServiceConfig {
+    pub data_service_grpc_tls_config: Option,
+    pub data_service_grpc_non_tls_config: Option,
     pub whitelisted_auth_tokens: Vec,
     pub file_store_config: IndexerGrpcFileStoreConfig,
     pub redis_read_replica_address: String,
@@ -33,8 +49,6 @@ pub struct IndexerGrpcDataServiceConfig {
 #[async_trait::async_trait]
 impl RunnableConfig for IndexerGrpcDataServiceConfig {
     async fn run(&self) -> Result<()> {
-        let grpc_address = self.data_service_grpc_listen_address.clone();
-
         let token_set = build_auth_token_set(self.whitelisted_auth_tokens.clone());
         let authentication_inceptor =
             move |req: Request<()>| -> std::result::Result, Status> {
@@ -61,7 +75,7 @@ impl RunnableConfig for IndexerGrpcDataServiceConfig {
             .register_encoded_file_descriptor_set(TRANSACTION_V1_TESTING_FILE_DESCRIPTOR_SET)
             .register_encoded_file_descriptor_set(UTIL_TIMESTAMP_FILE_DESCRIPTOR_SET)
             .build()
-            .expect("Failed to build reflection service");
+            .map_err(|e| anyhow::anyhow!("Failed to build reflection service: {}", e))?;
 
         // Add authentication interceptor.
         let server = RawDataServerWrapper::new(
@@ -72,12 +86,57 @@ impl RunnableConfig for IndexerGrpcDataServiceConfig {
             .send_compressed(CompressionEncoding::Gzip)
             .accept_compressed(CompressionEncoding::Gzip);
         let svc_with_interceptor = InterceptedService::new(svc, authentication_inceptor);
-        Server::builder()
-            .add_service(reflection_service)
-            .add_service(svc_with_interceptor)
-            .serve(grpc_address.to_socket_addrs().unwrap().next().unwrap())
-            .await
-            .map_err(|e| anyhow::anyhow!("Failed to serve: {}", e))
+
+        let svc_with_interceptor_clone = svc_with_interceptor.clone();
+        let reflection_service_clone = reflection_service.clone();
+
+        let mut tasks = vec![];
+        if self.data_service_grpc_non_tls_config.is_some() {
+            let config = self.data_service_grpc_non_tls_config.clone().unwrap();
+            let grpc_address = config
+                .data_service_grpc_listen_address
+                .to_socket_addrs()
+                .map_err(|e| anyhow::anyhow!(e))?
+                .next()
+                .ok_or_else(|| anyhow::anyhow!("Failed to parse grpc address"))?;
+            tasks.push(tokio::spawn(async move {
+                Server::builder()
+                    .add_service(svc_with_interceptor_clone)
+                    .add_service(reflection_service_clone)
+                    .serve(grpc_address)
+                    .await
+                    .map_err(|e| anyhow::anyhow!(e))
+            }));
+        }
+        if self.data_service_grpc_tls_config.is_some() {
+            let config = self.data_service_grpc_tls_config.clone().unwrap();
+            let grpc_address = config
+                .data_service_grpc_listen_address
+                .to_socket_addrs()
+                .map_err(|e| anyhow::anyhow!(e))?
+                .next()
+                .ok_or_else(|| anyhow::anyhow!("Failed to parse grpc address"))?;
+
+            let cert = tokio::fs::read(config.cert_path.clone()).await?;
+            let key = tokio::fs::read(config.key_path.clone()).await?;
+            let identity = tonic::transport::Identity::from_pem(cert, key);
+            tasks.push(tokio::spawn(async move {
+                Server::builder()
+                    .tls_config(tonic::transport::ServerTlsConfig::new().identity(identity))?
+                    .add_service(svc_with_interceptor)
+                    .add_service(reflection_service)
+                    .serve(grpc_address)
+                    .await
+                    .map_err(|e| anyhow::anyhow!(e))
+            }));
+        }
+
+        if tasks.is_empty() {
+            return Err(anyhow::anyhow!("No grpc config provided"));
+        }
+
+        futures::future::try_join_all(tasks).await?;
+        Ok(())
     }
 
     fn get_server_name(&self) -> String {
diff --git a/ecosystem/indexer-grpc/indexer-grpc-data-service/src/metrics.rs b/ecosystem/indexer-grpc/indexer-grpc-data-service/src/metrics.rs
index 9968929d5e490..d5461a6bb570b 100644
--- a/ecosystem/indexer-grpc/indexer-grpc-data-service/src/metrics.rs
+++ b/ecosystem/indexer-grpc/indexer-grpc-data-service/src/metrics.rs
@@ -50,7 +50,7 @@ pub static ERROR_COUNT: Lazy = Lazy::new(|| {
 /// Data latency for data service based on latest processed transaction based on selected processor.
 pub static PROCESSED_LATENCY_IN_SECS: Lazy = Lazy::new(|| {
     register_gauge_vec!(
-        "indexer_grpc_data_service_data_latency_in_secs",
+        "indexer_grpc_data_service_latest_data_latency_in_secs",
         "Latency of data service based on latest processed transaction",
         &["request_token", "processor_name"],
     )
@@ -60,7 +60,7 @@ pub static PROCESSED_LATENCY_IN_SECS: Lazy = Lazy::new(|| {
 /// Data latency for data service based on latest processed transaction for all processors.
 pub static PROCESSED_LATENCY_IN_SECS_ALL: Lazy = Lazy::new(|| {
     register_histogram_vec!(
-        "indexer_grpc_data_service_data_latency_in_secs_all",
+        "indexer_grpc_data_service_latest_data_latency_in_secs_all",
         "Latency of data service based on latest processed transaction",
         &["request_token"]
     )
diff --git a/ecosystem/indexer-grpc/indexer-grpc-data-service/src/service.rs b/ecosystem/indexer-grpc/indexer-grpc-data-service/src/service.rs
index 22aa91a53fc46..db7e3e6cb2457 100644
--- a/ecosystem/indexer-grpc/indexer-grpc-data-service/src/service.rs
+++ b/ecosystem/indexer-grpc/indexer-grpc-data-service/src/service.rs
@@ -9,7 +9,7 @@ use aptos_indexer_grpc_utils::{
     build_protobuf_encoded_transaction_wrappers,
     cache_operator::{CacheBatchGetStatus, CacheOperator},
     config::IndexerGrpcFileStoreConfig,
-    constants::{GRPC_AUTH_TOKEN_HEADER, GRPC_REQUEST_NAME_HEADER},
+    constants::{BLOB_STORAGE_SIZE, GRPC_AUTH_TOKEN_HEADER, GRPC_REQUEST_NAME_HEADER},
     file_store_operator::{FileStoreOperator, GcsFileStoreOperator, LocalFileStoreOperator},
     time_diff_since_pb_timestamp_in_secs, EncodedTransactionWithVersion,
 };
@@ -261,15 +261,19 @@ impl RawData for RawDataServerWrapper {
                                 ])
                                 .inc_by(current_batch_size as u64);
                             if let Some(data_latency_in_secs) = data_latency_in_secs {
-                                PROCESSED_LATENCY_IN_SECS
-                                    .with_label_values(&[
-                                        request_metadata.request_token.as_str(),
-                                        request_metadata.request_name.as_str(),
-                                    ])
-                                    .set(data_latency_in_secs);
-                                PROCESSED_LATENCY_IN_SECS_ALL
-                                    .with_label_values(&[request_metadata.request_source.as_str()])
-                                    .observe(data_latency_in_secs);
+                                // If it's a partial batch, we record the latency because it usually means
+                                // the data is the latest.
+                                if current_batch_size % BLOB_STORAGE_SIZE != 0 {
+                                    PROCESSED_LATENCY_IN_SECS
+                                        .with_label_values(&[
+                                            request_metadata.request_token.as_str(),
+                                            request_metadata.request_name.as_str(),
+                                        ])
+                                        .set(data_latency_in_secs);
+                                    PROCESSED_LATENCY_IN_SECS_ALL
+                                        .with_label_values(&[request_metadata.request_source.as_str()])
+                                        .observe(data_latency_in_secs);
+                                }
                             }
                         },
                         Err(SendTimeoutError::Timeout(_)) => {
diff --git a/ecosystem/indexer-grpc/indexer-grpc-utils/src/cache_operator.rs b/ecosystem/indexer-grpc/indexer-grpc-utils/src/cache_operator.rs
index 604d30b4fa7a3..46a78b76cc134 100644
--- a/ecosystem/indexer-grpc/indexer-grpc-utils/src/cache_operator.rs
+++ b/ecosystem/indexer-grpc/indexer-grpc-utils/src/cache_operator.rs
@@ -16,7 +16,7 @@ const CACHE_SIZE_ESTIMATION: u64 = 3_000_000_u64;
 // lower than the latest version - CACHE_SIZE_EVICTION_LOWER_BOUND.
 // The gap between CACHE_SIZE_ESTIMATION and this is to give buffer since
 // reading latest version and actual data not atomic(two operations).
-const CACHE_SIZE_EVICTION_LOWER_BOUND: u64 = 12_000_000_u64;
+const CACHE_SIZE_EVICTION_LOWER_BOUND: u64 = 4_000_000_u64;
 
 // Keys for cache.
 const CACHE_KEY_LATEST_VERSION: &str = "latest_version";

From 21ac8bf76f05eaa0a6272dd56f04154941eb1857 Mon Sep 17 00:00:00 2001
From: Junkil Park 
Date: Wed, 14 Jun 2023 02:51:28 -0700
Subject: [PATCH 163/200] Added the Knight token object example (#8489)

This module implements the knight token (non-fungible token) and the food tokens (fungible token).
This module has the function to feed a knight token with food tokens to increase the knight's health point.
---
 .../ambassador/sources/ambassador.move        |   2 +
 .../token_objects/knight/Move.toml            |  10 +
 .../token_objects/knight/sources/food.move    | 327 ++++++++++++++++++
 .../token_objects/knight/sources/knight.move  | 278 +++++++++++++++
 4 files changed, 617 insertions(+)
 create mode 100644 aptos-move/move-examples/token_objects/knight/Move.toml
 create mode 100644 aptos-move/move-examples/token_objects/knight/sources/food.move
 create mode 100644 aptos-move/move-examples/token_objects/knight/sources/knight.move

diff --git a/aptos-move/move-examples/token_objects/ambassador/sources/ambassador.move b/aptos-move/move-examples/token_objects/ambassador/sources/ambassador.move
index 5c86020ebddf1..d60102db45134 100644
--- a/aptos-move/move-examples/token_objects/ambassador/sources/ambassador.move
+++ b/aptos-move/move-examples/token_objects/ambassador/sources/ambassador.move
@@ -47,6 +47,7 @@ module token_objects::ambassador {
     const RANK_SILVER: vector = b"Silver";
     const RANK_BRONZE: vector = b"Bronze";
 
+    #[resource_group_member(group = aptos_framework::object::ObjectGroup)]
     /// The ambassador token
     struct AmbassadorToken has key {
         /// Used to mutate the token uri
@@ -61,6 +62,7 @@ module token_objects::ambassador {
         base_uri: String,
     }
 
+    #[resource_group_member(group = aptos_framework::object::ObjectGroup)]
     /// The ambassador level
     struct AmbassadorLevel has key {
         ambassador_level: u64,
diff --git a/aptos-move/move-examples/token_objects/knight/Move.toml b/aptos-move/move-examples/token_objects/knight/Move.toml
new file mode 100644
index 0000000000000..04e829911b84a
--- /dev/null
+++ b/aptos-move/move-examples/token_objects/knight/Move.toml
@@ -0,0 +1,10 @@
+[package]
+name = 'knight'
+version = '1.0.0'
+
+[addresses]
+token_objects = "_"
+
+[dependencies]
+AptosFramework = { local = "../../../framework/aptos-framework" }
+AptosTokenObjects = { local = "../../../framework/aptos-token-objects" }
diff --git a/aptos-move/move-examples/token_objects/knight/sources/food.move b/aptos-move/move-examples/token_objects/knight/sources/food.move
new file mode 100644
index 0000000000000..94060fff516dd
--- /dev/null
+++ b/aptos-move/move-examples/token_objects/knight/sources/food.move
@@ -0,0 +1,327 @@
+/// This module implements the the food tokens (fungible token). When the module initializes,
+/// it creates the collection and two fungible tokens such as Corn and Meat.
+module token_objects::food {
+    use std::error;
+    use std::option;
+    use std::signer;
+    use std::string::{Self, String};
+    use aptos_framework::fungible_asset::{Self, Metadata};
+    use aptos_framework::object::{Self, Object};
+    use aptos_framework::primary_fungible_store;
+    use aptos_token_objects::collection;
+    use aptos_token_objects::property_map;
+    use aptos_token_objects::token;
+
+    /// The token does not exist
+    const ETOKEN_DOES_NOT_EXIST: u64 = 1;
+    /// The provided signer is not the creator
+    const ENOT_CREATOR: u64 = 2;
+    /// Attempted to mutate an immutable field
+    const EFIELD_NOT_MUTABLE: u64 = 3;
+    /// Attempted to burn a non-burnable token
+    const ETOKEN_NOT_BURNABLE: u64 = 4;
+    /// Attempted to mutate a property map that is not mutable
+    const EPROPERTIES_NOT_MUTABLE: u64 = 5;
+    // The collection does not exist
+    const ECOLLECTION_DOES_NOT_EXIST: u64 = 6;
+
+    /// The food collection name
+    const FOOD_COLLECTION_NAME: vector = b"Food Collection Name";
+    /// The food collection description
+    const FOOD_COLLECTION_DESCRIPTION: vector = b"Food Collection Description";
+    /// The food collection URI
+    const FOOD_COLLECTION_URI: vector = b"https://food.collection.uri";
+
+    /// The knight token collection name
+    const KNIGHT_COLLECTION_NAME: vector = b"Knight Collection Name";
+    /// The knight collection description
+    const KNIGHT_COLLECTION_DESCRIPTION: vector = b"Knight Collection Description";
+    /// The knight collection URI
+    const KNIGHT_COLLECTION_URI: vector = b"https://knight.collection.uri";
+
+    /// The corn token name
+    const CORN_TOKEN_NAME: vector = b"Corn Token";
+    /// The meat token name
+    const MEAT_TOKEN_NAME: vector = b"Meat Token";
+
+    /// Property names
+    const CONDITION_PROPERTY_NAME: vector = b"Condition";
+    const RESTORATION_VALUE_PROPERTY_NAME: vector = b"Restoration Value";
+    const HEALTH_POINT_PROPERTY_NAME: vector = b"Health Point";
+
+    /// The condition of a knight
+    const CONDITION_HUNGRY: vector = b"Hungry";
+    const CONDITION_GOOD: vector = b"Good";
+
+    friend token_objects::knight;
+
+    #[resource_group_member(group = aptos_framework::object::ObjectGroup)]
+    // Food Token
+    struct FoodToken has key {
+        /// Used to mutate properties
+        property_mutator_ref: property_map::MutatorRef,
+        /// Used to mint fungible assets.
+        fungible_asset_mint_ref: fungible_asset::MintRef,
+        /// Used to burn fungible assets.
+        fungible_asset_burn_ref: fungible_asset::BurnRef,
+    }
+
+    #[resource_group_member(group = aptos_framework::object::ObjectGroup)]
+    /// Restoration value of the food. An attribute of a food token.
+    struct RestorationValue has key {
+        value: u64,
+    }
+
+    /// Initializes the module, creating the food collection and creating two fungible tokens such as Corn, and Meat.
+    fun init_module(sender: &signer) {
+        // Create a collection for food tokens.
+        create_food_collection(sender);
+        // Create two food token (i.e., Corn and Meat) as fungible tokens, meaning that there can be multiple units of them.
+        create_food_token_as_fungible_token(
+            sender,
+            string::utf8(b"Corn Token Description"),
+            string::utf8(CORN_TOKEN_NAME),
+            string::utf8(b"https://raw.githubusercontent.com/junkil-park/metadata/main/knight/Corn"),
+            string::utf8(b"Corn"),
+            string::utf8(b"CORN"),
+            string::utf8(b"https://raw.githubusercontent.com/junkil-park/metadata/main/knight/Corn.png"),
+            string::utf8(b"https://www.aptoslabs.com"),
+            5,
+        );
+        create_food_token_as_fungible_token(
+            sender,
+            string::utf8(b"Meat Token Description"),
+            string::utf8(MEAT_TOKEN_NAME),
+            string::utf8(b"https://raw.githubusercontent.com/junkil-park/metadata/main/knight/Meat"),
+            string::utf8(b"Meat"),
+            string::utf8(b"MEAT"),
+            string::utf8(b"https://raw.githubusercontent.com/junkil-park/metadata/main/knight/Meat.png"),
+            string::utf8(b"https://www.aptoslabs.com"),
+            20,
+        );
+    }
+
+    #[view]
+    /// Returns the restoration value of the food token
+    public fun restoration_value(token: Object): u64 acquires RestorationValue {
+        let restoration_value_in_food = borrow_global(object::object_address(&token));
+        restoration_value_in_food.value
+    }
+
+    #[view]
+    /// Returns the balance of the food token of the owner
+    public fun food_balance(owner_addr: address, food: Object): u64 {
+        let metadata = object::convert(food);
+        let store = primary_fungible_store::ensure_primary_store_exists(owner_addr, metadata);
+        fungible_asset::balance(store)
+    }
+
+    #[view]
+    /// Returns the corn token address
+    public fun corn_token_address(): address {
+        food_token_address(string::utf8(CORN_TOKEN_NAME))
+    }
+
+    #[view]
+    /// Returns the meat token address
+    public fun meat_token_address(): address {
+        food_token_address(string::utf8(MEAT_TOKEN_NAME))
+    }
+
+    #[view]
+    /// Returns the food token address by name
+    public fun food_token_address(food_token_name: String): address {
+        token::create_token_address(&@token_objects, &string::utf8(FOOD_COLLECTION_NAME), &food_token_name)
+    }
+
+    /// Creates the food collection.
+    fun create_food_collection(creator: &signer) {
+        // Constructs the strings from the bytes.
+        let description = string::utf8(FOOD_COLLECTION_DESCRIPTION);
+        let name = string::utf8(FOOD_COLLECTION_NAME);
+        let uri = string::utf8(FOOD_COLLECTION_URI);
+
+        // Creates the collection with unlimited supply and without establishing any royalty configuration.
+        collection::create_unlimited_collection(
+            creator,
+            description,
+            name,
+            option::none(),
+            uri,
+        );
+    }
+
+    /// Creates the food token as fungible token.
+    fun create_food_token_as_fungible_token(
+        creator: &signer,
+        description: String,
+        name: String,
+        uri: String,
+        fungible_asset_name: String,
+        fungible_asset_symbol: String,
+        icon_uri: String,
+        project_uri: String,
+        restoration_value: u64,
+    ) {
+        // The collection name is used to locate the collection object and to create a new token object.
+        let collection = string::utf8(FOOD_COLLECTION_NAME);
+        // Creates the food token, and get the constructor ref of the token. The constructor ref
+        // is used to generate the refs of the token.
+        let constructor_ref = token::create_named_token(
+            creator,
+            collection,
+            description,
+            name,
+            option::none(),
+            uri,
+        );
+
+        // Generates the object signer and the refs. The object signer is used to publish a resource
+        // (e.g., RestorationValue) under the token object address. The refs are used to manage the token.
+        let object_signer = object::generate_signer(&constructor_ref);
+        let property_mutator_ref = property_map::generate_mutator_ref(&constructor_ref);
+
+        // Initializes the value with the given value in food.
+        move_to(&object_signer, RestorationValue { value: restoration_value });
+
+        // Initialize the property map.
+        let properties = property_map::prepare_input(vector[], vector[], vector[]);
+        property_map::init(&constructor_ref, properties);
+        property_map::add_typed(
+            &property_mutator_ref,
+            string::utf8(RESTORATION_VALUE_PROPERTY_NAME),
+            restoration_value
+        );
+
+        // Creates the fungible asset.
+        primary_fungible_store::create_primary_store_enabled_fungible_asset(
+            &constructor_ref,
+            option::none(),
+            fungible_asset_name,
+            fungible_asset_symbol,
+            0,
+            icon_uri,
+            project_uri,
+        );
+        let fungible_asset_mint_ref = fungible_asset::generate_mint_ref(&constructor_ref);
+        let fungible_asset_burn_ref = fungible_asset::generate_burn_ref(&constructor_ref);
+
+        // Publishes the FoodToken resource with the refs.
+        let food_token = FoodToken {
+            property_mutator_ref,
+            fungible_asset_mint_ref,
+            fungible_asset_burn_ref,
+        };
+        move_to(&object_signer, food_token);
+    }
+
+    /// Mints the given amount of the corn token to the given receiver.
+    public entry fun mint_corn(creator: &signer, receiver: address, amount: u64) acquires FoodToken {
+        let corn_token = object::address_to_object(corn_token_address());
+        mint_internal(creator, corn_token, receiver, amount);
+    }
+
+    /// Mints the given amount of the meat token to the given receiver.
+    public entry fun mint_meat(creator: &signer, receiver: address, amount: u64) acquires FoodToken {
+        let meat_token = object::address_to_object(meat_token_address());
+        mint_internal(creator, meat_token, receiver, amount);
+    }
+
+    /// The internal mint function.
+    fun mint_internal(creator: &signer, token: Object, receiver: address, amount: u64) acquires FoodToken {
+        let food_token = authorized_borrow(creator, &token);
+        let fungible_asset_mint_ref = &food_token.fungible_asset_mint_ref;
+        let fa = fungible_asset::mint(fungible_asset_mint_ref, amount);
+        primary_fungible_store::deposit(receiver, fa);
+    }
+
+    /// Transfers the given amount of the corn token from the given sender to the given receiver.
+    public entry fun transfer_corn(from: &signer, to: address, amount: u64) {
+        transfer_food(from, object::address_to_object(corn_token_address()), to, amount);
+    }
+
+    /// Transfers the given amount of the meat token from the given sender to the given receiver.
+    public entry fun transfer_meat(from: &signer, to: address, amount: u64) {
+        transfer_food(from, object::address_to_object(meat_token_address()), to, amount);
+    }
+
+    public entry fun transfer_food(from: &signer, food: Object, to: address, amount: u64) {
+        let metadata = object::convert(food);
+        primary_fungible_store::transfer(from, metadata, to, amount);
+    }
+
+    public(friend) fun burn_food(from: &signer, food: Object, amount: u64) acquires FoodToken {
+        let metadata = object::convert(food);
+        let food_addr = object::object_address(&food);
+        let food_token = borrow_global(food_addr);
+        let from_store = primary_fungible_store::ensure_primary_store_exists(signer::address_of(from), metadata);
+        fungible_asset::burn_from(&food_token.fungible_asset_burn_ref, from_store, amount);
+    }
+
+    inline fun authorized_borrow(creator: &signer, token: &Object): &FoodToken {
+        let token_address = object::object_address(token);
+        assert!(
+            exists(token_address),
+            error::not_found(ETOKEN_DOES_NOT_EXIST),
+        );
+
+        assert!(
+            token::creator(*token) == signer::address_of(creator),
+            error::permission_denied(ENOT_CREATOR),
+        );
+        borrow_global(token_address)
+    }
+
+    #[test_only]
+    public fun init_module_for_test(creator: &signer) {
+        init_module(creator);
+    }
+
+    #[test(creator = @token_objects, user1 = @0x456, user2 = @0x789)]
+    public fun test_food(creator: &signer, user1: &signer, user2: &signer) acquires FoodToken {
+        // This test assumes that the creator's address is equal to @token_objects.
+        assert!(signer::address_of(creator) == @token_objects, 0);
+
+        // ---------------------------------------------------------------------
+        // Creator creates the collection, and mints corn and meat tokens in it.
+        // ---------------------------------------------------------------------
+        init_module(creator);
+
+        // -------------------------------------------
+        // Creator mints and sends 100 corns to User1.
+        // -------------------------------------------
+        let user1_addr = signer::address_of(user1);
+        mint_corn(creator, user1_addr, 100);
+
+        let corn_token = object::address_to_object(corn_token_address());
+        // Assert that the user1 has 100 corns.
+        assert!(food_balance(user1_addr, corn_token) == 100, 0);
+
+        // -------------------------------------------
+        // Creator mints and sends 200 meats to User2.
+        // -------------------------------------------
+        let user2_addr = signer::address_of(user2);
+        mint_meat(creator, user2_addr, 200);
+        let meat_token = object::address_to_object(meat_token_address());
+        // Assert that the user2 has 200 meats.
+        assert!(food_balance(user2_addr, meat_token) == 200, 0);
+
+        // ------------------------------
+        // User1 sends 10 corns to User2.
+        // ------------------------------
+        transfer_corn(user1, user2_addr, 10);
+        // Assert that the user1 has 90 corns.
+        assert!(food_balance(user1_addr, corn_token) == 90, 0);
+        // Assert that the user2 has 10 corns.
+        assert!(food_balance(user2_addr, corn_token) == 10, 0);
+
+        // ------------------------------
+        // User2 sends 20 meats to User1.
+        // ------------------------------
+        transfer_meat(user2, user1_addr, 20);
+        // Assert that the user1 has 20 meats.
+        assert!(food_balance(user1_addr, meat_token) == 20, 0);
+        // Assert that the user2 has 180 meats.
+        assert!(food_balance(user2_addr, meat_token) == 180, 0);
+    }
+}
diff --git a/aptos-move/move-examples/token_objects/knight/sources/knight.move b/aptos-move/move-examples/token_objects/knight/sources/knight.move
new file mode 100644
index 0000000000000..9501b4572457d
--- /dev/null
+++ b/aptos-move/move-examples/token_objects/knight/sources/knight.move
@@ -0,0 +1,278 @@
+/// This module implements the knight token (non-fungible token) including the
+/// functions create the collection and the knight tokens, and the function to feed a
+/// knight token with food tokens to increase the knight's health point.
+module token_objects::knight {
+    use std::option;
+    use std::string::{Self, String};
+    use aptos_framework::event;
+    use aptos_framework::object::{Self, Object};
+    use aptos_token_objects::collection;
+    use aptos_token_objects::property_map;
+    use aptos_token_objects::token;
+    use token_objects::food::{Self, FoodToken};
+
+    /// The token does not exist
+    const ETOKEN_DOES_NOT_EXIST: u64 = 1;
+    /// The provided signer is not the creator
+    const ENOT_CREATOR: u64 = 2;
+    /// Attempted to mutate an immutable field
+    const EFIELD_NOT_MUTABLE: u64 = 3;
+    /// Attempted to burn a non-burnable token
+    const ETOKEN_NOT_BURNABLE: u64 = 4;
+    /// Attempted to mutate a property map that is not mutable
+    const EPROPERTIES_NOT_MUTABLE: u64 = 5;
+    // The collection does not exist
+    const ECOLLECTION_DOES_NOT_EXIST: u64 = 6;
+
+    /// The knight token collection name
+    const KNIGHT_COLLECTION_NAME: vector = b"Knight Collection Name";
+    /// The knight collection description
+    const KNIGHT_COLLECTION_DESCRIPTION: vector = b"Knight Collection Description";
+    /// The knight collection URI
+    const KNIGHT_COLLECTION_URI: vector = b"https://knight.collection.uri";
+
+    /// Property names
+    const CONDITION_PROPERTY_NAME: vector = b"Condition";
+    const HEALTH_POINT_PROPERTY_NAME: vector = b"Health Point";
+
+    /// The condition of a knight
+    const CONDITION_HUNGRY: vector = b"Hungry";
+    const CONDITION_GOOD: vector = b"Good";
+
+    #[resource_group_member(group = aptos_framework::object::ObjectGroup)]
+    /// Knight token
+    struct KnightToken has key {
+        /// Used to mutate the token uri
+        mutator_ref: token::MutatorRef,
+        /// Used to mutate properties
+        property_mutator_ref: property_map::MutatorRef,
+        /// Used to emit HealthUpdateEvent
+        health_update_events: event::EventHandle,
+        /// the base URI of the token
+        base_uri: String,
+    }
+
+    #[resource_group_member(group = aptos_framework::object::ObjectGroup)]
+    /// The knight's health point
+    struct HealthPoint has key {
+        value: u64,
+    }
+
+    /// The health update event
+    struct HealthUpdateEvent has drop, store {
+        old_health: u64,
+        new_health: u64,
+    }
+
+    /// Initializes the module, creating the knight token collection.
+    fun init_module(sender: &signer) {
+        // Create a collection for knight tokens.
+        create_knight_collection(sender);
+    }
+
+    #[view]
+    /// Returns the knight health point of the token
+    public fun health_point(token: Object): u64 acquires HealthPoint {
+        let health = borrow_global(object::object_address(&token));
+        health.value
+    }
+
+    #[view]
+    /// Returns the knight token address by name
+    public fun knight_token_address(knight_token_name: String): address {
+        token::create_token_address(&@token_objects, &string::utf8(KNIGHT_COLLECTION_NAME), &knight_token_name)
+    }
+
+    /// Creates the knight collection. This function creates a collection with unlimited supply using
+    /// the module constants for description, name, and URI, defined above. The royalty configuration
+    /// is skipped in this collection for simplicity.
+    fun create_knight_collection(creator: &signer) {
+        // Constructs the strings from the bytes.
+        let description = string::utf8(KNIGHT_COLLECTION_DESCRIPTION);
+        let name = string::utf8(KNIGHT_COLLECTION_NAME);
+        let uri = string::utf8(KNIGHT_COLLECTION_URI);
+
+        // Creates the collection with unlimited supply and without establishing any royalty configuration.
+        collection::create_unlimited_collection(
+            creator,
+            description,
+            name,
+            option::none(),
+            uri,
+        );
+    }
+
+    /// Mints an knight token. This function mints a new knight token and transfers it to the
+    /// `soul_bound_to` address. The token is minted with health point 0 and condition Hungry.
+    public entry fun mint_knight(
+        creator: &signer,
+        description: String,
+        name: String,
+        base_uri: String,
+        receiver: address,
+    ) {
+        // The collection name is used to locate the collection object and to create a new token object.
+        let collection = string::utf8(KNIGHT_COLLECTION_NAME);
+        // Creates the knight token, and get the constructor ref of the token. The constructor ref
+        // is used to generate the refs of the token.
+        let uri = base_uri;
+        string::append(&mut uri, string::utf8(CONDITION_HUNGRY));
+        let constructor_ref = token::create_named_token(
+            creator,
+            collection,
+            description,
+            name,
+            option::none(),
+            uri,
+        );
+
+        // Generates the object signer and the refs. The object signer is used to publish a resource
+        // (e.g., HealthPoint) under the token object address. The refs are used to manage the token.
+        let object_signer = object::generate_signer(&constructor_ref);
+        let transfer_ref = object::generate_transfer_ref(&constructor_ref);
+        let mutator_ref = token::generate_mutator_ref(&constructor_ref);
+        let property_mutator_ref = property_map::generate_mutator_ref(&constructor_ref);
+
+        // Transfers the token to the `soul_bound_to` address
+        let linear_transfer_ref = object::generate_linear_transfer_ref(&transfer_ref);
+        object::transfer_with_ref(linear_transfer_ref, receiver);
+
+        // Initializes the knight health point as 0
+        move_to(&object_signer, HealthPoint { value: 1 });
+
+        // Initialize the property map and the knight condition as Hungry
+        let properties = property_map::prepare_input(vector[], vector[], vector[]);
+        property_map::init(&constructor_ref, properties);
+        property_map::add_typed(
+            &property_mutator_ref,
+            string::utf8(CONDITION_PROPERTY_NAME),
+            string::utf8(CONDITION_HUNGRY),
+        );
+        // Although the health point is stored in the HealthPoint resource, it is also duplicated
+        // and stored in the property map to be recognized as a property by the wallet.
+        property_map::add_typed(
+            &property_mutator_ref,
+            string::utf8(HEALTH_POINT_PROPERTY_NAME),
+            1,
+        );
+
+        // Publishes the KnightToken resource with the refs and the event handle for `HealthUpdateEvent`.
+        let knight_token = KnightToken {
+            mutator_ref,
+            property_mutator_ref,
+            health_update_events: object::new_event_handle(&object_signer),
+            base_uri
+        };
+        move_to(&object_signer, knight_token);
+    }
+
+    public entry fun feed_corn(from: &signer, to: Object, amount: u64) acquires HealthPoint, KnightToken {
+        let corn_token = object::address_to_object(food::corn_token_address());
+        feed_food(from, corn_token, to, amount);
+    }
+
+    public entry fun feed_meat(from: &signer, to: Object, amount: u64) acquires HealthPoint, KnightToken {
+        let meat_token = object::address_to_object(food::meat_token_address());
+        feed_food(from, meat_token, to, amount);
+    }
+
+    public entry fun feed_food(from: &signer, food_token: Object, to: Object, amount: u64) acquires HealthPoint, KnightToken {
+        let knight_token_address = object::object_address(&to);
+        food::burn_food(from, food_token, amount);
+
+        let restoration_amount = food::restoration_value(food_token) * amount;
+        let health_point = borrow_global_mut(object::object_address(&to));
+        let old_health_point = health_point.value;
+        let new_health_point = old_health_point + restoration_amount;
+        health_point.value = new_health_point;
+
+        let knight = borrow_global_mut(knight_token_address);
+        // Gets `property_mutator_ref` to update the health point and condition in the property map.
+        let property_mutator_ref = &knight.property_mutator_ref;
+        // Updates the health point in the property map.
+        property_map::update_typed(property_mutator_ref, &string::utf8(HEALTH_POINT_PROPERTY_NAME), new_health_point);
+
+        event::emit_event(
+            &mut knight.health_update_events,
+            HealthUpdateEvent {
+                old_health: old_health_point,
+                new_health: new_health_point,
+            }
+        );
+
+        // `new_condition` is determined based on the new health point.
+        let new_condition = if (new_health_point <= 20) {
+            CONDITION_HUNGRY
+        } else {
+            CONDITION_GOOD
+        };
+        // Updates the condition in the property map.
+        property_map::update_typed(property_mutator_ref, &string::utf8(CONDITION_PROPERTY_NAME), string::utf8(new_condition));
+
+        // Updates the token URI based on the new condition.
+        let uri = knight.base_uri;
+        string::append(&mut uri, string::utf8(new_condition));
+        token::set_uri(&knight.mutator_ref, uri);
+    }
+
+    #[test_only]
+    use std::signer;
+
+    #[test(creator = @token_objects, user1 = @0x456)]
+    public fun test_knight(creator: &signer, user1: &signer) acquires HealthPoint, KnightToken {
+        // This test assumes that the creator's address is equal to @token_objects.
+        assert!(signer::address_of(creator) == @token_objects, 0);
+
+        // ---------------------------------------------------------------------
+        // Creator creates the collection, and mints corn and meat tokens in it.
+        // ---------------------------------------------------------------------
+        food::init_module_for_test(creator);
+        init_module(creator);
+
+        // -------------------------------------------------------
+        // Creator mints and sends 90 corns and 20 meats to User1.
+        // -------------------------------------------------------
+        let user1_addr = signer::address_of(user1);
+        food::mint_corn(creator, user1_addr, 90);
+        food::mint_meat(creator, user1_addr, 20);
+
+        // ---------------------------------------
+        // Creator mints a knight token for User1.
+        // ---------------------------------------
+        let token_name = string::utf8(b"Knight Token #1");
+        let token_description = string::utf8(b"Knight Token #1 Description");
+        let token_uri = string::utf8(b"Knight Token #1 URI");
+        let user1_addr = signer::address_of(user1);
+        // Creates the knight token for User1.
+        mint_knight(
+            creator,
+            token_description,
+            token_name,
+            token_uri,
+            user1_addr,
+        );
+        let token_address = knight_token_address(token_name);
+        let knight_token = object::address_to_object(token_address);
+
+        // Asserts that the owner of the token is User1.
+        assert!(object::owner(knight_token) == user1_addr, 1);
+        // Asserts that the health point of the token is 1.
+        assert!(health_point(knight_token) == 1, 2);
+
+        let corn_token = object::address_to_object(food::corn_token_address());
+        let old_corn_balance = food::food_balance(user1_addr, corn_token);
+        feed_food(user1, corn_token, knight_token, 3);
+        // Asserts that the corn balance decreases by 3.
+        assert!(food::food_balance(user1_addr, corn_token) == old_corn_balance - 3, 0);
+        // Asserts that the health point increases by 15 (= amount * restoration_value = 3 * 5).
+        assert!(health_point(knight_token) == 16, 2);
+
+        let meat_token = object::address_to_object(food::meat_token_address());
+        let old_meat_balance = food::food_balance(user1_addr, meat_token);
+        feed_food(user1, meat_token, knight_token, 2);
+        // Asserts that the corn balance decreases by 3.
+        assert!(food::food_balance(user1_addr, meat_token) == old_meat_balance - 2, 0);
+        // Asserts that the health point increases by 40 (= amount * restoration_value = 2 * 20).
+        assert!(health_point(knight_token) == 56, 3);
+    }
+}

From 22d628095982b94ae755574a5a5f666b699c6bf8 Mon Sep 17 00:00:00 2001
From: "Xudong (Don) Wang" 
Date: Wed, 14 Jun 2023 22:08:16 +1000
Subject: [PATCH 164/200] [Spec] update specs of voting, transaction_fee, code
 (#8172)

* [spec] update specs of voting, transaction_fee, code

* [spec] add account and voting module

* run linter

* [spec] Fix timeout of smart_vector.move

* [spec] Update docs of smart_vector

---------

Co-authored-by: zorrot 
---
 .../framework/aptos-framework/doc/account.md  |  23 +-
 .../framework/aptos-framework/doc/code.md     |  20 ++
 .../framework/aptos-framework/doc/stake.md    | 250 ++++++++++--------
 .../aptos-framework/doc/transaction_fee.md    |  19 +-
 .../framework/aptos-framework/doc/voting.md   |  27 +-
 .../aptos-framework/sources/account.spec.move |  42 ++-
 .../aptos-framework/sources/code.spec.move    |   7 +
 .../aptos-framework/sources/stake.spec.move   |   7 +
 .../sources/transaction_fee.spec.move         |  36 ++-
 .../aptos-framework/sources/voting.spec.move  |  25 +-
 .../framework/aptos-stdlib/doc/from_bcs.md    |   4 +
 .../aptos-stdlib/doc/smart_vector.md          |  17 ++
 .../data_structures/smart_vector.spec.move    |   4 +
 .../aptos-stdlib/sources/from_bcs.spec.move   |   7 +
 14 files changed, 344 insertions(+), 144 deletions(-)

diff --git a/aptos-move/framework/aptos-framework/doc/account.md b/aptos-move/framework/aptos-framework/doc/account.md
index 7c64b4cf70f47..fb6fc9b70a4d2 100644
--- a/aptos-move/framework/aptos-framework/doc/account.md
+++ b/aptos-move/framework/aptos-framework/doc/account.md
@@ -2224,9 +2224,16 @@ The authentication scheme is ED25519_SCHEME and MULTI_ED25519_SCHEME
     signature: cap_update_table,
     challenge: challenge,
 };
-pragma aborts_if_is_partial;
-modifies global<Account>(addr);
-modifies global<OriginatingAddress>(@aptos_framework);
+let originating_addr = addr;
+let new_auth_key_vector = spec_assert_valid_rotation_proof_signature_and_get_auth_key(to_scheme, to_public_key_bytes, cap_update_table, challenge);
+let address_map = global<OriginatingAddress>(@aptos_framework).address_map;
+let new_auth_key = from_bcs::deserialize<address>(new_auth_key_vector);
+aborts_if !exists<OriginatingAddress>(@aptos_framework);
+aborts_if !from_bcs::deserializable<address>(account_resource.authentication_key);
+aborts_if table::spec_contains(address_map, curr_auth_key) &&
+    table::spec_get(address_map, curr_auth_key) != originating_addr;
+aborts_if !from_bcs::deserializable<address>(new_auth_key_vector);
+aborts_if curr_auth_key != new_auth_key && table::spec_contains(address_map, new_auth_key);
 

 
 
@@ -2261,7 +2268,15 @@ The authentication scheme is ED25519_SCHEME and MULTI_ED25519_SCHEME
     signature: cap_update_table,
     challenge: challenge,
 };
-pragma aborts_if_is_partial;
+let new_auth_key_vector = spec_assert_valid_rotation_proof_signature_and_get_auth_key(new_scheme, new_public_key_bytes, cap_update_table, challenge);
+let address_map = global<OriginatingAddress>(@aptos_framework).address_map;
+aborts_if !exists<OriginatingAddress>(@aptos_framework);
+aborts_if !from_bcs::deserializable<address>(offerer_account_resource.authentication_key);
+aborts_if table::spec_contains(address_map, curr_auth_key) &&
+    table::spec_get(address_map, curr_auth_key) != rotation_cap_offerer_address;
+aborts_if !from_bcs::deserializable<address>(new_auth_key_vector);
+let new_auth_key = from_bcs::deserialize<address>(new_auth_key_vector);
+aborts_if curr_auth_key != new_auth_key && table::spec_contains(address_map, new_auth_key);
 

 
 
diff --git a/aptos-move/framework/aptos-framework/doc/code.md b/aptos-move/framework/aptos-framework/doc/code.md
index 3e2f788a8ae8d..e849ecef6b9ff 100644
--- a/aptos-move/framework/aptos-framework/doc/code.md
+++ b/aptos-move/framework/aptos-framework/doc/code.md
@@ -34,6 +34,7 @@ This module supports functionality related to code management.
     -  [Function `check_upgradability`](#@Specification_1_check_upgradability)
     -  [Function `check_coexistence`](#@Specification_1_check_coexistence)
     -  [Function `check_dependencies`](#@Specification_1_check_dependencies)
+    -  [Function `get_module_names`](#@Specification_1_get_module_names)
     -  [Function `request_publish`](#@Specification_1_request_publish)
     -  [Function `request_publish_with_allowed_deps`](#@Specification_1_request_publish_with_allowed_deps)
 
@@ -986,6 +987,25 @@ Native function to initiate module loading, including a list of allowed dependen
 
 
 
+
+
+### Function `get_module_names`
+
+
+
fun get_module_names(pack: &code::PackageMetadata): vector<string::String>
+

+
+
+
+
+
pragma opaque;
+aborts_if [abstract] false;
+ensures [abstract] len(result) == len(pack.modules);
+ensures [abstract] forall i in 0..len(result): result[i] == pack.modules[i].name;
+

+
+
+
 
 
 ### Function `request_publish`
diff --git a/aptos-move/framework/aptos-framework/doc/stake.md b/aptos-move/framework/aptos-framework/doc/stake.md
index de7e8ad6ec8ef..e838e2f4d9a33 100644
--- a/aptos-move/framework/aptos-framework/doc/stake.md
+++ b/aptos-move/framework/aptos-framework/doc/stake.md
@@ -105,6 +105,7 @@ or if their stake drops below the min required, they would get removed at the en
 -  [Function `is_allowed`](#0x1_stake_is_allowed)
 -  [Function `assert_owner_cap_exists`](#0x1_stake_assert_owner_cap_exists)
 -  [Specification](#@Specification_1)
+    -  [Function `initialize_validator_fees`](#@Specification_1_initialize_validator_fees)
     -  [Function `add_transaction_fee`](#@Specification_1_add_transaction_fee)
     -  [Function `get_validator_state`](#@Specification_1_get_validator_state)
     -  [Function `initialize`](#@Specification_1_initialize)
@@ -3539,6 +3540,140 @@ Returns validator's next epoch voting power, including pending_active, active, a
 
 
 
+
+
+
+
+
fun spec_validators_are_initialized(validators: vector<ValidatorInfo>): bool {
+   forall i in 0..len(validators):
+       spec_has_stake_pool(validators[i].addr) &&
+           spec_has_validator_config(validators[i].addr)
+}
+

+
+
+
+
+
+
+
+
fun spec_validator_indices_are_valid(validators: vector<ValidatorInfo>): bool {
+   forall i in 0..len(validators):
+       global<ValidatorConfig>(validators[i].addr).validator_index < spec_validator_index_upper_bound()
+}
+

+
+
+
+
+
+
+
+
fun spec_validator_index_upper_bound(): u64 {
+   len(global<ValidatorPerformance>(@aptos_framework).validators)
+}
+

+
+
+
+
+
+
+
+
fun spec_has_stake_pool(a: address): bool {
+   exists<StakePool>(a)
+}
+

+
+
+
+
+
+
+
+
fun spec_has_validator_config(a: address): bool {
+   exists<ValidatorConfig>(a)
+}
+

+
+
+
+
+
+
+
+
fun spec_rewards_amount(
+   stake_amount: u64,
+   num_successful_proposals: u64,
+   num_total_proposals: u64,
+   rewards_rate: u64,
+   rewards_rate_denominator: u64,
+): u64;
+

+
+
+
+
+
+
+
+
fun spec_contains(validators: vector<ValidatorInfo>, addr: address): bool {
+   exists i in 0..len(validators): validators[i].addr == addr
+}
+

+
+
+
+
+
+
+
+
fun spec_is_current_epoch_validator(pool_address: address): bool {
+   let validator_set = global<ValidatorSet>(@aptos_framework);
+   !spec_contains(validator_set.pending_active, pool_address)
+       && (spec_contains(validator_set.active_validators, pool_address)
+       || spec_contains(validator_set.pending_inactive, pool_address))
+}
+

+
+
+
+
+
+
+
+
schema ResourceRequirement {
+    requires exists<AptosCoinCapabilities>(@aptos_framework);
+    requires exists<ValidatorPerformance>(@aptos_framework);
+    requires exists<ValidatorSet>(@aptos_framework);
+    requires exists<StakingConfig>(@aptos_framework);
+    requires exists<StakingRewardsConfig>(@aptos_framework) || !features::spec_periodical_reward_rate_decrease_enabled();
+    requires exists<timestamp::CurrentTimeMicroseconds>(@aptos_framework);
+    requires exists<ValidatorFees>(@aptos_framework);
+}
+

+
+
+
+
+
+### Function `initialize_validator_fees`
+
+
+
public(friend) fun initialize_validator_fees(aptos_framework: &signer)
+

+
+
+
+
+
let aptos_addr = signer::address_of(aptos_framework);
+aborts_if !system_addresses::is_aptos_framework_address(aptos_addr);
+aborts_if exists<ValidatorFees>(aptos_addr);
+ensures exists<ValidatorFees>(aptos_addr);
+

+
+
+
 
 
 ### Function `add_transaction_fee`
@@ -4104,119 +4239,4 @@ Returns validator's next epoch voting power, including pending_active, active, a
 

 
 
-
-
-
-
-
-
fun spec_validators_are_initialized(validators: vector<ValidatorInfo>): bool {
-   forall i in 0..len(validators):
-       spec_has_stake_pool(validators[i].addr) &&
-           spec_has_validator_config(validators[i].addr)
-}
-

-
-
-
-
-
-
-
-
fun spec_validator_indices_are_valid(validators: vector<ValidatorInfo>): bool {
-   forall i in 0..len(validators):
-       global<ValidatorConfig>(validators[i].addr).validator_index < spec_validator_index_upper_bound()
-}
-

-
-
-
-
-
-
-
-
fun spec_validator_index_upper_bound(): u64 {
-   len(global<ValidatorPerformance>(@aptos_framework).validators)
-}
-

-
-
-
-
-
-
-
-
fun spec_has_stake_pool(a: address): bool {
-   exists<StakePool>(a)
-}
-

-
-
-
-
-
-
-
-
fun spec_has_validator_config(a: address): bool {
-   exists<ValidatorConfig>(a)
-}
-

-
-
-
-
-
-
-
-
fun spec_rewards_amount(
-   stake_amount: u64,
-   num_successful_proposals: u64,
-   num_total_proposals: u64,
-   rewards_rate: u64,
-   rewards_rate_denominator: u64,
-): u64;
-

-
-
-
-
-
-
-
-
fun spec_contains(validators: vector<ValidatorInfo>, addr: address): bool {
-   exists i in 0..len(validators): validators[i].addr == addr
-}
-

-
-
-
-
-
-
-
-
fun spec_is_current_epoch_validator(pool_address: address): bool {
-   let validator_set = global<ValidatorSet>(@aptos_framework);
-   !spec_contains(validator_set.pending_active, pool_address)
-       && (spec_contains(validator_set.active_validators, pool_address)
-       || spec_contains(validator_set.pending_inactive, pool_address))
-}
-

-
-
-
-
-
-
-
-
schema ResourceRequirement {
-    requires exists<AptosCoinCapabilities>(@aptos_framework);
-    requires exists<ValidatorPerformance>(@aptos_framework);
-    requires exists<ValidatorSet>(@aptos_framework);
-    requires exists<StakingConfig>(@aptos_framework);
-    requires exists<StakingRewardsConfig>(@aptos_framework) || !features::spec_periodical_reward_rate_decrease_enabled();
-    requires exists<timestamp::CurrentTimeMicroseconds>(@aptos_framework);
-    requires exists<ValidatorFees>(@aptos_framework);
-}
-

-
-
 [move-book]: https://aptos.dev/guides/move-guides/book/SUMMARY
diff --git a/aptos-move/framework/aptos-framework/doc/transaction_fee.md b/aptos-move/framework/aptos-framework/doc/transaction_fee.md
index eff99bc7767f8..1111e88db5756 100644
--- a/aptos-move/framework/aptos-framework/doc/transaction_fee.md
+++ b/aptos-move/framework/aptos-framework/doc/transaction_fee.md
@@ -525,7 +525,14 @@ Only called during genesis.
 
 
 
-
pragma verify=false;
+
aborts_if exists<CollectedFeesPerBlock>(@aptos_framework);
+aborts_if burn_percentage > 100;
+let aptos_addr = signer::address_of(aptos_framework);
+aborts_if !system_addresses::is_aptos_framework_address(aptos_addr);
+aborts_if exists<ValidatorFees>(aptos_addr);
+include system_addresses::AbortsIfNotAptosFramework {account: aptos_framework};
+include aggregator_factory::CreateAggregatorInternalAbortsIf;
+ensures exists<ValidatorFees>(aptos_addr);
 

 
 
@@ -541,7 +548,15 @@ Only called during genesis.
 
 
 
-
pragma verify=false;
+
aborts_if new_burn_percentage > 100;
+let aptos_addr = signer::address_of(aptos_framework);
+aborts_if !system_addresses::is_aptos_framework_address(aptos_addr);
+requires exists<AptosCoinCapabilities>(@aptos_framework);
+requires exists<stake::ValidatorFees>(@aptos_framework);
+requires exists<CoinInfo<AptosCoin>>(@aptos_framework);
+include RequiresCollectedFeesPerValueLeqBlockAptosSupply;
+ensures exists<CollectedFeesPerBlock>(@aptos_framework) ==>
+    global<CollectedFeesPerBlock>(@aptos_framework).burn_percentage == new_burn_percentage;
 

 
 
diff --git a/aptos-move/framework/aptos-framework/doc/voting.md b/aptos-move/framework/aptos-framework/doc/voting.md
index 32828c52a7e56..45d08706a1f34 100644
--- a/aptos-move/framework/aptos-framework/doc/voting.md
+++ b/aptos-move/framework/aptos-framework/doc/voting.md
@@ -1637,7 +1637,16 @@ CurrentTimeMicroseconds existed under the @aptos_framework.
 
 
 
requires chain_status::is_operating();
-pragma aborts_if_is_strict = false;
+include AbortsIfNotContainProposalID<ProposalType>;
+aborts_if spec_get_proposal_state<ProposalType>(voting_forum_address, proposal_id) != PROPOSAL_STATE_SUCCEEDED;
+let voting_forum =  global<VotingForum<ProposalType>>(voting_forum_address);
+let proposal = table::spec_get(voting_forum.proposals, proposal_id);
+aborts_if proposal.is_resolved;
+aborts_if !std::string::spec_internal_check_utf8(RESOLVABLE_TIME_METADATA_KEY);
+aborts_if !simple_map::spec_contains_key(proposal.metadata, std::string::spec_utf8(RESOLVABLE_TIME_METADATA_KEY));
+aborts_if !from_bcs::deserializable<u64>(simple_map::spec_get(proposal.metadata, std::string::spec_utf8(RESOLVABLE_TIME_METADATA_KEY)));
+aborts_if timestamp::spec_now_seconds() <= from_bcs::deserialize<u64>(simple_map::spec_get(proposal.metadata, std::string::spec_utf8(RESOLVABLE_TIME_METADATA_KEY)));
+aborts_if transaction_context::spec_get_script_hash() != proposal.execution_hash;
 

 
 
@@ -1730,6 +1739,18 @@ CurrentTimeMicroseconds existed under the @aptos_framework.
 
 
 
+
+
+
+
+
fun spec_get_proposal_state<ProposalType>(
+   voting_forum_address: address,
+   proposal_id: u64,
+): u64;
+

+
+
+
 
 
 ### Function `get_proposal_state`
@@ -1741,9 +1762,11 @@ CurrentTimeMicroseconds existed under the @aptos_framework.
 
 
 
-
requires chain_status::is_operating();
+
pragma opaque;
+requires chain_status::is_operating();
 pragma addition_overflow_unchecked;
 include AbortsIfNotContainProposalID<ProposalType>;
+ensures [abstract] result == spec_get_proposal_state<ProposalType>(voting_forum_address, proposal_id);
 

 
 
diff --git a/aptos-move/framework/aptos-framework/sources/account.spec.move b/aptos-move/framework/aptos-framework/sources/account.spec.move
index 4359b39659224..14e637fa3a172 100644
--- a/aptos-move/framework/aptos-framework/sources/account.spec.move
+++ b/aptos-move/framework/aptos-framework/sources/account.spec.move
@@ -155,18 +155,22 @@ spec aptos_framework::account {
             challenge: challenge,
         };
 
-        // let new_auth_key = spec_assert_valid_rotation_proof_signature_and_get_auth_key(to_scheme, to_public_key_bytes, cap_update_table, challenge);
+        // Verify all properties in update_auth_key_and_originating_address_table
+        let originating_addr = addr;
+        let new_auth_key_vector = spec_assert_valid_rotation_proof_signature_and_get_auth_key(to_scheme, to_public_key_bytes, cap_update_table, challenge);
 
-        // TODO: boogie error: Error: invalid type for argument 0 in application of $1_from_bcs_deserializable'address': int (expected: Vec int).
-        // include UpdateAuthKeyAndOriginatingAddressTableAbortsIf{
-        //     originating_addr: addr,
-        //     account_resource: account_resource,
-        //     new_auth_key_vector: new_auth_key
-        // };
-        pragma aborts_if_is_partial;
+        let address_map = global(@aptos_framework).address_map;
+        let new_auth_key = from_bcs::deserialize
(new_auth_key_vector);
+
+        aborts_if !exists(@aptos_framework);
+        aborts_if !from_bcs::deserializable
(account_resource.authentication_key);
+        aborts_if table::spec_contains(address_map, curr_auth_key) &&
+            table::spec_get(address_map, curr_auth_key) != originating_addr;
+
+        aborts_if !from_bcs::deserializable
(new_auth_key_vector);
+
+        aborts_if curr_auth_key != new_auth_key && table::spec_contains(address_map, new_auth_key);
 
-        modifies global(addr);
-        modifies global(@aptos_framework);
     }
 
     spec rotate_authentication_key_with_rotation_capability(
@@ -195,10 +199,20 @@ spec aptos_framework::account {
             signature: cap_update_table,
             challenge: challenge,
         };
-        // let new_auth_key = spec_assert_valid_rotation_proof_signature_and_get_auth_key(new_scheme, new_public_key_bytes, cap_update_table, challenge);
-        // TODO: Need to investigate the issue of including UpdateAuthKeyAndOriginatingAddressTableAbortsIf here.
-        // TODO: boogie error: Error: invalid type for argument 0 in application of $1_from_bcs_deserializable'address': int (expected: Vec int).
-        pragma aborts_if_is_partial;
+
+        let new_auth_key_vector = spec_assert_valid_rotation_proof_signature_and_get_auth_key(new_scheme, new_public_key_bytes, cap_update_table, challenge);
+        let address_map = global(@aptos_framework).address_map;
+
+        // Verify all properties in update_auth_key_and_originating_address_table
+        aborts_if !exists(@aptos_framework);
+        aborts_if !from_bcs::deserializable
(offerer_account_resource.authentication_key);
+        aborts_if table::spec_contains(address_map, curr_auth_key) &&
+            table::spec_get(address_map, curr_auth_key) != rotation_cap_offerer_address;
+
+        aborts_if !from_bcs::deserializable
(new_auth_key_vector);
+        let new_auth_key = from_bcs::deserialize
(new_auth_key_vector);
+
+        aborts_if curr_auth_key != new_auth_key && table::spec_contains(address_map, new_auth_key);
     }
 
     spec offer_rotation_capability(
diff --git a/aptos-move/framework/aptos-framework/sources/code.spec.move b/aptos-move/framework/aptos-framework/sources/code.spec.move
index 5e79a1ae6af4d..bcc76a388cc33 100644
--- a/aptos-move/framework/aptos-framework/sources/code.spec.move
+++ b/aptos-move/framework/aptos-framework/sources/code.spec.move
@@ -46,4 +46,11 @@ spec aptos_framework::code {
         // TODO: loop too deep.
         pragma verify = false;
     }
+
+    spec get_module_names(pack: &PackageMetadata): vector {
+        pragma opaque;
+        aborts_if [abstract] false;
+        ensures [abstract] len(result) == len(pack.modules);
+        ensures [abstract] forall i in 0..len(result): result[i] == pack.modules[i].name;
+    }
 }
diff --git a/aptos-move/framework/aptos-framework/sources/stake.spec.move b/aptos-move/framework/aptos-framework/sources/stake.spec.move
index 1e59cd3968458..aa117251a0bb2 100644
--- a/aptos-move/framework/aptos-framework/sources/stake.spec.move
+++ b/aptos-move/framework/aptos-framework/sources/stake.spec.move
@@ -27,6 +27,13 @@ spec aptos_framework::stake {
     // Function specifications
     // -----------------------
 
+    spec initialize_validator_fees(aptos_framework: &signer) {
+        let aptos_addr = signer::address_of(aptos_framework);
+        aborts_if !system_addresses::is_aptos_framework_address(aptos_addr);
+        aborts_if exists(aptos_addr);
+        ensures exists(aptos_addr);
+    }
+
     // `Validator` is initialized once.
     spec initialize(aptos_framework: &signer) {
         let aptos_addr = signer::address_of(aptos_framework);
diff --git a/aptos-move/framework/aptos-framework/sources/transaction_fee.spec.move b/aptos-move/framework/aptos-framework/sources/transaction_fee.spec.move
index 34716da641497..334f046e1de14 100644
--- a/aptos-move/framework/aptos-framework/sources/transaction_fee.spec.move
+++ b/aptos-move/framework/aptos-framework/sources/transaction_fee.spec.move
@@ -12,13 +12,41 @@ spec aptos_framework::transaction_fee {
     }
 
     spec initialize_fee_collection_and_distribution(aptos_framework: &signer, burn_percentage: u8) {
-        // TODO: monomorphization issue. duplicated boogie procedures.
-        pragma verify=false;
+        use std::signer;
+        use aptos_framework::stake::ValidatorFees;
+        use aptos_framework::aggregator_factory;
+        use aptos_framework::system_addresses;
+
+        aborts_if exists(@aptos_framework);
+        aborts_if burn_percentage > 100;
+
+        let aptos_addr = signer::address_of(aptos_framework);
+        aborts_if !system_addresses::is_aptos_framework_address(aptos_addr);
+        aborts_if exists(aptos_addr);
+
+        include system_addresses::AbortsIfNotAptosFramework {account: aptos_framework};
+        include aggregator_factory::CreateAggregatorInternalAbortsIf;
+
+        ensures exists(aptos_addr);
     }
 
     spec upgrade_burn_percentage(aptos_framework: &signer, new_burn_percentage: u8) {
-        // TODO: missing aborts_if spec
-        pragma verify=false;
+        use std::signer;
+        use aptos_framework::coin::CoinInfo;
+        use aptos_framework::aptos_coin::AptosCoin;
+        // Percentage validation
+        aborts_if new_burn_percentage > 100;
+        // Signer validation
+        let aptos_addr = signer::address_of(aptos_framework);
+        aborts_if !system_addresses::is_aptos_framework_address(aptos_addr);
+        // Requirements of `process_collected_fees`
+        requires exists(@aptos_framework);
+        requires exists(@aptos_framework);
+        requires exists>(@aptos_framework);
+        include RequiresCollectedFeesPerValueLeqBlockAptosSupply;
+        // The effect of upgrading the burn percentage
+        ensures exists(@aptos_framework) ==>
+            global(@aptos_framework).burn_percentage == new_burn_percentage;
     }
 
     spec register_proposer_for_fee_collection(proposer_addr: address) {
diff --git a/aptos-move/framework/aptos-framework/sources/voting.spec.move b/aptos-move/framework/aptos-framework/sources/voting.spec.move
index f887b3c7250a8..fd3625d61540e 100644
--- a/aptos-move/framework/aptos-framework/sources/voting.spec.move
+++ b/aptos-move/framework/aptos-framework/sources/voting.spec.move
@@ -114,14 +114,23 @@ spec aptos_framework::voting {
         voting_forum_address: address,
         proposal_id: u64,
     ) {
+
         use aptos_framework::chain_status;
 
         requires chain_status::is_operating(); // Ensures existence of Timestamp
-
+        include AbortsIfNotContainProposalID;
         // If the proposal is not resolvable, this function aborts.
+        aborts_if spec_get_proposal_state(voting_forum_address, proposal_id) != PROPOSAL_STATE_SUCCEEDED;
 
-        // TODO: Find a way to specify when it will abort. The opaque with spec fun doesn't work.
-        pragma aborts_if_is_strict = false;
+        let voting_forum =  global>(voting_forum_address);
+        let proposal = table::spec_get(voting_forum.proposals, proposal_id);
+
+        aborts_if proposal.is_resolved;
+        aborts_if !std::string::spec_internal_check_utf8(RESOLVABLE_TIME_METADATA_KEY);
+        aborts_if !simple_map::spec_contains_key(proposal.metadata, std::string::spec_utf8(RESOLVABLE_TIME_METADATA_KEY));
+        aborts_if !from_bcs::deserializable(simple_map::spec_get(proposal.metadata, std::string::spec_utf8(RESOLVABLE_TIME_METADATA_KEY)));
+        aborts_if timestamp::spec_now_seconds() <= from_bcs::deserialize(simple_map::spec_get(proposal.metadata, std::string::spec_utf8(RESOLVABLE_TIME_METADATA_KEY)));
+        aborts_if transaction_context::spec_get_script_hash() != proposal.execution_hash;
     }
 
     spec resolve(
@@ -164,16 +173,25 @@ spec aptos_framework::voting {
         aborts_if false;
     }
 
+    spec fun spec_get_proposal_state(
+        voting_forum_address: address,
+        proposal_id: u64,
+    ): u64;
+
     spec get_proposal_state(
         voting_forum_address: address,
         proposal_id: u64,
     ): u64 {
+
         use aptos_framework::chain_status;
+        pragma opaque;
         requires chain_status::is_operating(); // Ensures existence of Timestamp
         // Addition of yes_votes and no_votes might overflow.
         pragma addition_overflow_unchecked;
+
         include AbortsIfNotContainProposalID;
         // Any way to specify the result?
+        ensures [abstract] result == spec_get_proposal_state(voting_forum_address, proposal_id);
     }
 
     spec get_proposal_creation_secs(
@@ -255,4 +273,5 @@ spec aptos_framework::voting {
         requires chain_status::is_operating();
         aborts_if false;
     }
+
 }
diff --git a/aptos-move/framework/aptos-stdlib/doc/from_bcs.md b/aptos-move/framework/aptos-stdlib/doc/from_bcs.md
index adb0222db0dd3..5dc4812f0bfef 100644
--- a/aptos-move/framework/aptos-stdlib/doc/from_bcs.md
+++ b/aptos-move/framework/aptos-stdlib/doc/from_bcs.md
@@ -337,6 +337,10 @@ owned.
 fun deserializable<T>(bytes: vector<u8>): bool;
 axiom<T> forall b1: vector<u8>, b2: vector<u8>:
     (deserialize<T>(b1) == deserialize<T>(b2) ==> b1 == b2);
+axiom<T> forall b1: vector<u8>, b2: vector<u8>:
+    ( b1 == b2 ==> deserializable<T>(b1) == deserializable<T>(b2) );
+axiom<T> forall b1: vector<u8>, b2: vector<u8>:
+    ( b1 == b2 ==> deserialize<T>(b1) == deserialize<T>(b2) );
 

 
 
diff --git a/aptos-move/framework/aptos-stdlib/doc/smart_vector.md b/aptos-move/framework/aptos-stdlib/doc/smart_vector.md
index c4ae93ff04641..131fa86967b39 100644
--- a/aptos-move/framework/aptos-stdlib/doc/smart_vector.md
+++ b/aptos-move/framework/aptos-stdlib/doc/smart_vector.md
@@ -31,6 +31,7 @@
     -  [Function `destroy_empty`](#@Specification_1_destroy_empty)
     -  [Function `borrow`](#@Specification_1_borrow)
     -  [Function `append`](#@Specification_1_append)
+    -  [Function `push_back`](#@Specification_1_push_back)
     -  [Function `pop_back`](#@Specification_1_pop_back)
     -  [Function `remove`](#@Specification_1_remove)
     -  [Function `swap_remove`](#@Specification_1_swap_remove)
@@ -891,6 +892,22 @@ Return true if the vector v has no elements and
 
 
 
+
pragma verify = false;
+

+
+
+
+
+
+### Function `push_back`
+
+
+
public fun push_back<T: store>(v: &mut smart_vector::SmartVector<T>, val: T)
+

+
+
+
+
 
pragma verify = false;
 

 
diff --git a/aptos-move/framework/aptos-stdlib/sources/data_structures/smart_vector.spec.move b/aptos-move/framework/aptos-stdlib/sources/data_structures/smart_vector.spec.move
index ba8f135b68ddf..c4bfca925cd51 100644
--- a/aptos-move/framework/aptos-stdlib/sources/data_structures/smart_vector.spec.move
+++ b/aptos-move/framework/aptos-stdlib/sources/data_structures/smart_vector.spec.move
@@ -33,6 +33,10 @@ spec aptos_std::smart_vector {
         );
     }
 
+    spec push_back(v: &mut SmartVector, val: T) {
+        pragma verify = false; // TODO: set to false because of timeout
+    }
+
     spec pop_back {
         use aptos_std::table_with_length;
 
diff --git a/aptos-move/framework/aptos-stdlib/sources/from_bcs.spec.move b/aptos-move/framework/aptos-stdlib/sources/from_bcs.spec.move
index 71f43efd783d7..9eeb4f025cdc2 100644
--- a/aptos-move/framework/aptos-stdlib/sources/from_bcs.spec.move
+++ b/aptos-move/framework/aptos-stdlib/sources/from_bcs.spec.move
@@ -14,6 +14,13 @@ spec aptos_std::from_bcs {
         axiom forall b1: vector, b2: vector:
             (deserialize(b1) == deserialize(b2) ==> b1 == b2);
 
+        // If the input are equal, the result of deserialize should be equal too
+        axiom forall b1: vector, b2: vector:
+            ( b1 == b2 ==> deserializable(b1) == deserializable(b2) );
+
+        axiom forall b1: vector, b2: vector:
+            ( b1 == b2 ==> deserialize(b1) == deserialize(b2) );
+
         // `deserialize` is an inverse function of `bcs::serialize`.
         // TODO: disabled because this generic axiom causes a timeout.
         // axiom forall v: T: deserialize(bcs::serialize(v)) == v;

From 3eb59f36c89c663e28d650c00b0a725448670feb Mon Sep 17 00:00:00 2001
From: Balaji Arun 
Date: Wed, 14 Jun 2023 07:32:43 -0700
Subject: [PATCH 165/200] [GHA] Pin main branch workflow for indexer workflow
 (#8653)

---
 .github/workflows/docker-build-test.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/docker-build-test.yaml b/.github/workflows/docker-build-test.yaml
index 3764a3f094af0..4f079c829e087 100644
--- a/.github/workflows/docker-build-test.yaml
+++ b/.github/workflows/docker-build-test.yaml
@@ -207,7 +207,7 @@ jobs:
       contains(github.event.pull_request.labels.*.name, 'CICD:run-e2e-tests') ||
       github.event.pull_request.auto_merge != null ||
       contains(github.event.pull_request.body, '#e2e')
-    uses: ./.github/workflows/docker-indexer-grpc-test.yaml
+    uses: aptos-labs/aptos-core/.github/workflows/docker-indexer-grpc-test.yaml@main
     secrets: inherit
     with:
       GIT_SHA: ${{ needs.determine-docker-build-metadata.outputs.gitSha }}

From a52626960ecb420978a27f056ff93e9472a8d245 Mon Sep 17 00:00:00 2001
From: Sital Kedia 
Date: Wed, 14 Jun 2023 09:22:24 -0700
Subject: [PATCH 166/200] Sharded blockstm api (#8650)

---
 Cargo.lock                                    |   1 +
 aptos-move/aptos-vm/src/aptos_vm.rs           |   3 +-
 aptos-move/aptos-vm/src/block_executor/mod.rs |  56 +++++++--
 .../block_executor_client.rs                  |   8 +-
 aptos-move/block-executor/src/executor.rs     |  26 ++++-
 .../src/proptest_types/bencher.rs             |   8 +-
 .../src/proptest_types/tests.rs               |  40 +++++--
 aptos-move/block-executor/src/task.rs         |   2 +-
 .../block-executor/src/unit_tests/mod.rs      |  13 ++-
 aptos-move/e2e-tests/src/executor.rs          |   3 +-
 consensus/src/state_computer.rs               |   4 +-
 execution/block-partitioner/src/lib.rs        |   1 -
 .../conflict_detector.rs                      |  10 +-
 .../cross_shard_messages.rs                   |  10 +-
 .../dependency_analysis.rs                    |   6 +-
 .../dependent_edges.rs                        |  23 ++--
 .../src/sharded_block_partitioner/messages.rs |  20 ++--
 .../src/sharded_block_partitioner/mod.rs      |  46 ++++----
 .../partitioning_shard.rs                     |  21 ++--
 .../executor-benchmark/src/native_executor.rs |   4 +-
 execution/executor-types/src/lib.rs           |  47 +-------
 execution/executor/src/block_executor.rs      |  19 ++--
 .../executor/src/components/chunk_output.rs   |   5 +-
 execution/executor/src/fuzzing.rs             |   5 +-
 execution/executor/src/mock_vm/mod.rs         |   4 +-
 types/Cargo.toml                              |   1 +
 types/src/block_executor/mod.rs               |   5 +
 .../src/block_executor/partitioner.rs         | 107 ++++++++++++++----
 types/src/lib.rs                              |   1 +
 29 files changed, 311 insertions(+), 188 deletions(-)
 create mode 100644 types/src/block_executor/mod.rs
 rename execution/block-partitioner/src/types.rs => types/src/block_executor/partitioner.rs (75%)

diff --git a/Cargo.lock b/Cargo.lock
index 58d9402234a96..182e78620ea7f 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3330,6 +3330,7 @@ dependencies = [
  "proptest",
  "proptest-derive",
  "rand 0.7.3",
+ "rayon",
  "regex",
  "serde 1.0.149",
  "serde_bytes",
diff --git a/aptos-move/aptos-vm/src/aptos_vm.rs b/aptos-move/aptos-vm/src/aptos_vm.rs
index 0f8699434cfb5..bf2d836e81dd6 100644
--- a/aptos-move/aptos-vm/src/aptos_vm.rs
+++ b/aptos-move/aptos-vm/src/aptos_vm.rs
@@ -30,6 +30,7 @@ use aptos_state_view::StateView;
 use aptos_types::{
     account_config,
     account_config::new_block_event_key,
+    block_executor::partitioner::ExecutableTransactions,
     block_metadata::BlockMetadata,
     on_chain_config::{new_epoch_event_key, FeatureFlag, TimedFeatureOverride},
     transaction::{
@@ -1505,7 +1506,7 @@ impl VMExecutor for AptosVM {
         let count = transactions.len();
         let ret = BlockAptosVM::execute_block(
             Arc::clone(&RAYON_EXEC_POOL),
-            transactions,
+            ExecutableTransactions::Unsharded(transactions),
             state_view,
             Self::get_concurrency_level(),
             maybe_block_gas_limit,
diff --git a/aptos-move/aptos-vm/src/block_executor/mod.rs b/aptos-move/aptos-vm/src/block_executor/mod.rs
index e1c8d68f959e1..02571191498e9 100644
--- a/aptos-move/aptos-vm/src/block_executor/mod.rs
+++ b/aptos-move/aptos-vm/src/block_executor/mod.rs
@@ -25,6 +25,7 @@ use aptos_block_executor::{
 use aptos_infallible::Mutex;
 use aptos_state_view::{StateView, StateViewId};
 use aptos_types::{
+    block_executor::partitioner::{ExecutableTransactions, SubBlock, TransactionWithDependencies},
     executable::ExecutableTestType,
     state_store::state_key::StateKey,
     transaction::{Transaction, TransactionOutput, TransactionStatus},
@@ -132,9 +133,50 @@ impl BlockExecutorTransactionOutput for AptosTransactionOutput {
 pub struct BlockAptosVM();
 
 impl BlockAptosVM {
+    fn verify_transactions(
+        transactions: ExecutableTransactions,
+    ) -> ExecutableTransactions {
+        match transactions {
+            ExecutableTransactions::Unsharded(transactions) => {
+                let signature_verified_txns = transactions
+                    .into_par_iter()
+                    .with_min_len(25)
+                    .map(preprocess_transaction::)
+                    .collect();
+                ExecutableTransactions::Unsharded(signature_verified_txns)
+            },
+            ExecutableTransactions::Sharded(sub_blocks) => {
+                let signature_verified_block = sub_blocks
+                    .into_par_iter()
+                    .map(|sub_block| {
+                        let start_index = sub_block.start_index;
+                        let verified_txns = sub_block
+                            .into_transactions_with_deps()
+                            .into_par_iter()
+                            .with_min_len(25)
+                            .map(|txn_with_deps| {
+                                let TransactionWithDependencies {
+                                    txn,
+                                    cross_shard_dependencies,
+                                } = txn_with_deps;
+                                let preprocessed_txn = preprocess_transaction::(txn);
+                                TransactionWithDependencies::new(
+                                    preprocessed_txn,
+                                    cross_shard_dependencies,
+                                )
+                            })
+                            .collect();
+                        SubBlock::new(start_index, verified_txns)
+                    })
+                    .collect();
+                ExecutableTransactions::Sharded(signature_verified_block)
+            },
+        }
+    }
+
     pub fn execute_block(
         executor_thread_pool: Arc,
-        transactions: Vec,
+        transactions: ExecutableTransactions,
         state_view: &S,
         concurrency_level: usize,
         maybe_block_gas_limit: Option,
@@ -146,17 +188,11 @@ impl BlockAptosVM {
         // TODO: state sync runs this code but doesn't need to verify signatures
         let signature_verification_timer =
             BLOCK_EXECUTOR_SIGNATURE_VERIFICATION_SECONDS.start_timer();
-        let signature_verified_block: Vec =
-            executor_thread_pool.install(|| {
-                transactions
-                    .into_par_iter()
-                    .with_min_len(25)
-                    .map(preprocess_transaction::)
-                    .collect()
-            });
+        let signature_verified_block =
+            executor_thread_pool.install(|| Self::verify_transactions(transactions));
         drop(signature_verification_timer);
 
-        let num_txns = signature_verified_block.len();
+        let num_txns = signature_verified_block.num_transactions();
         if state_view.id() != StateViewId::Miscellaneous {
             // Speculation is disabled in Miscellaneous context, which is used by testing and
             // can even lead to concurrent execute_block invocations, leading to errors on flush.
diff --git a/aptos-move/aptos-vm/src/sharded_block_executor/block_executor_client.rs b/aptos-move/aptos-vm/src/sharded_block_executor/block_executor_client.rs
index 289aeb4730471..d0989145637ad 100644
--- a/aptos-move/aptos-vm/src/sharded_block_executor/block_executor_client.rs
+++ b/aptos-move/aptos-vm/src/sharded_block_executor/block_executor_client.rs
@@ -2,7 +2,10 @@
 
 use crate::block_executor::BlockAptosVM;
 use aptos_state_view::StateView;
-use aptos_types::transaction::{Transaction, TransactionOutput};
+use aptos_types::{
+    block_executor::partitioner::ExecutableTransactions,
+    transaction::{Transaction, TransactionOutput},
+};
 use move_core_types::vm_status::VMStatus;
 use std::sync::Arc;
 
@@ -26,7 +29,8 @@ impl BlockExecutorClient for LocalExecutorClient {
     ) -> Result, VMStatus> {
         BlockAptosVM::execute_block(
             self.executor_thread_pool.clone(),
-            transactions,
+            // TODO: (skedia) Change this to sharded transactions
+            ExecutableTransactions::Unsharded(transactions),
             state_view,
             concurrency_level,
             maybe_block_gas_limit,
diff --git a/aptos-move/block-executor/src/executor.rs b/aptos-move/block-executor/src/executor.rs
index 2174c03bfdc96..14bc066de9153 100644
--- a/aptos-move/block-executor/src/executor.rs
+++ b/aptos-move/block-executor/src/executor.rs
@@ -22,7 +22,9 @@ use aptos_mvhashmap::{
     MVHashMap,
 };
 use aptos_state_view::TStateView;
-use aptos_types::{executable::Executable, write_set::WriteOp};
+use aptos_types::{
+    block_executor::partitioner::ExecutableTransactions, executable::Executable, write_set::WriteOp,
+};
 use aptos_vm_logging::{clear_speculative_txn_logs, init_speculative_logs};
 use num_cpus;
 use rayon::ThreadPool;
@@ -428,7 +430,7 @@ where
     pub(crate) fn execute_transactions_parallel(
         &self,
         executor_initial_arguments: E::Argument,
-        signature_verified_block: &Vec,
+        signature_verified_block: &ExecutableTransactions,
         base_view: &S,
     ) -> Result, E::Error> {
         let _timer = PARALLEL_EXECUTION_SECONDS.start_timer();
@@ -438,6 +440,13 @@ where
         // w. concurrency_level = 1 for some reason.
         assert!(self.concurrency_level > 1, "Must use sequential execution");
 
+        let signature_verified_block = match signature_verified_block {
+            ExecutableTransactions::Unsharded(txns) => txns,
+            ExecutableTransactions::Sharded(_) => {
+                unimplemented!("Sharded execution is not supported yet")
+            },
+        };
+
         let versioned_cache = MVHashMap::new();
 
         if signature_verified_block.is_empty() {
@@ -526,9 +535,16 @@ where
     pub(crate) fn execute_transactions_sequential(
         &self,
         executor_arguments: E::Argument,
-        signature_verified_block: &[T],
+        signature_verified_block: &ExecutableTransactions,
         base_view: &S,
     ) -> Result, E::Error> {
+        let signature_verified_block = match signature_verified_block {
+            ExecutableTransactions::Unsharded(txns) => txns,
+            ExecutableTransactions::Sharded(_) => {
+                unimplemented!("Sharded execution is not supported yet")
+            },
+        };
+
         let num_txns = signature_verified_block.len();
         let executor = E::init(executor_arguments);
         let data_map = UnsyncMap::new();
@@ -600,7 +616,7 @@ where
     pub fn execute_block(
         &self,
         executor_arguments: E::Argument,
-        signature_verified_block: Vec,
+        signature_verified_block: ExecutableTransactions,
         base_view: &S,
     ) -> Result, E::Error> {
         let mut ret = if self.concurrency_level > 1 {
@@ -622,7 +638,7 @@ where
 
             // All logs from the parallel execution should be cleared and not reported.
             // Clear by re-initializing the speculative logs.
-            init_speculative_logs(signature_verified_block.len());
+            init_speculative_logs(signature_verified_block.num_transactions());
 
             ret = self.execute_transactions_sequential(
                 executor_arguments,
diff --git a/aptos-move/block-executor/src/proptest_types/bencher.rs b/aptos-move/block-executor/src/proptest_types/bencher.rs
index 87bb442323e64..d3ffb13905e59 100644
--- a/aptos-move/block-executor/src/proptest_types/bencher.rs
+++ b/aptos-move/block-executor/src/proptest_types/bencher.rs
@@ -9,7 +9,9 @@ use crate::{
         TransactionGenParams, ValueType,
     },
 };
-use aptos_types::executable::ExecutableTestType;
+use aptos_types::{
+    block_executor::partitioner::ExecutableTransactions, executable::ExecutableTestType,
+};
 use criterion::{BatchSize, Bencher as CBencher};
 use num_cpus;
 use proptest::{
@@ -34,7 +36,7 @@ pub(crate) struct BencherState<
 > where
     Vec: From,
 {
-    transactions: Vec, ValueType>>,
+    transactions: ExecutableTransactions, ValueType>>,
     expected_output: ExpectedOutput>,
 }
 
@@ -104,7 +106,7 @@ where
         let expected_output = ExpectedOutput::generate_baseline(&transactions, None, None);
 
         Self {
-            transactions,
+            transactions: ExecutableTransactions::Unsharded(transactions),
             expected_output,
         }
     }
diff --git a/aptos-move/block-executor/src/proptest_types/tests.rs b/aptos-move/block-executor/src/proptest_types/tests.rs
index 73e65ff53423a..da4f45966c529 100644
--- a/aptos-move/block-executor/src/proptest_types/tests.rs
+++ b/aptos-move/block-executor/src/proptest_types/tests.rs
@@ -10,7 +10,9 @@ use crate::{
         TransactionGenParams, ValueType,
     },
 };
-use aptos_types::executable::ExecutableTestType;
+use aptos_types::{
+    block_executor::partitioner::ExecutableTransactions, executable::ExecutableTestType,
+};
 use claims::assert_ok;
 use num_cpus;
 use proptest::{
@@ -60,6 +62,8 @@ fn run_transactions(
             .unwrap(),
     );
 
+    let executable_txns = ExecutableTransactions::Unsharded(transactions);
+
     for _ in 0..num_repeat {
         let output = BlockExecutor::<
             Transaction, ValueType>,
@@ -71,15 +75,18 @@ fn run_transactions(
             executor_thread_pool.clone(),
             maybe_block_gas_limit,
         )
-        .execute_transactions_parallel((), &transactions, &data_view);
+        .execute_transactions_parallel((), &executable_txns, &data_view);
 
         if module_access.0 && module_access.1 {
             assert_eq!(output.unwrap_err(), Error::ModulePathReadWrite);
             continue;
         }
 
-        let baseline =
-            ExpectedOutput::generate_baseline(&transactions, None, maybe_block_gas_limit);
+        let baseline = ExpectedOutput::generate_baseline(
+            executable_txns.get_unsharded_transactions().unwrap(),
+            None,
+            maybe_block_gas_limit,
+        );
         baseline.assert_output(&output);
     }
 }
@@ -184,6 +191,8 @@ fn deltas_writes_mixed_with_block_gas_limit(num_txns: usize, maybe_block_gas_lim
         .map(|txn_gen| txn_gen.materialize_with_deltas(&universe, 15, false))
         .collect();
 
+    let executable_txns = ExecutableTransactions::Unsharded(transactions);
+
     let data_view = DeltaDataView::, ValueType<[u8; 32]>> {
         phantom: PhantomData,
     };
@@ -206,10 +215,13 @@ fn deltas_writes_mixed_with_block_gas_limit(num_txns: usize, maybe_block_gas_lim
             executor_thread_pool.clone(),
             maybe_block_gas_limit,
         )
-        .execute_transactions_parallel((), &transactions, &data_view);
+        .execute_transactions_parallel((), &executable_txns, &data_view);
 
-        let baseline =
-            ExpectedOutput::generate_baseline(&transactions, None, maybe_block_gas_limit);
+        let baseline = ExpectedOutput::generate_baseline(
+            executable_txns.get_unsharded_transactions().unwrap(),
+            None,
+            maybe_block_gas_limit,
+        );
         baseline.assert_output(&output);
     }
 }
@@ -239,6 +251,8 @@ fn deltas_resolver_with_block_gas_limit(num_txns: usize, maybe_block_gas_limit:
         .map(|txn_gen| txn_gen.materialize_with_deltas(&universe, 15, false))
         .collect();
 
+    let executable_txns = ExecutableTransactions::Unsharded(transactions);
+
     let executor_thread_pool = Arc::new(
         rayon::ThreadPoolBuilder::new()
             .num_threads(num_cpus::get())
@@ -257,7 +271,7 @@ fn deltas_resolver_with_block_gas_limit(num_txns: usize, maybe_block_gas_limit:
             executor_thread_pool.clone(),
             maybe_block_gas_limit,
         )
-        .execute_transactions_parallel((), &transactions, &data_view);
+        .execute_transactions_parallel((), &executable_txns, &data_view);
 
         let delta_writes = output
             .as_ref()
@@ -267,7 +281,7 @@ fn deltas_resolver_with_block_gas_limit(num_txns: usize, maybe_block_gas_limit:
             .collect();
 
         let baseline = ExpectedOutput::generate_baseline(
-            &transactions,
+            executable_txns.get_unsharded_transactions().unwrap(),
             Some(delta_writes),
             maybe_block_gas_limit,
         );
@@ -413,6 +427,8 @@ fn publishing_fixed_params_with_block_gas_limit(
         phantom: PhantomData,
     };
 
+    let executable_txns = ExecutableTransactions::Unsharded(transactions.clone());
+
     let executor_thread_pool = Arc::new(
         rayon::ThreadPoolBuilder::new()
             .num_threads(num_cpus::get())
@@ -427,7 +443,7 @@ fn publishing_fixed_params_with_block_gas_limit(
         DeltaDataView, ValueType<[u8; 32]>>,
         ExecutableTestType,
     >::new(num_cpus::get(), executor_thread_pool, maybe_block_gas_limit)
-    .execute_transactions_parallel((), &transactions, &data_view);
+    .execute_transactions_parallel((), &executable_txns, &data_view);
     assert_ok!(output);
 
     // Adjust the reads of txn indices[2] to contain module read to key 42.
@@ -464,6 +480,8 @@ fn publishing_fixed_params_with_block_gas_limit(
             .unwrap(),
     );
 
+    let executable_txns = ExecutableTransactions::Unsharded(transactions);
+
     for _ in 0..200 {
         let output = BlockExecutor::<
             Transaction, ValueType<[u8; 32]>>,
@@ -475,7 +493,7 @@ fn publishing_fixed_params_with_block_gas_limit(
             executor_thread_pool.clone(),
             Some(max(w_index, r_index) as u64 + 1),
         ) // Ensure enough gas limit to commit the module txns
-        .execute_transactions_parallel((), &transactions, &data_view);
+        .execute_transactions_parallel((), &executable_txns, &data_view);
 
         assert_eq!(output.unwrap_err(), Error::ModulePathReadWrite);
     }
diff --git a/aptos-move/block-executor/src/task.rs b/aptos-move/block-executor/src/task.rs
index 7589bef53ded1..ffc448e3d98af 100644
--- a/aptos-move/block-executor/src/task.rs
+++ b/aptos-move/block-executor/src/task.rs
@@ -24,7 +24,7 @@ pub enum ExecutionStatus {
     SkipRest(T),
 }
 
-/// Trait that defines a transaction that could be parallel executed by the scheduler. Each
+/// Trait that defines a transaction type that can be executed by the block executor. A transaction
 /// transaction will write to a key value storage as their side effect.
 pub trait Transaction: Sync + Send + 'static {
     type Key: PartialOrd + Ord + Send + Sync + Clone + Hash + Eq + ModulePath + Debug;
diff --git a/aptos-move/block-executor/src/unit_tests/mod.rs b/aptos-move/block-executor/src/unit_tests/mod.rs
index 5265da748fbc4..60458ee9dae09 100644
--- a/aptos-move/block-executor/src/unit_tests/mod.rs
+++ b/aptos-move/block-executor/src/unit_tests/mod.rs
@@ -10,6 +10,7 @@ use crate::{
 use aptos_aggregator::delta_change_set::{delta_add, delta_sub, DeltaOp, DeltaUpdate};
 use aptos_mvhashmap::types::TxnIndex;
 use aptos_types::{
+    block_executor::partitioner::ExecutableTransactions,
     executable::{ExecutableTestType, ModulePath},
     write_set::TransactionWrite,
 };
@@ -40,15 +41,23 @@ where
             .unwrap(),
     );
 
+    let executable_transactions = ExecutableTransactions::Unsharded(transactions);
+
     let output = BlockExecutor::<
         Transaction,
         Task,
         DeltaDataView,
         ExecutableTestType,
     >::new(num_cpus::get(), executor_thread_pool, None)
-    .execute_transactions_parallel((), &transactions, &data_view);
+    .execute_transactions_parallel((), &executable_transactions, &data_view);
 
-    let baseline = ExpectedOutput::generate_baseline(&transactions, None, None);
+    let baseline = ExpectedOutput::generate_baseline(
+        executable_transactions
+            .get_unsharded_transactions()
+            .unwrap(),
+        None,
+        None,
+    );
     baseline.assert_output(&output);
 }
 
diff --git a/aptos-move/e2e-tests/src/executor.rs b/aptos-move/e2e-tests/src/executor.rs
index 1277113e8632f..a055b52243925 100644
--- a/aptos-move/e2e-tests/src/executor.rs
+++ b/aptos-move/e2e-tests/src/executor.rs
@@ -28,6 +28,7 @@ use aptos_types::{
         new_block_event_key, AccountResource, CoinInfoResource, CoinStoreResource, NewBlockEvent,
         CORE_CODE_ADDRESS,
     },
+    block_executor::partitioner::ExecutableTransactions,
     block_metadata::BlockMetadata,
     chain_id::ChainId,
     on_chain_config::{
@@ -416,7 +417,7 @@ impl FakeExecutor {
     ) -> Result, VMStatus> {
         BlockAptosVM::execute_block(
             self.executor_thread_pool.clone(),
-            txn_block,
+            ExecutableTransactions::Unsharded(txn_block),
             &self.data_store,
             usize::min(4, num_cpus::get()),
             None,
diff --git a/consensus/src/state_computer.rs b/consensus/src/state_computer.rs
index 9656e5ab4c56d..2f6bbdcdb1703 100644
--- a/consensus/src/state_computer.rs
+++ b/consensus/src/state_computer.rs
@@ -331,9 +331,9 @@ async fn test_commit_sync_race() {
         transaction_shuffler::create_transaction_shuffler,
     };
     use aptos_consensus_notifications::Error;
-    use aptos_executor_types::ExecutableBlock;
     use aptos_types::{
         aggregate_signature::AggregateSignature,
+        block_executor::partitioner::ExecutableBlock,
         block_info::BlockInfo,
         ledger_info::LedgerInfo,
         on_chain_config::{TransactionDeduperType, TransactionShufflerType},
@@ -355,7 +355,7 @@ async fn test_commit_sync_race() {
 
         fn execute_block(
             &self,
-            _block: ExecutableBlock,
+            _block: ExecutableBlock,
             _parent_block_id: HashValue,
             _maybe_block_gas_limit: Option,
         ) -> Result {
diff --git a/execution/block-partitioner/src/lib.rs b/execution/block-partitioner/src/lib.rs
index da04fc2c2be7b..000f232ca6686 100644
--- a/execution/block-partitioner/src/lib.rs
+++ b/execution/block-partitioner/src/lib.rs
@@ -4,7 +4,6 @@
 
 pub mod sharded_block_partitioner;
 pub mod test_utils;
-pub mod types;
 
 use aptos_types::transaction::Transaction;
 
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/conflict_detector.rs b/execution/block-partitioner/src/sharded_block_partitioner/conflict_detector.rs
index bed926dc5fc07..cd42de9e8a939 100644
--- a/execution/block-partitioner/src/sharded_block_partitioner/conflict_detector.rs
+++ b/execution/block-partitioner/src/sharded_block_partitioner/conflict_detector.rs
@@ -1,13 +1,13 @@
 // Copyright © Aptos Foundation
 
-use crate::{
-    sharded_block_partitioner::dependency_analysis::{RWSet, WriteSetWithTxnIndex},
-    types::{
+use crate::sharded_block_partitioner::dependency_analysis::{RWSet, WriteSetWithTxnIndex};
+use aptos_types::{
+    block_executor::partitioner::{
         CrossShardDependencies, ShardId, SubBlock, TransactionWithDependencies, TxnIdxWithShardId,
         TxnIndex,
     },
+    transaction::analyzed_transaction::{AnalyzedTransaction, StorageLocation},
 };
-use aptos_types::transaction::analyzed_transaction::{AnalyzedTransaction, StorageLocation};
 use std::{
     collections::hash_map::DefaultHasher,
     hash::{Hash, Hasher},
@@ -114,7 +114,7 @@ impl CrossShardConflictDetector {
         current_round_rw_set_with_index: Arc>,
         prev_round_rw_set_with_index: Arc>,
         index_offset: TxnIndex,
-    ) -> (SubBlock, Vec) {
+    ) -> (SubBlock, Vec) {
         let mut frozen_txns = Vec::new();
         let mut cross_shard_dependencies = Vec::new();
         for txn in txns.into_iter() {
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/cross_shard_messages.rs b/execution/block-partitioner/src/sharded_block_partitioner/cross_shard_messages.rs
index c7cd693a0ca00..b7234522069f8 100644
--- a/execution/block-partitioner/src/sharded_block_partitioner/cross_shard_messages.rs
+++ b/execution/block-partitioner/src/sharded_block_partitioner/cross_shard_messages.rs
@@ -1,13 +1,11 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
-use crate::{
-    sharded_block_partitioner::{
-        cross_shard_messages::CrossShardMsg::CrossShardDependentEdgesMsg,
-        dependency_analysis::{RWSet, WriteSetWithTxnIndex},
-    },
-    types::{CrossShardEdges, ShardId, TxnIndex},
+use crate::sharded_block_partitioner::{
+    cross_shard_messages::CrossShardMsg::CrossShardDependentEdgesMsg,
+    dependency_analysis::{RWSet, WriteSetWithTxnIndex},
 };
+use aptos_types::block_executor::partitioner::{CrossShardEdges, ShardId, TxnIndex};
 use std::sync::mpsc::{Receiver, Sender};
 
 #[derive(Clone, Debug)]
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/dependency_analysis.rs b/execution/block-partitioner/src/sharded_block_partitioner/dependency_analysis.rs
index 7da289c06611e..2fea666162fc3 100644
--- a/execution/block-partitioner/src/sharded_block_partitioner/dependency_analysis.rs
+++ b/execution/block-partitioner/src/sharded_block_partitioner/dependency_analysis.rs
@@ -1,7 +1,9 @@
 // Copyright © Aptos Foundation
 
-use crate::types::TxnIndex;
-use aptos_types::transaction::analyzed_transaction::{AnalyzedTransaction, StorageLocation};
+use aptos_types::{
+    block_executor::partitioner::TxnIndex,
+    transaction::analyzed_transaction::{AnalyzedTransaction, StorageLocation},
+};
 use std::{
     collections::{HashMap, HashSet},
     sync::Arc,
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/dependent_edges.rs b/execution/block-partitioner/src/sharded_block_partitioner/dependent_edges.rs
index b903d085c791d..2b8240b4cea82 100644
--- a/execution/block-partitioner/src/sharded_block_partitioner/dependent_edges.rs
+++ b/execution/block-partitioner/src/sharded_block_partitioner/dependent_edges.rs
@@ -1,14 +1,15 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
-use crate::{
-    sharded_block_partitioner::cross_shard_messages::{
-        CrossShardClientInterface, CrossShardDependentEdges,
-    },
-    types::{
+use crate::sharded_block_partitioner::cross_shard_messages::{
+    CrossShardClientInterface, CrossShardDependentEdges,
+};
+use aptos_types::{
+    block_executor::partitioner::{
         CrossShardDependencies, CrossShardEdges, ShardId, SubBlocksForShard, TxnIdxWithShardId,
         TxnIndex,
     },
+    transaction::analyzed_transaction::AnalyzedTransaction,
 };
 use itertools::Itertools;
 use std::{collections::HashMap, sync::Arc};
@@ -16,7 +17,7 @@ use std::{collections::HashMap, sync::Arc};
 pub struct DependentEdgeCreator {
     shard_id: ShardId,
     cross_shard_client: Arc,
-    froze_sub_blocks: SubBlocksForShard,
+    froze_sub_blocks: SubBlocksForShard,
     num_shards: usize,
 }
 
@@ -32,7 +33,7 @@ impl DependentEdgeCreator {
     pub fn new(
         shard_id: ShardId,
         cross_shard_client: Arc,
-        froze_sub_blocks: SubBlocksForShard,
+        froze_sub_blocks: SubBlocksForShard,
         num_shards: usize,
     ) -> Self {
         Self {
@@ -155,7 +156,7 @@ impl DependentEdgeCreator {
         }
     }
 
-    pub fn into_frozen_sub_blocks(self) -> SubBlocksForShard {
+    pub fn into_frozen_sub_blocks(self) -> SubBlocksForShard {
         self.froze_sub_blocks
     }
 }
@@ -168,12 +169,14 @@ mod tests {
             dependent_edges::DependentEdgeCreator,
         },
         test_utils::create_non_conflicting_p2p_transaction,
-        types::{
+    };
+    use aptos_types::{
+        block_executor::partitioner::{
             CrossShardDependencies, CrossShardEdges, SubBlock, SubBlocksForShard,
             TransactionWithDependencies, TxnIdxWithShardId,
         },
+        transaction::analyzed_transaction::StorageLocation,
     };
-    use aptos_types::transaction::analyzed_transaction::StorageLocation;
     use std::sync::Arc;
 
     #[test]
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/messages.rs b/execution/block-partitioner/src/sharded_block_partitioner/messages.rs
index d0770433d8bb8..7336855022947 100644
--- a/execution/block-partitioner/src/sharded_block_partitioner/messages.rs
+++ b/execution/block-partitioner/src/sharded_block_partitioner/messages.rs
@@ -1,10 +1,10 @@
 // Copyright © Aptos Foundation
 
-use crate::{
-    sharded_block_partitioner::dependency_analysis::WriteSetWithTxnIndex,
-    types::{SubBlocksForShard, TxnIndex},
+use crate::sharded_block_partitioner::dependency_analysis::WriteSetWithTxnIndex;
+use aptos_types::{
+    block_executor::partitioner::{SubBlocksForShard, TxnIndex},
+    transaction::analyzed_transaction::AnalyzedTransaction,
 };
-use aptos_types::transaction::analyzed_transaction::AnalyzedTransaction;
 use std::sync::Arc;
 
 pub struct DiscardCrossShardDep {
@@ -14,7 +14,7 @@ pub struct DiscardCrossShardDep {
     pub current_round_start_index: TxnIndex,
     // This is the frozen sub block for the current shard and is passed because we want to modify
     // it to add dependency back edges.
-    pub frozen_sub_blocks: SubBlocksForShard,
+    pub frozen_sub_blocks: SubBlocksForShard,
 }
 
 impl DiscardCrossShardDep {
@@ -22,7 +22,7 @@ impl DiscardCrossShardDep {
         transactions: Vec,
         prev_rounds_write_set_with_index: Arc>,
         current_round_start_index: TxnIndex,
-        frozen_sub_blocks: SubBlocksForShard,
+        frozen_sub_blocks: SubBlocksForShard,
     ) -> Self {
         Self {
             transactions,
@@ -38,7 +38,7 @@ pub struct AddWithCrossShardDep {
     pub index_offset: TxnIndex,
     // The frozen dependencies in previous chunks.
     pub prev_rounds_write_set_with_index: Arc>,
-    pub frozen_sub_blocks: SubBlocksForShard,
+    pub frozen_sub_blocks: SubBlocksForShard,
 }
 
 impl AddWithCrossShardDep {
@@ -46,7 +46,7 @@ impl AddWithCrossShardDep {
         transactions: Vec,
         index_offset: TxnIndex,
         prev_rounds_write_set_with_index: Arc>,
-        frozen_sub_blocks: SubBlocksForShard,
+        frozen_sub_blocks: SubBlocksForShard,
     ) -> Self {
         Self {
             transactions,
@@ -58,14 +58,14 @@ impl AddWithCrossShardDep {
 }
 
 pub struct PartitioningResp {
-    pub frozen_sub_blocks: SubBlocksForShard,
+    pub frozen_sub_blocks: SubBlocksForShard,
     pub write_set_with_index: WriteSetWithTxnIndex,
     pub discarded_txns: Vec,
 }
 
 impl PartitioningResp {
     pub fn new(
-        frozen_sub_blocks: SubBlocksForShard,
+        frozen_sub_blocks: SubBlocksForShard,
         write_set_with_index: WriteSetWithTxnIndex,
         discarded_txns: Vec,
     ) -> Self {
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/mod.rs b/execution/block-partitioner/src/sharded_block_partitioner/mod.rs
index 3ea0842ca428b..9951a476535b7 100644
--- a/execution/block-partitioner/src/sharded_block_partitioner/mod.rs
+++ b/execution/block-partitioner/src/sharded_block_partitioner/mod.rs
@@ -1,21 +1,21 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
-use crate::{
-    sharded_block_partitioner::{
-        cross_shard_messages::CrossShardMsg,
-        dependency_analysis::WriteSetWithTxnIndex,
-        messages::{
-            AddWithCrossShardDep, ControlMsg,
-            ControlMsg::{AddCrossShardDepReq, DiscardCrossShardDepReq},
-            DiscardCrossShardDep, PartitioningResp,
-        },
-        partitioning_shard::PartitioningShard,
+use crate::sharded_block_partitioner::{
+    cross_shard_messages::CrossShardMsg,
+    dependency_analysis::WriteSetWithTxnIndex,
+    messages::{
+        AddWithCrossShardDep, ControlMsg,
+        ControlMsg::{AddCrossShardDepReq, DiscardCrossShardDepReq},
+        DiscardCrossShardDep, PartitioningResp,
     },
-    types::{ShardId, SubBlocksForShard, TxnIndex},
+    partitioning_shard::PartitioningShard,
 };
 use aptos_logger::{error, info};
-use aptos_types::transaction::analyzed_transaction::AnalyzedTransaction;
+use aptos_types::{
+    block_executor::partitioner::{ShardId, SubBlocksForShard, TxnIndex},
+    transaction::analyzed_transaction::AnalyzedTransaction,
+};
 use itertools::Itertools;
 use std::{
     collections::HashMap,
@@ -206,7 +206,7 @@ impl ShardedBlockPartitioner {
     fn collect_partition_block_response(
         &self,
     ) -> (
-        Vec,
+        Vec>,
         Vec,
         Vec>,
     ) {
@@ -234,10 +234,10 @@ impl ShardedBlockPartitioner {
         &self,
         txns_to_partition: Vec>,
         current_round_start_index: TxnIndex,
-        frozen_sub_blocks: Vec,
+        frozen_sub_blocks: Vec>,
         frozen_write_set_with_index: Arc>,
     ) -> (
-        Vec,
+        Vec>,
         Vec,
         Vec>,
     ) {
@@ -261,10 +261,10 @@ impl ShardedBlockPartitioner {
         &self,
         index_offset: usize,
         remaining_txns_vec: Vec>,
-        frozen_sub_blocks_by_shard: Vec,
+        frozen_sub_blocks_by_shard: Vec>,
         frozen_write_set_with_index: Arc>,
     ) -> (
-        Vec,
+        Vec>,
         Vec,
         Vec>,
     ) {
@@ -295,7 +295,7 @@ impl ShardedBlockPartitioner {
         &self,
         transactions: Vec,
         num_partitioning_round: usize,
-    ) -> Vec {
+    ) -> Vec> {
         let total_txns = transactions.len();
         if total_txns == 0 {
             return vec![];
@@ -305,7 +305,7 @@ impl ShardedBlockPartitioner {
         let mut txns_to_partition = self.partition_by_senders(transactions);
         let mut frozen_write_set_with_index = Arc::new(Vec::new());
         let mut current_round_start_index = 0;
-        let mut frozen_sub_blocks: Vec = vec![];
+        let mut frozen_sub_blocks: Vec> = vec![];
         for shard_id in 0..self.num_shards {
             frozen_sub_blocks.push(SubBlocksForShard::empty(shard_id))
         }
@@ -401,14 +401,16 @@ mod tests {
             create_non_conflicting_p2p_transaction, create_signed_p2p_transaction,
             generate_test_account, generate_test_account_for_address, TestAccount,
         },
-        types::{SubBlock, TxnIdxWithShardId},
     };
-    use aptos_types::transaction::analyzed_transaction::AnalyzedTransaction;
+    use aptos_types::{
+        block_executor::partitioner::{SubBlock, TxnIdxWithShardId},
+        transaction::analyzed_transaction::AnalyzedTransaction,
+    };
     use move_core_types::account_address::AccountAddress;
     use rand::{rngs::OsRng, Rng};
     use std::collections::HashMap;
 
-    fn verify_no_cross_shard_dependency(sub_blocks_for_shards: Vec) {
+    fn verify_no_cross_shard_dependency(sub_blocks_for_shards: Vec>) {
         for sub_blocks in sub_blocks_for_shards {
             for txn in sub_blocks.iter() {
                 assert_eq!(txn.cross_shard_dependencies().num_required_edges(), 0);
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/partitioning_shard.rs b/execution/block-partitioner/src/sharded_block_partitioner/partitioning_shard.rs
index 5a9efc86b945e..ebb8d83c3611a 100644
--- a/execution/block-partitioner/src/sharded_block_partitioner/partitioning_shard.rs
+++ b/execution/block-partitioner/src/sharded_block_partitioner/partitioning_shard.rs
@@ -1,16 +1,17 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
-use crate::{
-    sharded_block_partitioner::{
-        conflict_detector::CrossShardConflictDetector,
-        cross_shard_messages::{CrossShardClient, CrossShardClientInterface, CrossShardMsg},
-        dependency_analysis::{RWSet, WriteSetWithTxnIndex},
-        dependent_edges::DependentEdgeCreator,
-        messages::{AddWithCrossShardDep, ControlMsg, DiscardCrossShardDep, PartitioningResp},
-    },
-    types::{ShardId, SubBlock, TransactionWithDependencies},
+use crate::sharded_block_partitioner::{
+    conflict_detector::CrossShardConflictDetector,
+    cross_shard_messages::{CrossShardClient, CrossShardClientInterface, CrossShardMsg},
+    dependency_analysis::{RWSet, WriteSetWithTxnIndex},
+    dependent_edges::DependentEdgeCreator,
+    messages::{AddWithCrossShardDep, ControlMsg, DiscardCrossShardDep, PartitioningResp},
 };
 use aptos_logger::trace;
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+use aptos_types::block_executor::partitioner::{ShardId, SubBlock, TransactionWithDependencies};
+use aptos_types::transaction::analyzed_transaction::AnalyzedTransaction;
 use std::sync::{
     mpsc::{Receiver, Sender},
     Arc,
@@ -93,7 +94,7 @@ impl PartitioningShard {
             .into_iter()
             .zip(accepted_cross_shard_dependencies.into_iter())
             .map(|(txn, dependencies)| TransactionWithDependencies::new(txn, dependencies))
-            .collect::>();
+            .collect::>>();
 
         let mut frozen_sub_blocks = dependent_edge_creator.into_frozen_sub_blocks();
         let current_frozen_sub_block = SubBlock::new(index_offset, accepted_txns_with_dependencies);
diff --git a/execution/executor-benchmark/src/native_executor.rs b/execution/executor-benchmark/src/native_executor.rs
index 7685afa52c768..11d05fd4ce92c 100644
--- a/execution/executor-benchmark/src/native_executor.rs
+++ b/execution/executor-benchmark/src/native_executor.rs
@@ -9,11 +9,11 @@ use anyhow::Result;
 use aptos_executor::{
     block_executor::TransactionBlockExecutor, components::chunk_output::ChunkOutput,
 };
-use aptos_executor_types::ExecutableTransactions;
 use aptos_storage_interface::cached_state_view::CachedStateView;
 use aptos_types::{
     account_address::AccountAddress,
     account_config::{deposit::DepositEvent, withdraw::WithdrawEvent},
+    block_executor::partitioner::ExecutableTransactions,
     contract_event::ContractEvent,
     event::EventKey,
     state_store::state_key::StateKey,
@@ -337,7 +337,7 @@ impl NativeExecutor {
 
 impl TransactionBlockExecutor for NativeExecutor {
     fn execute_transaction_block(
-        transactions: ExecutableTransactions,
+        transactions: ExecutableTransactions,
         state_view: CachedStateView,
         _maybe_block_gas_limit: Option,
     ) -> Result {
diff --git a/execution/executor-types/src/lib.rs b/execution/executor-types/src/lib.rs
index 829987578f8c8..9055136c0d6c4 100644
--- a/execution/executor-types/src/lib.rs
+++ b/execution/executor-types/src/lib.rs
@@ -4,13 +4,13 @@
 #![forbid(unsafe_code)]
 
 use anyhow::Result;
-use aptos_block_partitioner::types::SubBlock;
 use aptos_crypto::{
     hash::{EventAccumulatorHasher, TransactionAccumulatorHasher, ACCUMULATOR_PLACEHOLDER_HASH},
     HashValue,
 };
 use aptos_scratchpad::{ProofRead, SparseMerkleTree};
 use aptos_types::{
+    block_executor::partitioner::ExecutableBlock,
     contract_event::ContractEvent,
     epoch_state::EpochState,
     ledger_info::LedgerInfoWithSignatures,
@@ -90,7 +90,7 @@ pub trait BlockExecutorTrait: Send + Sync {
     /// Executes a block.
     fn execute_block(
         &self,
-        block: ExecutableBlock,
+        block: ExecutableBlock,
         parent_block_id: HashValue,
         maybe_block_gas_limit: Option,
     ) -> Result;
@@ -127,49 +127,6 @@ pub trait BlockExecutorTrait: Send + Sync {
     fn finish(&self);
 }
 
-pub struct ExecutableBlock {
-    pub block_id: HashValue,
-    pub transactions: ExecutableTransactions,
-}
-
-impl ExecutableBlock {
-    pub fn new(block_id: HashValue, transactions: ExecutableTransactions) -> Self {
-        Self {
-            block_id,
-            transactions,
-        }
-    }
-}
-
-impl From<(HashValue, Vec)> for ExecutableBlock {
-    fn from((block_id, transactions): (HashValue, Vec)) -> Self {
-        Self::new(block_id, ExecutableTransactions::Unsharded(transactions))
-    }
-}
-
-pub enum ExecutableTransactions {
-    Unsharded(Vec),
-    Sharded(Vec),
-}
-
-impl ExecutableTransactions {
-    pub fn num_transactions(&self) -> usize {
-        match self {
-            ExecutableTransactions::Unsharded(transactions) => transactions.len(),
-            ExecutableTransactions::Sharded(sub_blocks) => sub_blocks
-                .iter()
-                .map(|sub_block| sub_block.num_txns())
-                .sum(),
-        }
-    }
-}
-
-impl From> for ExecutableTransactions {
-    fn from(txns: Vec) -> Self {
-        Self::Unsharded(txns)
-    }
-}
-
 #[derive(Clone)]
 pub enum VerifyExecutionMode {
     NoVerify,
diff --git a/execution/executor/src/block_executor.rs b/execution/executor/src/block_executor.rs
index 51374d06e6a9e..b43ac2c11325b 100644
--- a/execution/executor/src/block_executor.rs
+++ b/execution/executor/src/block_executor.rs
@@ -15,9 +15,7 @@ use crate::{
 };
 use anyhow::Result;
 use aptos_crypto::HashValue;
-use aptos_executor_types::{
-    BlockExecutorTrait, Error, ExecutableBlock, ExecutableTransactions, StateComputeResult,
-};
+use aptos_executor_types::{BlockExecutorTrait, Error, StateComputeResult};
 use aptos_infallible::RwLock;
 use aptos_logger::prelude::*;
 use aptos_scratchpad::SparseMerkleTree;
@@ -25,14 +23,19 @@ use aptos_state_view::StateViewId;
 use aptos_storage_interface::{
     async_proof_fetcher::AsyncProofFetcher, cached_state_view::CachedStateView, DbReaderWriter,
 };
-use aptos_types::{ledger_info::LedgerInfoWithSignatures, state_store::state_value::StateValue};
+use aptos_types::{
+    block_executor::partitioner::{ExecutableBlock, ExecutableTransactions},
+    ledger_info::LedgerInfoWithSignatures,
+    state_store::state_value::StateValue,
+    transaction::Transaction,
+};
 use aptos_vm::AptosVM;
 use fail::fail_point;
 use std::{marker::PhantomData, sync::Arc};
 
 pub trait TransactionBlockExecutor: Send + Sync {
     fn execute_transaction_block(
-        transactions: ExecutableTransactions,
+        transactions: ExecutableTransactions,
         state_view: CachedStateView,
         maybe_block_gas_limit: Option,
     ) -> Result;
@@ -40,7 +43,7 @@ pub trait TransactionBlockExecutor: Send + Sync {
 
 impl TransactionBlockExecutor for AptosVM {
     fn execute_transaction_block(
-        transactions: ExecutableTransactions,
+        transactions: ExecutableTransactions,
         state_view: CachedStateView,
         maybe_block_gas_limit: Option,
     ) -> Result {
@@ -104,7 +107,7 @@ where
 
     fn execute_block(
         &self,
-        block: ExecutableBlock,
+        block: ExecutableBlock,
         parent_block_id: HashValue,
         maybe_block_gas_limit: Option,
     ) -> Result {
@@ -174,7 +177,7 @@ where
 
     fn execute_block(
         &self,
-        block: ExecutableBlock,
+        block: ExecutableBlock,
         parent_block_id: HashValue,
         maybe_block_gas_limit: Option,
     ) -> Result {
diff --git a/execution/executor/src/components/chunk_output.rs b/execution/executor/src/components/chunk_output.rs
index 859eeccd0ccfc..f72b55cca7cac 100644
--- a/execution/executor/src/components/chunk_output.rs
+++ b/execution/executor/src/components/chunk_output.rs
@@ -7,7 +7,7 @@
 use crate::{components::apply_chunk_output::ApplyChunkOutput, metrics};
 use anyhow::Result;
 use aptos_crypto::HashValue;
-use aptos_executor_types::{ExecutableTransactions, ExecutedBlock, ExecutedChunk};
+use aptos_executor_types::{ExecutedBlock, ExecutedChunk};
 use aptos_infallible::Mutex;
 use aptos_logger::{sample, sample::SampleRate, trace, warn};
 use aptos_storage_interface::{
@@ -16,6 +16,7 @@ use aptos_storage_interface::{
 };
 use aptos_types::{
     account_config::CORE_CODE_ADDRESS,
+    block_executor::partitioner::ExecutableTransactions,
     transaction::{ExecutionStatus, Transaction, TransactionOutput, TransactionStatus},
 };
 use aptos_vm::{
@@ -47,7 +48,7 @@ pub struct ChunkOutput {
 
 impl ChunkOutput {
     pub fn by_transaction_execution(
-        transactions: ExecutableTransactions,
+        transactions: ExecutableTransactions,
         state_view: CachedStateView,
         maybe_block_gas_limit: Option,
     ) -> Result {
diff --git a/execution/executor/src/fuzzing.rs b/execution/executor/src/fuzzing.rs
index 3e5a0fd1b3db9..9bc051e576882 100644
--- a/execution/executor/src/fuzzing.rs
+++ b/execution/executor/src/fuzzing.rs
@@ -8,12 +8,13 @@ use crate::{
 };
 use anyhow::Result;
 use aptos_crypto::{hash::SPARSE_MERKLE_PLACEHOLDER_HASH, HashValue};
-use aptos_executor_types::{BlockExecutorTrait, ExecutableTransactions};
+use aptos_executor_types::BlockExecutorTrait;
 use aptos_state_view::StateView;
 use aptos_storage_interface::{
     cached_state_view::CachedStateView, state_delta::StateDelta, DbReader, DbReaderWriter, DbWriter,
 };
 use aptos_types::{
+    block_executor::partitioner::ExecutableTransactions,
     ledger_info::LedgerInfoWithSignatures,
     test_helpers::transaction_test_helpers::BLOCK_GAS_LIMIT,
     transaction::{Transaction, TransactionOutput, TransactionToCommit, Version},
@@ -52,7 +53,7 @@ pub struct FakeVM;
 
 impl TransactionBlockExecutor for FakeVM {
     fn execute_transaction_block(
-        transactions: ExecutableTransactions,
+        transactions: ExecutableTransactions,
         state_view: CachedStateView,
         maybe_block_gas_limit: Option,
     ) -> Result {
diff --git a/execution/executor/src/mock_vm/mod.rs b/execution/executor/src/mock_vm/mod.rs
index eeec728a7b790..eb584a375c48e 100644
--- a/execution/executor/src/mock_vm/mod.rs
+++ b/execution/executor/src/mock_vm/mod.rs
@@ -8,13 +8,13 @@ mod mock_vm_test;
 use crate::{block_executor::TransactionBlockExecutor, components::chunk_output::ChunkOutput};
 use anyhow::Result;
 use aptos_crypto::{ed25519::Ed25519PrivateKey, PrivateKey, Uniform};
-use aptos_executor_types::ExecutableTransactions;
 use aptos_state_view::StateView;
 use aptos_storage_interface::cached_state_view::CachedStateView;
 use aptos_types::{
     access_path::AccessPath,
     account_address::AccountAddress,
     account_config::CORE_CODE_ADDRESS,
+    block_executor::partitioner::ExecutableTransactions,
     chain_id::ChainId,
     contract_event::ContractEvent,
     event::EventKey,
@@ -60,7 +60,7 @@ pub struct MockVM;
 
 impl TransactionBlockExecutor for MockVM {
     fn execute_transaction_block(
-        transactions: ExecutableTransactions,
+        transactions: ExecutableTransactions,
         state_view: CachedStateView,
         maybe_block_gas_limit: Option,
     ) -> Result {
diff --git a/types/Cargo.toml b/types/Cargo.toml
index 35ca764d3b1cf..fb27effe6cddf 100644
--- a/types/Cargo.toml
+++ b/types/Cargo.toml
@@ -31,6 +31,7 @@ once_cell = { workspace = true }
 proptest = { workspace = true, optional = true }
 proptest-derive = { workspace = true, optional = true }
 rand = { workspace = true }
+rayon = { workspace = true }
 serde = { workspace = true }
 serde_bytes = { workspace = true }
 serde_json = { workspace = true }
diff --git a/types/src/block_executor/mod.rs b/types/src/block_executor/mod.rs
new file mode 100644
index 0000000000000..bd7cb7ff962fd
--- /dev/null
+++ b/types/src/block_executor/mod.rs
@@ -0,0 +1,5 @@
+// Copyright © Aptos Foundation
+// Parts of the project are originally copyright © Meta Platforms, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+pub mod partitioner;
diff --git a/execution/block-partitioner/src/types.rs b/types/src/block_executor/partitioner.rs
similarity index 75%
rename from execution/block-partitioner/src/types.rs
rename to types/src/block_executor/partitioner.rs
index 46af531c134c1..c5dd6a446c22f 100644
--- a/execution/block-partitioner/src/types.rs
+++ b/types/src/block_executor/partitioner.rs
@@ -1,7 +1,7 @@
 // Copyright © Aptos Foundation
-// SPDX-License-Identifier: Apache-2.0
 
-use aptos_types::transaction::analyzed_transaction::{AnalyzedTransaction, StorageLocation};
+use crate::transaction::{analyzed_transaction::StorageLocation, Transaction};
+use aptos_crypto::HashValue;
 use std::collections::HashMap;
 
 pub type ShardId = usize;
@@ -156,14 +156,14 @@ impl CrossShardDependencies {
 ///  | Transaction 3  | Transaction 6    | Transaction 9    |
 ///  +----------------+------------------+------------------+
 /// ```
-pub struct SubBlock {
+pub struct SubBlock {
     // This is the index of first transaction relative to the block.
     pub start_index: TxnIndex,
-    pub transactions: Vec,
+    pub transactions: Vec>,
 }
 
-impl SubBlock {
-    pub fn new(start_index: TxnIndex, transactions: Vec) -> Self {
+impl SubBlock {
+    pub fn new(start_index: TxnIndex, transactions: Vec>) -> Self {
         Self {
             start_index,
             transactions,
@@ -182,10 +182,14 @@ impl SubBlock {
         self.start_index + self.num_txns()
     }
 
-    pub fn transactions_with_deps(&self) -> &Vec {
+    pub fn transactions_with_deps(&self) -> &Vec> {
         &self.transactions
     }
 
+    pub fn into_transactions_with_deps(self) -> Vec> {
+        self.transactions
+    }
+
     pub fn add_dependent_edge(
         &mut self,
         source_index: TxnIndex,
@@ -199,19 +203,28 @@ impl SubBlock {
         source_txn.add_dependent_edge(txn_idx, storage_locations);
     }
 
-    pub fn iter(&self) -> impl Iterator {
+    pub fn iter(&self) -> impl Iterator> {
         self.transactions.iter()
     }
 }
 
+impl IntoIterator for SubBlock {
+    type IntoIter = std::vec::IntoIter>;
+    type Item = TransactionWithDependencies;
+
+    fn into_iter(self) -> Self::IntoIter {
+        self.transactions.into_iter()
+    }
+}
+
 // A set of sub blocks assigned to a shard.
 #[derive(Default)]
-pub struct SubBlocksForShard {
+pub struct SubBlocksForShard {
     pub shard_id: ShardId,
-    pub sub_blocks: Vec,
+    pub sub_blocks: Vec>,
 }
 
-impl SubBlocksForShard {
+impl SubBlocksForShard {
     pub fn empty(shard_id: ShardId) -> Self {
         Self {
             shard_id,
@@ -219,7 +232,7 @@ impl SubBlocksForShard {
         }
     }
 
-    pub fn add_sub_block(&mut self, sub_block: SubBlock) {
+    pub fn add_sub_block(&mut self, sub_block: SubBlock) {
         self.sub_blocks.push(sub_block);
     }
 
@@ -238,45 +251,43 @@ impl SubBlocksForShard {
         self.sub_blocks.is_empty()
     }
 
-    pub fn iter(&self) -> impl Iterator {
+    pub fn iter(&self) -> impl Iterator> {
         self.sub_blocks
             .iter()
             .flat_map(|sub_block| sub_block.iter())
     }
 
-    pub fn sub_block_iter(&self) -> impl Iterator {
+    pub fn sub_block_iter(&self) -> impl Iterator> {
         self.sub_blocks.iter()
     }
 
-    pub fn get_sub_block(&self, round: usize) -> Option<&SubBlock> {
+    pub fn get_sub_block(&self, round: usize) -> Option<&SubBlock> {
         self.sub_blocks.get(round)
     }
 
-    pub fn get_sub_block_mut(&mut self, round: usize) -> Option<&mut SubBlock> {
+    pub fn get_sub_block_mut(&mut self, round: usize) -> Option<&mut SubBlock> {
         self.sub_blocks.get_mut(round)
     }
 }
 
 #[derive(Debug, Clone)]
-pub struct TransactionWithDependencies {
-    pub txn: AnalyzedTransaction,
+pub struct TransactionWithDependencies {
+    pub txn: T,
     pub cross_shard_dependencies: CrossShardDependencies,
 }
 
-impl TransactionWithDependencies {
-    pub fn new(txn: AnalyzedTransaction, cross_shard_dependencies: CrossShardDependencies) -> Self {
+impl TransactionWithDependencies {
+    pub fn new(txn: T, cross_shard_dependencies: CrossShardDependencies) -> Self {
         Self {
             txn,
             cross_shard_dependencies,
         }
     }
 
-    #[cfg(test)]
-    pub fn txn(&self) -> &AnalyzedTransaction {
+    pub fn txn(&self) -> &T {
         &self.txn
     }
 
-    #[cfg(test)]
     pub fn cross_shard_dependencies(&self) -> &CrossShardDependencies {
         &self.cross_shard_dependencies
     }
@@ -290,3 +301,53 @@ impl TransactionWithDependencies {
             .add_dependent_edge(txn_idx, storage_locations);
     }
 }
+
+pub struct ExecutableBlock {
+    pub block_id: HashValue,
+    pub transactions: ExecutableTransactions,
+}
+
+impl ExecutableBlock {
+    pub fn new(block_id: HashValue, transactions: ExecutableTransactions) -> Self {
+        Self {
+            block_id,
+            transactions,
+        }
+    }
+}
+
+impl From<(HashValue, Vec)> for ExecutableBlock {
+    fn from((block_id, transactions): (HashValue, Vec)) -> Self {
+        Self::new(block_id, ExecutableTransactions::Unsharded(transactions))
+    }
+}
+
+pub enum ExecutableTransactions {
+    Unsharded(Vec),
+    Sharded(Vec>),
+}
+
+impl ExecutableTransactions {
+    pub fn num_transactions(&self) -> usize {
+        match self {
+            ExecutableTransactions::Unsharded(transactions) => transactions.len(),
+            ExecutableTransactions::Sharded(sub_blocks) => sub_blocks
+                .iter()
+                .map(|sub_block| sub_block.num_txns())
+                .sum(),
+        }
+    }
+
+    pub fn get_unsharded_transactions(&self) -> Option<&Vec> {
+        match self {
+            ExecutableTransactions::Unsharded(transactions) => Some(transactions),
+            ExecutableTransactions::Sharded(_) => None,
+        }
+    }
+}
+
+impl From> for ExecutableTransactions {
+    fn from(txns: Vec) -> Self {
+        Self::Unsharded(txns)
+    }
+}
diff --git a/types/src/lib.rs b/types/src/lib.rs
index a9fb39f4c7c50..2f408f53786ac 100644
--- a/types/src/lib.rs
+++ b/types/src/lib.rs
@@ -51,6 +51,7 @@ pub use utility_coin::*;
 
 pub mod account_view;
 pub mod aggregate_signature;
+pub mod block_executor;
 pub mod state_store;
 #[cfg(test)]
 mod unit_tests;

From 72736823e971cd69a63021536adbe38f1fad7b07 Mon Sep 17 00:00:00 2001
From: alnoki <43892045+alnoki@users.noreply.github.com>
Date: Wed, 14 Jun 2023 10:50:46 -0700
Subject: [PATCH 167/200] Correct view function mutability docs, add tip
 (#8539)

Co-authored-by: Greg Nazario 
---
 .../docs/integration/aptos-apis.md                | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/developer-docs-site/docs/integration/aptos-apis.md b/developer-docs-site/docs/integration/aptos-apis.md
index 44654d9421640..8e241b1b0bf74 100644
--- a/developer-docs-site/docs/integration/aptos-apis.md
+++ b/developer-docs-site/docs/integration/aptos-apis.md
@@ -27,12 +27,12 @@ Most integrations into the Aptos blockchain benefit from a holistic and comprehe
 Ensure the [fullnode](../nodes/deployments.md) you're communicating with is up to date. The fullnode must reach the version containing your transaction to retrieve relevant data from it. There can be latency from the fullnodes retrieving state from [validator fullnodes](../concepts/fullnodes.md), which in turn rely upon [validator nodes](../concepts/validator-nodes.md) as the source of truth.
 :::
 
-The storage service on a node employs two forms of pruning that erase data from nodes: 
+The storage service on a node employs two forms of pruning that erase data from nodes:
 
 * state
 * events, transactions, and everything else
 
-While either of these may be disabled, storing the state versions is not particularly sustainable. 
+While either of these may be disabled, storing the state versions is not particularly sustainable.
 
 Events and transactions pruning can be disabled via setting the [`enable_ledger_pruner`](https://github.com/aptos-labs/aptos-core/blob/cf0bc2e4031a843cdc0c04e70b3f7cd92666afcf/config/src/config/storage_config.rs#L141) to `false` in `storage_config.rs`. This is default behavior in Mainnet. In the near future, Aptos will provide indexers that mitigate the need to directly query from a node.
 
@@ -44,13 +44,16 @@ The REST API offers querying transactions and events in these ways:
 
 ## Reading state with the View function
 
-View functions do not modify blockchain state. A [View](https://github.com/aptos-labs/aptos-core/blob/main/api/src/view_function.rs) function and its [input](https://github.com/aptos-labs/aptos-core/blob/main/api/types/src/view.rs) can be used to read potentially complex on-chain state using Move. For example, you can evaluate who has the highest bid in an auction contract. Here are related files:
+View functions do not modify blockchain state when called from the API. A [View](https://github.com/aptos-labs/aptos-core/blob/main/api/src/view_function.rs) function and its [input](https://github.com/aptos-labs/aptos-core/blob/main/api/types/src/view.rs) can be used to read potentially complex on-chain state using Move. For example, you can evaluate who has the highest bid in an auction contract. Here are related files:
 
 * [`view_function.rs`](https://github.com/aptos-labs/aptos-core/blob/main/api/src/tests/view_function.rs) for an example
 * related [Move](https://github.com/aptos-labs/aptos-core/blob/90c33dc7a18662839cd50f3b70baece0e2dbfc71/aptos-move/framework/aptos-framework/sources/coin.move#L226) code
 * [specification](https://github.com/aptos-labs/aptos-core/blob/90c33dc7a18662839cd50f3b70baece0e2dbfc71/api/doc/spec.yaml#L8513).
 
-The View function operates like the [Aptos Simulation API](../guides/system-integrators-guide.md#testing-transactions-or-transaction-pre-execution), though with no side effects and a accessible output path. The function is immutable if tagged as `#[view]`, the compiler will confirm it so and if fail otherwise. View functions can be called via the `/view` endpoint. Calls to view functions require the module and function names along with input type parameters and values.
+The view function operates like the [Aptos Simulation API](../guides/system-integrators-guide.md#testing-transactions-or-transaction-pre-execution), though with no side effects and a accessible output path. View functions can be called via the `/view` endpoint. Calls to view functions require the module and function names along with input type parameters and values.
+
+A function does not have to be immutable to be tagged as `#[view]`, but if the function is mutable it will not result in state mutation when called from the API.
+If you want to tag a mutable function as `#[view]`, consider making it private so that it cannot be maliciously called during runtime.
 
 In order to use the View functions, you need to pass `--bytecode-version 6` to the [Aptos CLI](../tools/install-cli/index.md) when publishing the module.
 
@@ -73,13 +76,13 @@ The view function returns a list of values as a vector. By default, the results
 
 ## Exchanging and tracking coins
 
-Aptos has a standard *Coin type* define in [`coin.move`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/coin.move). Different types of coins can be represented in this type through the use of distinct structs that symbolize the type parameter or use generic for `Coin`. 
+Aptos has a standard *Coin type* define in [`coin.move`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/coin.move). Different types of coins can be represented in this type through the use of distinct structs that symbolize the type parameter or use generic for `Coin`.
 
 Coins are stored within an account under the resource `CoinStore`. At account creation, each user has the resource `CoinStore<0x1::aptos_coin::AptosCoin>` or `CoinStore`, for short. Within this resource is the Aptos coin: `Coin`.
 
 ### Transferring coins between users
 
-Coins can be transferred between users via the [`coin::transfer`](https://github.com/aptos-labs/aptos-core/blob/36a7c00b29a457469264187d8e44070b2d5391fe/aptos-move/framework/aptos-framework/sources/coin.move#L307) function for all coins and [`aptos_account::transfer`](https://github.com/aptos-labs/aptos-core/blob/88c9aab3982c246f8aa75eb2caf8c8ab1dcab491/aptos-move/framework/aptos-framework/sources/aptos_account.move#L18) for Aptos coins. The advantage of the latter function is that it creates the destination account if it does not exist. 
+Coins can be transferred between users via the [`coin::transfer`](https://github.com/aptos-labs/aptos-core/blob/36a7c00b29a457469264187d8e44070b2d5391fe/aptos-move/framework/aptos-framework/sources/coin.move#L307) function for all coins and [`aptos_account::transfer`](https://github.com/aptos-labs/aptos-core/blob/88c9aab3982c246f8aa75eb2caf8c8ab1dcab491/aptos-move/framework/aptos-framework/sources/aptos_account.move#L18) for Aptos coins. The advantage of the latter function is that it creates the destination account if it does not exist.
 
 :::caution
 It is important to note that if an account has not registered a `CoinStore` for a given `T`, then any transfer of type `T` to that account will fail.

From 454ebd25906124f441c86bde065470af486b98b3 Mon Sep 17 00:00:00 2001
From: Josh Lind 
Date: Tue, 13 Jun 2023 17:29:17 -0400
Subject: [PATCH 168/200] [Config] Default to fast sync for mainnet nodes.

---
 config/src/config/state_sync_config.rs | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/config/src/config/state_sync_config.rs b/config/src/config/state_sync_config.rs
index e24a6f8004d58..d456ab975b17b 100644
--- a/config/src/config/state_sync_config.rs
+++ b/config/src/config/state_sync_config.rs
@@ -325,11 +325,13 @@ impl ConfigOptimizer for StateSyncDriverConfig {
         let state_sync_driver_config = &mut node_config.state_sync.state_sync_driver;
         let local_driver_config_yaml = &local_config_yaml["state_sync"]["state_sync_driver"];
 
-        // Default to fast sync for all testnet nodes because testnet is old
-        // enough that pruning has kicked in, and nodes will struggle to
-        // locate all the data since genesis.
+        // Default to fast sync for all testnet and mainnet nodes
+        // because pruning has kicked in, and nodes will struggle
+        // to locate all the data since genesis.
         let mut modified_config = false;
-        if chain_id.is_testnet() && local_driver_config_yaml["bootstrapping_mode"].is_null() {
+        if (chain_id.is_testnet() || chain_id.is_mainnet())
+            && local_driver_config_yaml["bootstrapping_mode"].is_null()
+        {
             state_sync_driver_config.bootstrapping_mode = BootstrappingMode::DownloadLatestStates;
             modified_config = true;
         }
@@ -374,7 +376,7 @@ mod tests {
     use super::*;
 
     #[test]
-    fn test_optimize_bootstrapping_mode_testnet_vfn() {
+    fn test_optimize_bootstrapping_mode_devnet_vfn() {
         // Create a node config with execution mode enabled
         let mut node_config = create_execution_mode_config();
 
@@ -383,15 +385,15 @@ mod tests {
             &mut node_config,
             &serde_yaml::from_str("{}").unwrap(), // An empty local config,
             NodeType::ValidatorFullnode,
-            ChainId::testnet(),
+            ChainId::new(40), // Not mainnet or testnet
         )
         .unwrap();
         assert!(modified_config);
 
-        // Verify that the bootstrapping mode is now set to fast sync
+        // Verify that the bootstrapping mode is not changed
         assert_eq!(
             node_config.state_sync.state_sync_driver.bootstrapping_mode,
-            BootstrappingMode::DownloadLatestStates
+            BootstrappingMode::ExecuteTransactionsFromGenesis
         );
     }
 
@@ -432,10 +434,10 @@ mod tests {
         .unwrap();
         assert!(modified_config);
 
-        // Verify that the bootstrapping mode is still set to execution mode
+        // Verify that the bootstrapping mode is now set to fast sync
         assert_eq!(
             node_config.state_sync.state_sync_driver.bootstrapping_mode,
-            BootstrappingMode::ExecuteTransactionsFromGenesis
+            BootstrappingMode::DownloadLatestStates
         );
     }
 

From e6ffbaad8e6682396c8746c8813fa0b091d06dcc Mon Sep 17 00:00:00 2001
From: aldenhu 
Date: Wed, 14 Jun 2023 00:12:55 +0000
Subject: [PATCH 169/200] drop pruned blocks asynchronously

---
 .../executor/src/components/block_tree/mod.rs | 39 ++++++++++++++++---
 .../src/components/block_tree/test.rs         |  9 ++++-
 2 files changed, 41 insertions(+), 7 deletions(-)

diff --git a/execution/executor/src/components/block_tree/mod.rs b/execution/executor/src/components/block_tree/mod.rs
index 8fb05fbca301f..2f1a14fc5b9f3 100644
--- a/execution/executor/src/components/block_tree/mod.rs
+++ b/execution/executor/src/components/block_tree/mod.rs
@@ -7,7 +7,10 @@
 #[cfg(test)]
 mod test;
 
-use crate::logging::{LogEntry, LogSchema};
+use crate::{
+    logging::{LogEntry, LogSchema},
+    metrics::APTOS_EXECUTOR_OTHER_TIMERS_SECONDS,
+};
 use anyhow::{anyhow, ensure, Result};
 use aptos_consensus_types::block::Block as ConsensusBlock;
 use aptos_crypto::HashValue;
@@ -18,7 +21,10 @@ use aptos_storage_interface::DbReader;
 use aptos_types::{ledger_info::LedgerInfo, proof::definition::LeafCount};
 use std::{
     collections::{hash_map::Entry, HashMap},
-    sync::{Arc, Weak},
+    sync::{
+        mpsc::{channel, Receiver},
+        Arc, Weak,
+    },
 };
 
 pub struct Block {
@@ -226,7 +232,12 @@ impl BlockTree {
         block_lookup.fetch_or_add_block(id, ExecutedBlock::new_empty(ledger_view), None)
     }
 
-    pub fn prune(&self, ledger_info: &LedgerInfo) -> Result<()> {
+    // Set the root to be at `ledger_info`, drop blocks that are no longer descendants of the
+    // new root.
+    //
+    // Dropping happens asynchronously in another thread. A receiver is returned to the caller
+    // to wait for the dropping to fully complete (useful for tests).
+    pub fn prune(&self, ledger_info: &LedgerInfo) -> Result> {
         let committed_block_id = ledger_info.consensus_block_id();
         let last_committed_block = self.get_block(committed_block_id)?;
 
@@ -250,8 +261,26 @@ impl BlockTree {
             );
             last_committed_block
         };
-        *self.root.lock() = root;
-        Ok(())
+        let old_root = {
+            let mut root_locked = self.root.lock();
+            // send old root to async task to drop it
+            let old_root = root_locked.clone();
+            *root_locked = root;
+            old_root
+        };
+        // This should be the last reference to old root, spawning a drop to a different thread
+        // guarantees that the drop will not happen in the current thread
+        let (tx, rx) = channel::<()>();
+        rayon::spawn(move || {
+            let _timeer = APTOS_EXECUTOR_OTHER_TIMERS_SECONDS
+                .with_label_values(&["drop_old_root"])
+                .start_timer();
+            drop(old_root);
+            // Error is ignored, since the caller might not care about dropping completion and
+            // has discarded the receiver already.
+            tx.send(()).ok();
+        });
+        Ok(rx)
     }
 
     pub fn add_block(
diff --git a/execution/executor/src/components/block_tree/test.rs b/execution/executor/src/components/block_tree/test.rs
index 0aba39ca8fea2..f1c3ac195afcc 100644
--- a/execution/executor/src/components/block_tree/test.rs
+++ b/execution/executor/src/components/block_tree/test.rs
@@ -28,6 +28,7 @@ impl BlockTree {
         }
     }
 
+    #[cfg(test)]
     pub fn size(&self) -> usize {
         self.block_lookup.inner.lock().0.len()
     }
@@ -103,7 +104,11 @@ fn test_branch() {
     // if assertion fails.
     let num_blocks = block_tree.size();
     assert_eq!(num_blocks, 12);
-    block_tree.prune(&gen_ledger_info(id(9), false)).unwrap();
+    block_tree
+        .prune(&gen_ledger_info(id(9), false))
+        .unwrap()
+        .recv()
+        .unwrap();
     let num_blocks = block_tree.size();
     assert_eq!(num_blocks, 3);
     assert_eq!(block_tree.root_block().id, id(9));
@@ -113,7 +118,7 @@ fn test_branch() {
 fn test_reconfig_id_update() {
     let block_tree = create_tree();
     let ledger_info = gen_ledger_info(id(1), true);
-    block_tree.prune(&ledger_info).unwrap();
+    block_tree.prune(&ledger_info).unwrap().recv().unwrap();
     let num_blocks = block_tree.size();
     // reconfig suffix blocks are ditched
     assert_eq!(num_blocks, 1);

From 40b4a49e91edcc3bddfd1864771e073849300515 Mon Sep 17 00:00:00 2001
From: Zekun Li 
Date: Thu, 8 Jun 2023 16:44:13 -0700
Subject: [PATCH 170/200] [dag] add dag store

This commit adds basic nodes types and Dag store that handles indexing and produces links for new round.

TODO: support garbage collection
---
 consensus/src/dag/dag_store.rs      | 271 ++++++++++++++++++++++++++++
 consensus/src/dag/mod.rs            |   3 +-
 consensus/src/dag/tests/dag_test.rs |  97 ++++++++++
 consensus/src/dag/tests/mod.rs      |   1 +
 4 files changed, 371 insertions(+), 1 deletion(-)
 create mode 100644 consensus/src/dag/dag_store.rs
 create mode 100644 consensus/src/dag/tests/dag_test.rs

diff --git a/consensus/src/dag/dag_store.rs b/consensus/src/dag/dag_store.rs
new file mode 100644
index 0000000000000..e9a5cf0de067a
--- /dev/null
+++ b/consensus/src/dag/dag_store.rs
@@ -0,0 +1,271 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use anyhow::{anyhow, ensure};
+use aptos_consensus_types::common::{Author, Payload, Round};
+use aptos_crypto::{
+    hash::{CryptoHash, CryptoHasher},
+    HashValue,
+};
+use aptos_crypto_derive::CryptoHasher;
+use aptos_types::{aggregate_signature::AggregateSignature, validator_verifier::ValidatorVerifier};
+use serde::{Deserialize, Serialize};
+use std::{
+    collections::{BTreeMap, HashMap, HashSet},
+    ops::Deref,
+    sync::Arc,
+};
+
+/// Represents the metadata about the node, without payload and parents from Node
+#[derive(Clone, Serialize, Deserialize)]
+pub struct NodeMetadata {
+    epoch: u64,
+    round: Round,
+    author: Author,
+    timestamp: u64,
+    digest: HashValue,
+}
+
+/// Node representation in the DAG, parents contain 2f+1 strong links (links to previous round)
+/// plus weak links (links to lower round)
+#[derive(Clone, Serialize, Deserialize, CryptoHasher)]
+pub struct Node {
+    metadata: NodeMetadata,
+    payload: Payload,
+    parents: Vec,
+}
+
+impl Node {
+    pub fn new(
+        epoch: u64,
+        round: Round,
+        author: Author,
+        timestamp: u64,
+        payload: Payload,
+        parents: Vec,
+    ) -> Self {
+        let digest = Self::calculate_digest(epoch, round, author, timestamp, &payload, &parents);
+
+        Self {
+            metadata: NodeMetadata {
+                epoch,
+                round,
+                author,
+                timestamp,
+                digest,
+            },
+            payload,
+            parents,
+        }
+    }
+
+    /// Calculate the node digest based on all fields in the node
+    fn calculate_digest(
+        epoch: u64,
+        round: Round,
+        author: Author,
+        timestamp: u64,
+        payload: &Payload,
+        parents: &Vec,
+    ) -> HashValue {
+        #[derive(Serialize)]
+        struct NodeWithoutDigest<'a> {
+            epoch: u64,
+            round: Round,
+            author: Author,
+            timestamp: u64,
+            payload: &'a Payload,
+            parents: &'a Vec,
+        }
+
+        impl<'a> CryptoHash for NodeWithoutDigest<'a> {
+            type Hasher = NodeHasher;
+
+            fn hash(&self) -> HashValue {
+                let mut state = Self::Hasher::new();
+                let bytes = bcs::to_bytes(&self).expect("Unable to serialize node");
+                state.update(&bytes);
+                state.finish()
+            }
+        }
+
+        let node_with_out_digest = NodeWithoutDigest {
+            epoch,
+            round,
+            author,
+            timestamp,
+            payload,
+            parents,
+        };
+        node_with_out_digest.hash()
+    }
+
+    pub fn digest(&self) -> HashValue {
+        self.metadata.digest
+    }
+
+    pub fn metadata(&self) -> NodeMetadata {
+        self.metadata.clone()
+    }
+}
+
+/// Quorum signatures over the node digest
+#[derive(Clone)]
+pub struct NodeCertificate {
+    digest: HashValue,
+    signatures: AggregateSignature,
+}
+
+impl NodeCertificate {
+    pub fn new(digest: HashValue, signatures: AggregateSignature) -> Self {
+        Self { digest, signatures }
+    }
+}
+
+#[derive(Clone)]
+pub struct CertifiedNode {
+    node: Node,
+    certificate: NodeCertificate,
+}
+
+impl CertifiedNode {
+    pub fn new(node: Node, certificate: NodeCertificate) -> Self {
+        Self { node, certificate }
+    }
+}
+
+impl Deref for CertifiedNode {
+    type Target = Node;
+
+    fn deref(&self) -> &Self::Target {
+        &self.node
+    }
+}
+
+/// Data structure that stores the DAG representation, it maintains both hash based index and
+/// round based index.
+pub struct Dag {
+    nodes_by_digest: HashMap>,
+    nodes_by_round: BTreeMap>>>,
+    /// Map between peer id to vector index
+    author_to_index: HashMap,
+    /// Highest head nodes that are not linked by other nodes
+    highest_unlinked_nodes_by_author: Vec>>,
+}
+
+impl Dag {
+    pub fn new(author_to_index: HashMap, initial_round: Round) -> Self {
+        let mut nodes_by_round = BTreeMap::new();
+        let num_nodes = author_to_index.len();
+        nodes_by_round.insert(initial_round, vec![None; num_nodes]);
+        Self {
+            nodes_by_digest: HashMap::new(),
+            nodes_by_round,
+            author_to_index,
+            highest_unlinked_nodes_by_author: vec![None; num_nodes],
+        }
+    }
+
+    fn lowest_round(&self) -> Round {
+        *self
+            .nodes_by_round
+            .first_key_value()
+            .map(|(round, _)| round)
+            .unwrap_or(&0)
+    }
+
+    fn highest_round(&self) -> Round {
+        *self
+            .nodes_by_round
+            .last_key_value()
+            .map(|(round, _)| round)
+            .unwrap_or(&0)
+    }
+
+    pub fn add_node(&mut self, node: CertifiedNode) -> anyhow::Result<()> {
+        let node = Arc::new(node);
+        let index = *self
+            .author_to_index
+            .get(&node.metadata.author)
+            .ok_or_else(|| anyhow!("unknown author"))?;
+        let round = node.metadata.round;
+        ensure!(round >= self.lowest_round(), "round too low");
+        ensure!(round <= self.highest_round() + 1, "round too high");
+        for parent in &node.parents {
+            ensure!(self.exists(&parent.digest), "parent not exist");
+        }
+        ensure!(
+            self.nodes_by_digest
+                .insert(node.metadata.digest, node.clone())
+                .is_none(),
+            "duplicate node"
+        );
+        ensure!(
+            self.nodes_by_round
+                .entry(round)
+                .or_insert_with(|| vec![None; self.author_to_index.len()])[index]
+                .replace(node.clone())
+                .is_none(),
+            "equivocate node"
+        );
+        if round
+            > self.highest_unlinked_nodes_by_author[index]
+                .as_ref()
+                .map_or(0, |node| node.metadata.round)
+        {
+            self.highest_unlinked_nodes_by_author[index].replace(node);
+        }
+        Ok(())
+    }
+
+    pub fn exists(&self, digest: &HashValue) -> bool {
+        self.nodes_by_digest.contains_key(digest)
+    }
+
+    pub fn get_node(&self, digest: &HashValue) -> Option> {
+        self.nodes_by_digest.get(digest).cloned()
+    }
+
+    pub fn get_unlinked_nodes_for_new_round(
+        &self,
+        validator_verifier: &ValidatorVerifier,
+    ) -> Option> {
+        let current_round = self.highest_round();
+        let strong_link_authors =
+            self.highest_unlinked_nodes_by_author
+                .iter()
+                .filter_map(|maybe_node| {
+                    maybe_node.as_ref().and_then(|node| {
+                        if node.metadata.round == current_round {
+                            Some(&node.metadata.author)
+                        } else {
+                            None
+                        }
+                    })
+                });
+        if validator_verifier
+            .check_voting_power(strong_link_authors)
+            .is_ok()
+        {
+            Some(
+                self.highest_unlinked_nodes_by_author
+                    .iter()
+                    .filter_map(|maybe_node| maybe_node.as_ref().map(|node| node.metadata.clone()))
+                    .collect(),
+            )
+        } else {
+            None
+        }
+    }
+
+    pub fn mark_nodes_linked(&mut self, node_metadata: &[NodeMetadata]) {
+        let digests: HashSet<_> = node_metadata.iter().map(|node| node.digest).collect();
+        for maybe_node in &mut self.highest_unlinked_nodes_by_author {
+            if let Some(node) = maybe_node {
+                if digests.contains(&node.metadata.digest) {
+                    *maybe_node = None;
+                }
+            }
+        }
+    }
+}
diff --git a/consensus/src/dag/mod.rs b/consensus/src/dag/mod.rs
index 1184204db0b9a..3108eeeaec6fc 100644
--- a/consensus/src/dag/mod.rs
+++ b/consensus/src/dag/mod.rs
@@ -1,8 +1,9 @@
 // Copyright © Aptos Foundation
 // Parts of the project are originally copyright © Meta Platforms, Inc.
 // SPDX-License-Identifier: Apache-2.0
+#![allow(dead_code)]
 
-#[allow(dead_code)]
+mod dag_store;
 mod reliable_broadcast;
 #[cfg(test)]
 mod tests;
diff --git a/consensus/src/dag/tests/dag_test.rs b/consensus/src/dag/tests/dag_test.rs
new file mode 100644
index 0000000000000..e03b45f9449c4
--- /dev/null
+++ b/consensus/src/dag/tests/dag_test.rs
@@ -0,0 +1,97 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::dag::dag_store::{CertifiedNode, Dag, Node, NodeCertificate, NodeMetadata};
+use aptos_consensus_types::common::{Author, Payload, Round};
+use aptos_types::{
+    aggregate_signature::AggregateSignature, validator_verifier::random_validator_verifier,
+};
+
+#[test]
+fn test_dag_insertion_succeed() {
+    let (signers, validator_verifier) = random_validator_verifier(4, None, false);
+    let author_to_index = validator_verifier.address_to_validator_index().clone();
+    let mut dag = Dag::new(author_to_index, 0);
+
+    // Round 1 - nodes 0, 1, 2 links to vec![]
+    for signer in &signers[0..3] {
+        let node = new_node(1, signer.author(), vec![]);
+        assert!(dag.add_node(node).is_ok());
+    }
+    let parents = dag
+        .get_unlinked_nodes_for_new_round(&validator_verifier)
+        .unwrap();
+
+    // Round 2 nodes 0, 1, 2 links to 0, 1, 2
+    for signer in &signers[0..3] {
+        let node = new_node(2, signer.author(), parents.clone());
+        assert!(dag.add_node(node).is_ok());
+    }
+
+    let slow_node = new_node(1, signers[3].author(), vec![]);
+    assert!(dag.add_node(slow_node).is_ok());
+
+    // Round 3 nodes 1, 2 links to 0, 1, 2, 3 (weak)
+    let parents = dag
+        .get_unlinked_nodes_for_new_round(&validator_verifier)
+        .unwrap();
+    assert_eq!(parents.len(), 4);
+
+    dag.mark_nodes_linked(&parents);
+    assert!(dag
+        .get_unlinked_nodes_for_new_round(&validator_verifier)
+        .is_none());
+
+    for signer in &signers[1..3] {
+        let node = new_node(3, signer.author(), parents.clone());
+        assert!(dag.add_node(node).is_ok());
+    }
+
+    // not enough strong links
+    assert!(dag
+        .get_unlinked_nodes_for_new_round(&validator_verifier)
+        .is_none());
+}
+
+#[test]
+fn test_dag_insertion_failure() {
+    let (signers, validator_verifier) = random_validator_verifier(4, None, false);
+    let author_to_index = validator_verifier.address_to_validator_index().clone();
+    let mut dag = Dag::new(author_to_index, 0);
+
+    // Round 1 - nodes 0, 1, 2 links to vec![]
+    for signer in &signers[0..3] {
+        let node = new_node(1, signer.author(), vec![]);
+        assert!(dag.add_node(node.clone()).is_ok());
+        // duplicate node
+        assert!(dag.add_node(node).is_err());
+    }
+
+    let missing_node = new_node(1, signers[3].author(), vec![]);
+    let mut parents = dag
+        .get_unlinked_nodes_for_new_round(&validator_verifier)
+        .unwrap();
+    parents.push(missing_node.metadata());
+
+    let node = new_node(2, signers[0].author(), parents.clone());
+    // parents not exist
+    assert!(dag.add_node(node).is_err());
+
+    let node = new_node(3, signers[0].author(), vec![]);
+    // round too high
+    assert!(dag.add_node(node).is_err());
+
+    let node = new_node(2, signers[0].author(), parents[0..3].to_vec());
+    assert!(dag.add_node(node).is_ok());
+    let node = new_node(2, signers[0].author(), vec![]);
+    assert!(dag.add_node(node).is_err());
+}
+
+fn new_node(round: Round, author: Author, parents: Vec) -> CertifiedNode {
+    let node = Node::new(1, round, author, 0, Payload::empty(false), parents);
+    let digest = node.digest();
+    CertifiedNode::new(
+        node,
+        NodeCertificate::new(digest, AggregateSignature::empty()),
+    )
+}
diff --git a/consensus/src/dag/tests/mod.rs b/consensus/src/dag/tests/mod.rs
index 2ab720ad81960..c5254238605a4 100644
--- a/consensus/src/dag/tests/mod.rs
+++ b/consensus/src/dag/tests/mod.rs
@@ -1,4 +1,5 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
+mod dag_test;
 mod reliable_broadcast_tests;

From 456939d16ad188f4bbd73772521126b480edb05d Mon Sep 17 00:00:00 2001
From: igor-aptos <110557261+igor-aptos@users.noreply.github.com>
Date: Wed, 14 Jun 2023 14:28:59 -0700
Subject: [PATCH 171/200] Tune run-forge-realistic-env-load-sweep forge test
 (#8651)

and add expired/failed_submission to success criteria

based on
https://github.com/aptos-labs/aptos-core/actions/runs/5253448203/jobs/9490834445
---
 testsuite/forge-cli/src/main.rs         |  6 +-
 testsuite/forge/src/success_criteria.rs | 73 +++++++++++++++++++++++--
 2 files changed, 73 insertions(+), 6 deletions(-)

diff --git a/testsuite/forge-cli/src/main.rs b/testsuite/forge-cli/src/main.rs
index d6dd38b9d4124..2c73b25f6621d 100644
--- a/testsuite/forge-cli/src/main.rs
+++ b/testsuite/forge-cli/src/main.rs
@@ -778,12 +778,14 @@ fn realistic_env_load_sweep_test() -> ForgeConfig {
                     (9, 1.5, 3.),
                     (95, 1.5, 3.),
                     (950, 2., 3.),
-                    (2900, 2.5, 4.),
-                    (4900, 3., 5.),
+                    (2750, 2.5, 4.),
+                    (4600, 3., 5.),
                 ]
                 .into_iter()
                 .map(|(min_tps, max_lat_p50, max_lat_p99)| {
                     SuccessCriteria::new(min_tps)
+                        .add_max_expired_tps(0)
+                        .add_max_failed_submission_tps(0)
                         .add_latency_threshold(max_lat_p50, LatencyType::P50)
                         .add_latency_threshold(max_lat_p99, LatencyType::P99)
                 })
diff --git a/testsuite/forge/src/success_criteria.rs b/testsuite/forge/src/success_criteria.rs
index e4683e4f9c443..51ce299e180d4 100644
--- a/testsuite/forge/src/success_criteria.rs
+++ b/testsuite/forge/src/success_criteria.rs
@@ -28,6 +28,7 @@ pub struct SuccessCriteria {
     latency_thresholds: Vec<(Duration, LatencyType)>,
     check_no_restarts: bool,
     max_expired_tps: Option,
+    max_failed_submission_tps: Option,
     wait_for_all_nodes_to_catchup: Option,
     // Maximum amount of CPU cores and memory bytes used by the nodes.
     system_metrics_threshold: Option,
@@ -41,6 +42,7 @@ impl SuccessCriteria {
             latency_thresholds: Vec::new(),
             check_no_restarts: false,
             max_expired_tps: None,
+            max_failed_submission_tps: None,
             wait_for_all_nodes_to_catchup: None,
             system_metrics_threshold: None,
             chain_progress_check: None,
@@ -57,6 +59,11 @@ impl SuccessCriteria {
         self
     }
 
+    pub fn add_max_failed_submission_tps(mut self, max_failed_submission_tps: usize) -> Self {
+        self.max_failed_submission_tps = Some(max_failed_submission_tps);
+        self
+    }
+
     pub fn add_wait_for_catchup_s(mut self, duration_secs: u64) -> Self {
         self.wait_for_all_nodes_to_catchup = Some(Duration::from_secs(duration_secs));
         self
@@ -91,8 +98,10 @@ impl SuccessCriteriaChecker {
         let traffic_name_addition = traffic_name
             .map(|n| format!(" for {}", n))
             .unwrap_or_else(|| "".to_string());
-        Self::check_tps(
+        Self::check_throughput(
             success_criteria.min_avg_tps,
+            success_criteria.max_expired_tps,
+            success_criteria.max_failed_submission_tps,
             stats_rate,
             &traffic_name_addition,
         )?;
@@ -122,9 +131,10 @@ impl SuccessCriteriaChecker {
         );
         let stats_rate = stats.rate();
 
-        Self::check_tps(success_criteria.min_avg_tps, &stats_rate, &"".to_string())?;
-        Self::check_latency(
-            &success_criteria.latency_thresholds,
+        Self::check_throughput(
+            success_criteria.min_avg_tps,
+            success_criteria.max_expired_tps,
+            success_criteria.max_failed_submission_tps,
             &stats_rate,
             &"".to_string(),
         )?;
@@ -291,6 +301,61 @@ impl SuccessCriteriaChecker {
         }
     }
 
+    fn check_max_value(
+        max_config: Option,
+        stats_rate: &TxnStatsRate,
+        value: u64,
+        value_desc: &str,
+        traffic_name_addition: &String,
+    ) -> anyhow::Result<()> {
+        if let Some(max) = max_config {
+            if value > max as u64 {
+                bail!(
+                    "{} requirement{} failed. {} TPS: average {}, maximum requirement {}. Full stats: {}",
+                    value_desc,
+                    traffic_name_addition,
+                    value_desc,
+                    value,
+                    max,
+                    stats_rate,
+                )
+            } else {
+                println!(
+                    "{} TPS is {} and is below max limit of {}",
+                    value_desc, value, max
+                );
+                Ok(())
+            }
+        } else {
+            Ok(())
+        }
+    }
+
+    pub fn check_throughput(
+        min_avg_tps: usize,
+        max_expired_config: Option,
+        max_failed_submission_config: Option,
+        stats_rate: &TxnStatsRate,
+        traffic_name_addition: &String,
+    ) -> anyhow::Result<()> {
+        Self::check_tps(min_avg_tps, stats_rate, traffic_name_addition)?;
+        Self::check_max_value(
+            max_expired_config,
+            stats_rate,
+            stats_rate.expired,
+            "expired",
+            traffic_name_addition,
+        )?;
+        Self::check_max_value(
+            max_failed_submission_config,
+            stats_rate,
+            stats_rate.failed_submission,
+            "submission",
+            traffic_name_addition,
+        )?;
+        Ok(())
+    }
+
     pub fn check_latency(
         latency_thresholds: &[(Duration, LatencyType)],
         stats_rate: &TxnStatsRate,

From 42e7c40e72afd01bb0728b3d1384f553b999ba15 Mon Sep 17 00:00:00 2001
From: Guoteng Rao <3603304+grao1991@users.noreply.github.com>
Date: Wed, 14 Jun 2023 16:08:25 -0700
Subject: [PATCH 172/200] [Storage] Reorganize calculation and commit tasks in
 save_transactions/save_transaction_block. (#8664)

---
 storage/aptosdb/src/ledger_store/mod.rs |  39 +-
 storage/aptosdb/src/lib.rs              | 531 +++++++++++++-----------
 testsuite/single_node_performance.py    |   6 +-
 3 files changed, 318 insertions(+), 258 deletions(-)

diff --git a/storage/aptosdb/src/ledger_store/mod.rs b/storage/aptosdb/src/ledger_store/mod.rs
index e471f0e801e99..2df2accce408b 100644
--- a/storage/aptosdb/src/ledger_store/mod.rs
+++ b/storage/aptosdb/src/ledger_store/mod.rs
@@ -29,11 +29,11 @@ use aptos_types::{
         definition::LeafCount, position::Position, AccumulatorConsistencyProof,
         TransactionAccumulatorProof, TransactionAccumulatorRangeProof, TransactionInfoWithProof,
     },
-    transaction::{TransactionInfo, Version},
+    transaction::{TransactionInfo, TransactionToCommit, Version},
 };
 use arc_swap::ArcSwap;
 use itertools::Itertools;
-use std::{ops::Deref, sync::Arc};
+use std::{borrow::Borrow, ops::Deref, sync::Arc};
 
 #[derive(Debug)]
 pub struct LedgerStore {
@@ -288,7 +288,8 @@ impl LedgerStore {
         &self,
         first_version: u64,
         txn_infos: &[TransactionInfo],
-        // TODO(grao): Consider split this function to two functions.
+        // TODO(grao): Consider remove this function and migrate all callers to use the two functions
+        // below.
         transaction_info_batch: &SchemaBatch,
         transaction_accumulator_batch: &SchemaBatch,
     ) -> Result {
@@ -312,6 +313,38 @@ impl LedgerStore {
         Ok(root_hash)
     }
 
+    pub fn put_transaction_accumulator(
+        &self,
+        first_version: Version,
+        txns_to_commit: &[impl Borrow],
+        transaction_accumulator_batch: &SchemaBatch,
+    ) -> Result {
+        let txn_hashes: Vec<_> = txns_to_commit
+            .iter()
+            .map(|t| t.borrow().transaction_info().hash())
+            .collect();
+
+        let (root_hash, writes) = Accumulator::append(
+            self,
+            first_version, /* num_existing_leaves */
+            &txn_hashes,
+        )?;
+        writes.iter().try_for_each(|(pos, hash)| {
+            transaction_accumulator_batch.put::(pos, hash)
+        })?;
+
+        Ok(root_hash)
+    }
+
+    pub fn put_transaction_info(
+        &self,
+        version: Version,
+        transaction_info: &TransactionInfo,
+        transaction_info_batch: &SchemaBatch,
+    ) -> Result<()> {
+        transaction_info_batch.put::(&version, transaction_info)
+    }
+
     /// Write `ledger_info_with_sigs` to `batch`.
     pub fn put_ledger_info(
         &self,
diff --git a/storage/aptosdb/src/lib.rs b/storage/aptosdb/src/lib.rs
index 50885c6c22a6b..786cc4099a704 100644
--- a/storage/aptosdb/src/lib.rs
+++ b/storage/aptosdb/src/lib.rs
@@ -74,7 +74,7 @@ use aptos_config::config::{
 use aptos_config::config::{
     BUFFERED_STATE_TARGET_ITEMS, DEFAULT_MAX_NUM_NODES_PER_LRU_CACHE_SHARD,
 };
-use aptos_crypto::hash::HashValue;
+use aptos_crypto::HashValue;
 use aptos_db_indexer::Indexer;
 use aptos_infallible::Mutex;
 use aptos_logger::prelude::*;
@@ -115,7 +115,6 @@ use aptos_types::{
 };
 use aptos_vm::data_cache::AsMoveResolver;
 use arr_macro::arr;
-use itertools::zip_eq;
 use move_resource_viewer::MoveValueAnnotator;
 use once_cell::sync::Lazy;
 use rayon::prelude::*;
@@ -277,16 +276,6 @@ impl Drop for RocksdbPropertyReporter {
     }
 }
 
-#[derive(Default)]
-struct LedgerSchemaBatches {
-    ledger_metadata_batch: SchemaBatch,
-    event_batch: SchemaBatch,
-    transaction_batch: SchemaBatch,
-    transaction_info_batch: SchemaBatch,
-    transaction_accumulator_batch: SchemaBatch,
-    write_set_batch: SchemaBatch,
-}
-
 /// This holds a handle to the underlying DB responsible for physical storage and provides APIs for
 /// access to the core Aptos data structures.
 pub struct AptosDB {
@@ -800,137 +789,6 @@ impl AptosDB {
         Ok(events_with_version)
     }
 
-    fn save_ledger_info(
-        &self,
-        new_root_hash: HashValue,
-        ledger_info_with_sigs: Option<&LedgerInfoWithSignatures>,
-        ledger_batch: &SchemaBatch,
-    ) -> Result<()> {
-        // If expected ledger info is provided, verify result root hash and save the ledger info.
-        if let Some(x) = ledger_info_with_sigs {
-            let expected_root_hash = x.ledger_info().transaction_accumulator_hash();
-            ensure!(
-                new_root_hash == expected_root_hash,
-                "Root hash calculated doesn't match expected. {:?} vs {:?}",
-                new_root_hash,
-                expected_root_hash,
-            );
-            let current_epoch = self
-                .ledger_store
-                .get_latest_ledger_info_option()
-                .map_or(0, |li| li.ledger_info().next_block_epoch());
-            ensure!(
-                x.ledger_info().epoch() == current_epoch,
-                "Gap in epoch history. Trying to put in LedgerInfo in epoch: {}, current epoch: {}",
-                x.ledger_info().epoch(),
-                current_epoch,
-            );
-
-            self.ledger_store.put_ledger_info(x, ledger_batch)?;
-        }
-        Ok(())
-    }
-
-    fn save_transactions_impl(
-        &self,
-        txns_to_commit: &[impl Borrow + Sync],
-        first_version: u64,
-        expected_state_db_usage: StateStorageUsage,
-        sharded_state_cache: Option<&ShardedStateCache>,
-    ) -> Result<(LedgerSchemaBatches, ShardedStateKvSchemaBatch, HashValue)> {
-        let _timer = OTHER_TIMERS_SECONDS
-            .with_label_values(&["save_transactions_impl"])
-            .start_timer();
-
-        let ledger_schema_batches = LedgerSchemaBatches::default();
-
-        let sharded_state_kv_batches = new_sharded_kv_schema_batch();
-
-        let last_version = first_version + txns_to_commit.len() as u64 - 1;
-
-        let new_root_hash = thread::scope(|s| {
-            let t0 = s.spawn(|| {
-                // Account state updates.
-                let _timer = OTHER_TIMERS_SECONDS
-                    .with_label_values(&["save_transactions_state"])
-                    .start_timer();
-
-                let state_updates_vec = txns_to_commit
-                    .iter()
-                    .map(|txn_to_commit| txn_to_commit.borrow().state_updates())
-                    .collect::>();
-
-                // TODO(grao): Make state_store take sharded state updates.
-                self.state_store.put_value_sets(
-                    state_updates_vec,
-                    first_version,
-                    expected_state_db_usage,
-                    sharded_state_cache,
-                    &ledger_schema_batches.ledger_metadata_batch,
-                    &sharded_state_kv_batches,
-                )
-            });
-
-            let t1 = s.spawn(|| {
-                // Event updates. Gather event accumulator root hashes.
-                let _timer = OTHER_TIMERS_SECONDS
-                    .with_label_values(&["save_transactions_events"])
-                    .start_timer();
-                zip_eq(first_version..=last_version, txns_to_commit)
-                    .map(|(ver, txn_to_commit)| {
-                        self.event_store.put_events(
-                            ver,
-                            txn_to_commit.borrow().events(),
-                            &ledger_schema_batches.event_batch,
-                        )
-                    })
-                    .collect::>>()
-            });
-
-            let t2 = s.spawn(|| {
-                let _timer = OTHER_TIMERS_SECONDS
-                    .with_label_values(&["save_transactions_txn_infos"])
-                    .start_timer();
-                zip_eq(first_version..=last_version, txns_to_commit).try_for_each(
-                    |(ver, txn_to_commit)| {
-                        // Transaction updates. Gather transaction hashes.
-                        self.transaction_store.put_transaction(
-                            ver,
-                            txn_to_commit.borrow().transaction(),
-                            &ledger_schema_batches.transaction_batch,
-                        )?;
-                        self.transaction_store.put_write_set(
-                            ver,
-                            txn_to_commit.borrow().write_set(),
-                            &ledger_schema_batches.write_set_batch,
-                        )
-                    },
-                )?;
-                // Transaction accumulator updates. Get result root hash.
-                let txn_infos: Vec<_> = txns_to_commit
-                    .iter()
-                    .map(|t| t.borrow().transaction_info())
-                    .cloned()
-                    .collect();
-                self.ledger_store.put_transaction_infos(
-                    first_version,
-                    &txn_infos,
-                    &ledger_schema_batches.transaction_info_batch,
-                    &ledger_schema_batches.transaction_accumulator_batch,
-                )
-            });
-            t0.join().unwrap()?;
-            t1.join().unwrap()?;
-            t2.join().unwrap()
-        });
-
-        Ok((
-            ledger_schema_batches,
-            sharded_state_kv_batches,
-            new_root_hash?,
-        ))
-    }
-
     fn get_table_info_option(&self, handle: TableHandle) -> Result> {
         match &self.indexer {
             Some(indexer) => indexer.get_table_info(handle),
@@ -948,6 +806,9 @@ impl AptosDB {
         ledger_info_with_sigs: Option<&LedgerInfoWithSignatures>,
         latest_in_memory_state: &StateDelta,
     ) -> Result<()> {
+        let _timer = OTHER_TIMERS_SECONDS
+            .with_label_values(&["save_transactions_validation"])
+            .start_timer();
         let buffered_state = self.state_store.buffered_state().lock();
         ensure!(
             base_state_version == buffered_state.current_state().base_version,
@@ -1006,100 +867,278 @@ impl AptosDB {
         Ok(())
     }
 
-    fn commit_ledger_and_state_kv_db(
+    fn calculate_and_commit_ledger_and_state_kv(
         &self,
-        last_version: Version,
-        ledger_schema_batches: LedgerSchemaBatches,
-        sharded_state_kv_batches: ShardedStateKvSchemaBatch,
-        new_root_hash: HashValue,
-        ledger_info_with_sigs: Option<&LedgerInfoWithSignatures>,
+        txns_to_commit: &[impl Borrow + Sync],
+        first_version: Version,
+        expected_state_db_usage: StateStorageUsage,
+        sharded_state_cache: Option<&ShardedStateCache>,
+    ) -> Result {
+        let new_root_hash = thread::scope(|s| {
+            let _timer = OTHER_TIMERS_SECONDS
+                .with_label_values(&["save_transactions__work"])
+                .start_timer();
+            // TODO(grao): Write progress for each of the following databases, and handle the
+            // inconsistency at the startup time.
+            let t0 = s.spawn(|| self.commit_events(txns_to_commit, first_version));
+            let t1 = s.spawn(|| self.commit_write_sets(txns_to_commit, first_version));
+            let t2 = s.spawn(|| self.commit_transactions(txns_to_commit, first_version));
+            let t3 = s.spawn(|| {
+                self.commit_state_kv_and_ledger_metadata(
+                    txns_to_commit,
+                    first_version,
+                    expected_state_db_usage,
+                    sharded_state_cache,
+                )
+            });
+            let t4 = s.spawn(|| self.commit_transaction_infos(txns_to_commit, first_version));
+            let t5 = s.spawn(|| self.commit_transaction_accumulator(txns_to_commit, first_version));
+            // TODO(grao): Consider propagating the error instead of panic, if necessary.
+            t0.join().unwrap()?;
+            t1.join().unwrap()?;
+            t2.join().unwrap()?;
+            t3.join().unwrap()?;
+            t4.join().unwrap()?;
+            t5.join().unwrap()
+        })?;
+
+        Ok(new_root_hash)
+    }
+
+    fn commit_state_kv_and_ledger_metadata(
+        &self,
+        txns_to_commit: &[impl Borrow + Sync],
+        first_version: Version,
+        expected_state_db_usage: StateStorageUsage,
+        sharded_state_cache: Option<&ShardedStateCache>,
     ) -> Result<()> {
-        // Commit multiple batches for different DBs in parallel, then write the overall
-        // progress.
         let _timer = OTHER_TIMERS_SECONDS
-            .with_label_values(&["save_transactions_commit"])
+            .with_label_values(&["commit_state_kv_and_ledger_metadata"])
             .start_timer();
+        let state_updates_vec = txns_to_commit
+            .iter()
+            .map(|txn_to_commit| txn_to_commit.borrow().state_updates())
+            .collect::>();
 
-        COMMIT_POOL.scope(|s| {
-            // TODO(grao): Consider propagating the error instead of panic, if necessary.
-            s.spawn(|_| {
-                let _timer = OTHER_TIMERS_SECONDS
-                    .with_label_values(&["save_transactions_commit___state_kv_commit"])
-                    .start_timer();
-                self.state_kv_db
-                    .commit(last_version, sharded_state_kv_batches)
-                    .unwrap();
-            });
-            s.spawn(|_| {
-                let _timer = OTHER_TIMERS_SECONDS
-                    .with_label_values(&["save_transactions_commit___ledger_metadata_commit"])
-                    .start_timer();
-                ledger_schema_batches
-                    .ledger_metadata_batch
-                    .put::(
-                        &DbMetadataKey::LedgerCommitProgress,
-                        &DbMetadataValue::Version(last_version),
-                    )
-                    .unwrap();
-                self.ledger_db
-                    .metadata_db()
-                    .write_schemas(ledger_schema_batches.ledger_metadata_batch)
-                    .unwrap();
-            });
+        let ledger_metadata_batch = SchemaBatch::new();
+        let sharded_state_kv_batches = new_sharded_kv_schema_batch();
 
-            // TODO(grao): Write progress for each of the following databases, and handle the
-            // inconsistency at the startup time.
-            s.spawn(|_| {
-                let _timer = OTHER_TIMERS_SECONDS
-                    .with_label_values(&["save_transactions_commit___event_commit"])
-                    .start_timer();
-                self.ledger_db
-                    .event_db()
-                    .write_schemas(ledger_schema_batches.event_batch)
-                    .unwrap();
-            });
-            s.spawn(|_| {
-                let _timer = OTHER_TIMERS_SECONDS
-                    .with_label_values(&["save_transactions_commit___write_set_commit"])
-                    .start_timer();
-                self.ledger_db
-                    .write_set_db()
-                    .write_schemas(ledger_schema_batches.write_set_batch)
-                    .unwrap();
-            });
-            s.spawn(|_| {
-                let _timer = OTHER_TIMERS_SECONDS
-                    .with_label_values(&["save_transactions_commit___transaction_commit"])
-                    .start_timer();
+        // TODO(grao): Make state_store take sharded state updates.
+        self.state_store.put_value_sets(
+            state_updates_vec,
+            first_version,
+            expected_state_db_usage,
+            sharded_state_cache,
+            &ledger_metadata_batch,
+            &sharded_state_kv_batches,
+        )?;
+
+        let last_version = first_version + txns_to_commit.len() as u64 - 1;
+        ledger_metadata_batch
+            .put::(
+                &DbMetadataKey::LedgerCommitProgress,
+                &DbMetadataValue::Version(last_version),
+            )
+            .unwrap();
+
+        let _timer = OTHER_TIMERS_SECONDS
+            .with_label_values(&["commit_state_kv_and_ledger_metadata___commit"])
+            .start_timer();
+        thread::scope(|s| {
+            s.spawn(|| {
                 self.ledger_db
-                    .transaction_db()
-                    .write_schemas(ledger_schema_batches.transaction_batch)
+                    .metadata_db()
+                    .write_schemas(ledger_metadata_batch)
                     .unwrap();
             });
-            s.spawn(|_| {
-                let _timer = OTHER_TIMERS_SECONDS
-                    .with_label_values(&["save_transactions_commit___transaction_info_commit"])
-                    .start_timer();
-                self.ledger_db
-                    .transaction_info_db()
-                    .write_schemas(ledger_schema_batches.transaction_info_batch)
+            s.spawn(|| {
+                self.state_kv_db
+                    .commit(last_version, sharded_state_kv_batches)
                     .unwrap();
             });
-            s.spawn(|_| {
+        });
+
+        Ok(())
+    }
+
+    fn commit_events(
+        &self,
+        txns_to_commit: &[impl Borrow + Sync],
+        first_version: Version,
+    ) -> Result<()> {
+        let _timer = OTHER_TIMERS_SECONDS
+            .with_label_values(&["commit_events"])
+            .start_timer();
+        let batch = SchemaBatch::new();
+        txns_to_commit
+            .par_iter()
+            .with_min_len(128)
+            .enumerate()
+            .try_for_each(|(i, txn_to_commit)| -> Result<()> {
+                self.event_store.put_events(
+                    first_version + i as u64,
+                    txn_to_commit.borrow().events(),
+                    &batch,
+                )?;
+
+                Ok(())
+            })?;
+        let _timer = OTHER_TIMERS_SECONDS
+            .with_label_values(&["commit_events___commit"])
+            .start_timer();
+        self.ledger_db.event_db().write_schemas(batch)
+    }
+
+    fn commit_transactions(
+        &self,
+        txns_to_commit: &[impl Borrow + Sync],
+        first_version: Version,
+    ) -> Result<()> {
+        let _timer = OTHER_TIMERS_SECONDS
+            .with_label_values(&["commit_transactions"])
+            .start_timer();
+        let chunk_size = 512;
+        txns_to_commit
+            .par_chunks(chunk_size)
+            .enumerate()
+            .try_for_each(|(chunk_index, txns_in_chunk)| -> Result<()> {
+                let batch = SchemaBatch::new();
+                let chunk_first_version = first_version + (chunk_size * chunk_index) as u64;
+                txns_in_chunk.iter().enumerate().try_for_each(
+                    |(i, txn_to_commit)| -> Result<()> {
+                        self.transaction_store.put_transaction(
+                            chunk_first_version + i as u64,
+                            txn_to_commit.borrow().transaction(),
+                            &batch,
+                        )?;
+
+                        Ok(())
+                    },
+                )?;
                 let _timer = OTHER_TIMERS_SECONDS
-                    .with_label_values(&[
-                        "save_transactions_commit___transaction_accumulator_commit",
-                    ])
+                    .with_label_values(&["commit_transactions___commit"])
                     .start_timer();
-                self.ledger_db
-                    .transaction_accumulator_db()
-                    .write_schemas(ledger_schema_batches.transaction_accumulator_batch)
-                    .unwrap();
-            });
-        });
+                self.ledger_db.transaction_db().write_schemas(batch)
+            })
+    }
+
+    fn commit_transaction_accumulator(
+        &self,
+        txns_to_commit: &[impl Borrow + Sync],
+        first_version: u64,
+    ) -> Result {
+        let _timer = OTHER_TIMERS_SECONDS
+            .with_label_values(&["commit_transaction_accumulator"])
+            .start_timer();
+
+        let batch = SchemaBatch::new();
+        let root_hash =
+            self.ledger_store
+                .put_transaction_accumulator(first_version, txns_to_commit, &batch)?;
+
+        let _timer = OTHER_TIMERS_SECONDS
+            .with_label_values(&["commit_transaction_accumulator___commit"])
+            .start_timer();
+        self.ledger_db
+            .transaction_accumulator_db()
+            .write_schemas(batch)?;
+
+        Ok(root_hash)
+    }
+
+    fn commit_transaction_infos(
+        &self,
+        txns_to_commit: &[impl Borrow + Sync],
+        first_version: u64,
+    ) -> Result<()> {
+        let _timer = OTHER_TIMERS_SECONDS
+            .with_label_values(&["commit_transaction_infos"])
+            .start_timer();
+        let batch = SchemaBatch::new();
+        txns_to_commit
+            .par_iter()
+            .with_min_len(128)
+            .enumerate()
+            .try_for_each(|(i, txn_to_commit)| -> Result<()> {
+                let version = first_version + i as u64;
+                self.ledger_store.put_transaction_info(
+                    version,
+                    txn_to_commit.borrow().transaction_info(),
+                    &batch,
+                )?;
+
+                Ok(())
+            })?;
+
+        let _timer = OTHER_TIMERS_SECONDS
+            .with_label_values(&["commit_transaction_infos___commit"])
+            .start_timer();
+        self.ledger_db.transaction_info_db().write_schemas(batch)
+    }
+
+    fn commit_write_sets(
+        &self,
+        txns_to_commit: &[impl Borrow + Sync],
+        first_version: Version,
+    ) -> Result<()> {
+        let _timer = OTHER_TIMERS_SECONDS
+            .with_label_values(&["commit_write_sets"])
+            .start_timer();
+        let batch = SchemaBatch::new();
+        txns_to_commit
+            .par_iter()
+            .with_min_len(128)
+            .enumerate()
+            .try_for_each(|(i, txn_to_commit)| -> Result<()> {
+                self.transaction_store.put_write_set(
+                    first_version + i as u64,
+                    txn_to_commit.borrow().write_set(),
+                    &batch,
+                )?;
+
+                Ok(())
+            })?;
+        let _timer = OTHER_TIMERS_SECONDS
+            .with_label_values(&["commit_write_sets___commit"])
+            .start_timer();
+        self.ledger_db.write_set_db().write_schemas(batch)
+    }
+
+    fn commit_ledger_info(
+        &self,
+        last_version: Version,
+        new_root_hash: HashValue,
+        ledger_info_with_sigs: Option<&LedgerInfoWithSignatures>,
+    ) -> Result<()> {
+        let _timer = OTHER_TIMERS_SECONDS
+            .with_label_values(&["commit_ledger_info"])
+            .start_timer();
 
         let ledger_batch = SchemaBatch::new();
-        self.save_ledger_info(new_root_hash, ledger_info_with_sigs, &ledger_batch)?;
+
+        // If expected ledger info is provided, verify result root hash and save the ledger info.
+        if let Some(x) = ledger_info_with_sigs {
+            let expected_root_hash = x.ledger_info().transaction_accumulator_hash();
+            ensure!(
+                new_root_hash == expected_root_hash,
+                "Root hash calculated doesn't match expected. {:?} vs {:?}",
+                new_root_hash,
+                expected_root_hash,
+            );
+            let current_epoch = self
+                .ledger_store
+                .get_latest_ledger_info_option()
+                .map_or(0, |li| li.ledger_info().next_block_epoch());
+            ensure!(
+                x.ledger_info().epoch() == current_epoch,
+                "Gap in epoch history. Trying to put in LedgerInfo in epoch: {}, current epoch: {}",
+                x.ledger_info().epoch(),
+                current_epoch,
+            );
+
+            self.ledger_store.put_ledger_info(x, &ledger_batch)?;
+        }
+
         ledger_batch.put::(
             &DbMetadataKey::OverallCommitProgress,
             &DbMetadataValue::Version(last_version),
@@ -1975,24 +2014,18 @@ impl DbWriter for AptosDB {
                 &latest_in_memory_state,
             )?;
 
-            let (ledger_schema_batches, sharded_state_kv_batches, new_root_hash) = self
-                .save_transactions_impl(
-                    txns_to_commit,
-                    first_version,
-                    latest_in_memory_state.current.usage(),
-                    None,
-                )?;
+            let new_root_hash = self.calculate_and_commit_ledger_and_state_kv(
+                txns_to_commit,
+                first_version,
+                latest_in_memory_state.current.usage(),
+                None,
+            )?;
 
             {
                 let mut buffered_state = self.state_store.buffered_state().lock();
                 let last_version = first_version + txns_to_commit.len() as u64 - 1;
-                self.commit_ledger_and_state_kv_db(
-                    last_version,
-                    ledger_schema_batches,
-                    sharded_state_kv_batches,
-                    new_root_hash,
-                    ledger_info_with_sigs,
-                )?;
+
+                self.commit_ledger_info(last_version, new_root_hash, ledger_info_with_sigs)?;
 
                 self.maybe_commit_state_merkle_db(
                     &mut buffered_state,
@@ -2042,27 +2075,21 @@ impl DbWriter for AptosDB {
                 &latest_in_memory_state,
             )?;
 
-            // TODO(grao): Schedule tasks in save_transactions_impl and
-            // commit_ledger_and_state_kv_db in a different way to make them more parallelizable.
-            let (ledger_schema_batches, sharded_state_kv_batches, new_root_hash) = self
-                .save_transactions_impl(
-                    txns_to_commit,
-                    first_version,
-                    latest_in_memory_state.current.usage(),
-                    Some(sharded_state_cache),
-                )?;
+            let new_root_hash = self.calculate_and_commit_ledger_and_state_kv(
+                txns_to_commit,
+                first_version,
+                latest_in_memory_state.current.usage(),
+                Some(sharded_state_cache),
+            )?;
 
+            let _timer = OTHER_TIMERS_SECONDS
+                .with_label_values(&["save_transactions__others"])
+                .start_timer();
             {
                 let mut buffered_state = self.state_store.buffered_state().lock();
                 let last_version = first_version + txns_to_commit.len() as u64 - 1;
 
-                self.commit_ledger_and_state_kv_db(
-                    last_version,
-                    ledger_schema_batches,
-                    sharded_state_kv_batches,
-                    new_root_hash,
-                    ledger_info_with_sigs,
-                )?;
+                self.commit_ledger_info(last_version, new_root_hash, ledger_info_with_sigs)?;
 
                 if !txns_to_commit.is_empty() {
                     let _timer = OTHER_TIMERS_SECONDS
diff --git a/testsuite/single_node_performance.py b/testsuite/single_node_performance.py
index deeea5f6d4e17..62a354044c424 100755
--- a/testsuite/single_node_performance.py
+++ b/testsuite/single_node_performance.py
@@ -21,15 +21,15 @@
     ("coin-transfer", False, 1): (12600.0, True),
     ("coin-transfer", True, 1): (22100.0, True),
     ("account-generation", False, 1): (11000.0, True),
-    ("account-generation", True, 1): (17600.0, True),
+    ("account-generation", True, 1): (20000.0, True),
     # changed to not use account_pool. either recalibrate or add here to use account pool.
-    ("account-resource32-b", False, 1): (13000.0, False),
+    ("account-resource32-b", False, 1): (15000.0, False),
     ("modify-global-resource", False, 1): (3700.0, True),
     ("modify-global-resource", False, 10): (10800.0, True),
     # seems to have changed, disabling as land_blocking, until recalibrated
     ("publish-package", False, 1): (159.0, False),
     ("batch100-transfer", False, 1): (350, True),
-    ("batch100-transfer", True, 1): (553, True),
+    ("batch100-transfer", True, 1): (630, True),
     ("token-v1ft-mint-and-transfer", False, 1): (1650.0, True),
     ("token-v1ft-mint-and-transfer", False, 20): (7100.0, True),
     ("token-v1nft-mint-and-transfer-sequential", False, 1): (1100.0, True),

From 68aff2a74aa76514dfc333ddabaf4dd23209047f Mon Sep 17 00:00:00 2001
From: danielx <66756900+danielxiangzl@users.noreply.github.com>
Date: Wed, 14 Jun 2023 17:11:24 -0700
Subject: [PATCH 173/200] [BlockSTM] Remove Commit Lock (#8665)

---
 aptos-move/block-executor/src/executor.rs     | 31 +++++++++++++++++--
 .../src/txn_last_input_output.rs              |  7 -----
 2 files changed, 28 insertions(+), 10 deletions(-)

diff --git a/aptos-move/block-executor/src/executor.rs b/aptos-move/block-executor/src/executor.rs
index 14bc066de9153..17bce0f8b4d12 100644
--- a/aptos-move/block-executor/src/executor.rs
+++ b/aptos-move/block-executor/src/executor.rs
@@ -37,6 +37,31 @@ use std::{
     },
 };
 
+struct CommitGuard<'a> {
+    post_commit_txs: &'a Vec>,
+    worker_idx: usize,
+    txn_idx: u32,
+}
+
+impl<'a> CommitGuard<'a> {
+    fn new(post_commit_txs: &'a Vec>, worker_idx: usize, txn_idx: u32) -> Self {
+        Self {
+            post_commit_txs,
+            worker_idx,
+            txn_idx,
+        }
+    }
+}
+
+impl<'a> Drop for CommitGuard<'a> {
+    fn drop(&mut self) {
+        // Send the committed txn to the Worker thread.
+        self.post_commit_txs[self.worker_idx]
+            .send(self.txn_idx)
+            .expect("Worker must be available");
+    }
+}
+
 #[derive(Debug)]
 enum CommitRole {
     Coordinator(Vec>),
@@ -230,9 +255,9 @@ where
         last_input_output: &TxnLastInputOutput,
     ) {
         while let Some(txn_idx) = scheduler.try_commit() {
-            post_commit_txs[*worker_idx]
-                .send(txn_idx)
-                .expect("Worker must be available");
+            // Create a CommitGuard to ensure Coordinator sends the committed txn index to Worker.
+            let _commit_guard: CommitGuard =
+                CommitGuard::new(post_commit_txs, *worker_idx, txn_idx);
             // Iterate round robin over workers to do commit_hook.
             *worker_idx = (*worker_idx + 1) % post_commit_txs.len();
 
diff --git a/aptos-move/block-executor/src/txn_last_input_output.rs b/aptos-move/block-executor/src/txn_last_input_output.rs
index 30fc77f57fb50..4e4e6f37e151e 100644
--- a/aptos-move/block-executor/src/txn_last_input_output.rs
+++ b/aptos-move/block-executor/src/txn_last_input_output.rs
@@ -6,7 +6,6 @@ use crate::{
     task::{ExecutionStatus, Transaction, TransactionOutput},
 };
 use anyhow::anyhow;
-use aptos_infallible::Mutex;
 use aptos_mvhashmap::types::{Incarnation, TxnIndex, Version};
 use aptos_types::{access_path::AccessPath, executable::ModulePath, write_set::WriteOp};
 use arc_swap::ArcSwapOption;
@@ -130,8 +129,6 @@ pub struct TxnLastInputOutput {
     module_reads: DashSet,
 
     module_read_write_intersection: AtomicBool,
-
-    commit_locks: Vec>, // Shared locks to prevent race during commit
 }
 
 impl TxnLastInputOutput {
@@ -146,7 +143,6 @@ impl TxnLastInputO
             module_writes: DashSet::new(),
             module_reads: DashSet::new(),
             module_read_write_intersection: AtomicBool::new(false),
-            commit_locks: (0..num_txns).map(|_| Mutex::new(())).collect(),
         }
     }
 
@@ -234,7 +230,6 @@ impl TxnLastInputO
     }
 
     pub fn update_to_skip_rest(&self, txn_idx: TxnIndex) {
-        let _lock = self.commit_locks[txn_idx as usize].lock();
         if let ExecutionStatus::Success(output) = self.take_output(txn_idx) {
             self.outputs[txn_idx as usize].store(Some(Arc::new(TxnOutput {
                 output_status: ExecutionStatus::SkipRest(output),
@@ -268,7 +263,6 @@ impl TxnLastInputO
         usize,
         Box::Txn as Transaction>::Key>>,
     ) {
-        let _lock = self.commit_locks[txn_idx as usize].lock();
         let ret: (
             usize,
             Box::Txn as Transaction>::Key>>,
@@ -298,7 +292,6 @@ impl TxnLastInputO
         txn_idx: TxnIndex,
         delta_writes: Vec<(<::Txn as Transaction>::Key, WriteOp)>,
     ) {
-        let _lock = self.commit_locks[txn_idx as usize].lock();
         match &self.outputs[txn_idx as usize]
             .load_full()
             .expect("Output must exist")

From e914ed265dce966d449fcd8ead04261be6b91799 Mon Sep 17 00:00:00 2001
From: Christian Sahar <125399153+saharct@users.noreply.github.com>
Date: Wed, 14 Jun 2023 18:08:37 -0700
Subject: [PATCH 174/200] Specify that functions can return references under
 certain conditions (#8644)

* Add note that functions can return references

* Mention that inline functions can return such references
---
 developer-docs-site/docs/move/book/functions.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/developer-docs-site/docs/move/book/functions.md b/developer-docs-site/docs/move/book/functions.md
index e95d533fff145..2e19ffd90b78c 100644
--- a/developer-docs-site/docs/move/book/functions.md
+++ b/developer-docs-site/docs/move/book/functions.md
@@ -327,6 +327,10 @@ fun zero(): u64 { 0 }
 
 Here `: u64` indicates that the function's return type is `u64`.
 
+:::tip
+A function can return an immutable `&` or mutable `&mut` [reference](./references.md) if derived from an input reference. Keep in mind, this means that a function [cannot return a reference to global storage](./references.md#references-cannot-be-stored) unless it is an [inline function](#inline-functions).
+:::
+
 Using tuples, a function can return multiple values:
 
 ```move

From ad2cbfd093e0159a5a51a4011c295ceb57537183 Mon Sep 17 00:00:00 2001
From: Rustie Lin 
Date: Wed, 14 Jun 2023 23:01:47 -0700
Subject: [PATCH 175/200] [gha][docker] only push to GAR on PR; push to ECR on
 postcommit (#8599)

* Revert "Revert "[gha][docker] only push to GAR on PR; push to ECR on postcommit" (#8514)"

This reverts commit c32e9185798877da6a7da0489251c67e304d60d8.

* [forge] find latest images based on cloud

* [gha] make GCP the default target registry for docker build

Co-authored-by: Balaji Arun 

* [gha/docker] make remote TARGET_REGISTRY backwards compatible

* [testsuite] find docker images on GCP using crane

---------

Co-authored-by: Balaji Arun 
---
 .github/workflows/docker-build-test.yaml      | 11 +++
 .github/workflows/forge-stable.yaml           | 13 +++
 .github/workflows/forge-unstable.yaml         | 12 +++
 .../workflow-run-docker-rust-build.yaml       | 17 ++++
 docker/builder/docker-bake-rust-all.hcl       | 81 ++++++++++---------
 docker/builder/docker-bake-rust-all.sh        |  4 +-
 testsuite/find_latest_image.py                | 18 ++++-
 testsuite/fixtures/testMain.fixture           |  4 +
 testsuite/forge.py                            | 73 ++++++++++++-----
 testsuite/forge_test.py                       | 38 ++++++++-
 10 files changed, 204 insertions(+), 67 deletions(-)

diff --git a/.github/workflows/docker-build-test.yaml b/.github/workflows/docker-build-test.yaml
index 4f079c829e087..4ad334e77d7f1 100644
--- a/.github/workflows/docker-build-test.yaml
+++ b/.github/workflows/docker-build-test.yaml
@@ -61,6 +61,10 @@ env:
   # We use `pr-` as cache-id for PRs and simply  otherwise.
   TARGET_CACHE_ID: ${{ github.event.number && format('pr-{0}', github.event.number) || github.ref_name }}
 
+  # On PRs, only build and push to GCP
+  # On push, build and push to all remote registries
+  TARGET_REGISTRY: ${{ github.event_name == 'pull_request_target' && 'remote' || 'remote-all' }}
+
 permissions:
   contents: read
   id-token: write #required for GCP Workload Identity federation which we use to login into Google Artifact Registry
@@ -99,9 +103,11 @@ jobs:
         run: |
           echo "GIT_SHA: ${GIT_SHA}"
           echo "TARGET_CACHE_ID: ${TARGET_CACHE_ID}"
+          echo "TARGET_REGISTRY: ${TARGET_REGISTRY}"
     outputs:
       gitSha: ${{ env.GIT_SHA }}
       targetCacheId: ${{ env.TARGET_CACHE_ID }}
+      targetRegistry: ${{ env.TARGET_REGISTRY }}
 
   rust-images:
     needs: [permission-check, determine-docker-build-metadata]
@@ -112,6 +118,7 @@ jobs:
       TARGET_CACHE_ID: ${{ needs.determine-docker-build-metadata.outputs.targetCacheId }}
       PROFILE: release
       BUILD_ADDL_TESTING_IMAGES: true
+      TARGET_REGISTRY: ${{ needs.determine-docker-build-metadata.outputs.targetRegistry }}
 
   rust-images-indexer:
     needs: [permission-check, determine-docker-build-metadata]
@@ -127,6 +134,7 @@ jobs:
       PROFILE: release
       FEATURES: indexer
       BUILD_ADDL_TESTING_IMAGES: true
+      TARGET_REGISTRY: ${{ needs.determine-docker-build-metadata.outputs.targetRegistry }}
 
   rust-images-failpoints:
     needs: [permission-check, determine-docker-build-metadata]
@@ -142,6 +150,7 @@ jobs:
       PROFILE: release
       FEATURES: failpoints
       BUILD_ADDL_TESTING_IMAGES: true
+      TARGET_REGISTRY: ${{ needs.determine-docker-build-metadata.outputs.targetRegistry }}
 
   rust-images-performance:
     needs: [permission-check, determine-docker-build-metadata]
@@ -156,6 +165,7 @@ jobs:
       TARGET_CACHE_ID: ${{ needs.determine-docker-build-metadata.outputs.targetCacheId }}
       PROFILE: performance
       BUILD_ADDL_TESTING_IMAGES: true
+      TARGET_REGISTRY: ${{ needs.determine-docker-build-metadata.outputs.targetRegistry }}
 
   rust-images-consensus-only-perf-test:
     needs: [permission-check, determine-docker-build-metadata]
@@ -170,6 +180,7 @@ jobs:
       PROFILE: release
       FEATURES: consensus-only-perf-test
       BUILD_ADDL_TESTING_IMAGES: true
+      TARGET_REGISTRY: ${{ needs.determine-docker-build-metadata.outputs.targetRegistry }}
 
   sdk-release:
     needs: [permission-check, rust-images, determine-docker-build-metadata] # runs with the default release docker build variant "rust-images"
diff --git a/.github/workflows/forge-stable.yaml b/.github/workflows/forge-stable.yaml
index 475655abe3a41..6eaaef78abb7c 100644
--- a/.github/workflows/forge-stable.yaml
+++ b/.github/workflows/forge-stable.yaml
@@ -25,6 +25,7 @@ on:
   pull_request:
     paths:
       - ".github/workflows/forge-stable.yaml"
+      - "testsuite/find_latest_image.py"
   push:
     branches:
       - aptos-release-v* # the aptos release branches
@@ -75,6 +76,18 @@ jobs:
         with:
           cancel-workflow: ${{ github.event_name == 'schedule' }} # Cancel the workflow if it is scheduled on a fork
 
+      # find_latest_images.py requires docker utilities and having authenticated to internal docker image registries
+      - uses: aptos-labs/aptos-core/.github/actions/docker-setup@main
+        id: docker-setup
+        with:
+          GCP_WORKLOAD_IDENTITY_PROVIDER: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
+          GCP_SERVICE_ACCOUNT_EMAIL: ${{ secrets.GCP_SERVICE_ACCOUNT_EMAIL }}
+          EXPORT_GCP_PROJECT_VARIABLES: "false"
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          AWS_DOCKER_ARTIFACT_REPO: ${{ secrets.AWS_DOCKER_ARTIFACT_REPO }}
+          GIT_CREDENTIALS: ${{ secrets.GIT_CREDENTIALS }}
+
       - uses: ./.github/actions/python-setup
         with:
           pyproject_directory: testsuite
diff --git a/.github/workflows/forge-unstable.yaml b/.github/workflows/forge-unstable.yaml
index f7dd7e47f75f1..299318a0f23b8 100644
--- a/.github/workflows/forge-unstable.yaml
+++ b/.github/workflows/forge-unstable.yaml
@@ -69,6 +69,18 @@ jobs:
         with:
           cancel-workflow: ${{ github.event_name == 'schedule' }} # Cancel the workflow if it is scheduled on a fork
 
+      # find_latest_images.py requires docker utilities and having authenticated to internal docker image registries
+      - uses: aptos-labs/aptos-core/.github/actions/docker-setup@main
+        id: docker-setup
+        with:
+          GCP_WORKLOAD_IDENTITY_PROVIDER: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
+          GCP_SERVICE_ACCOUNT_EMAIL: ${{ secrets.GCP_SERVICE_ACCOUNT_EMAIL }}
+          EXPORT_GCP_PROJECT_VARIABLES: "false"
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          AWS_DOCKER_ARTIFACT_REPO: ${{ secrets.AWS_DOCKER_ARTIFACT_REPO }}
+          GIT_CREDENTIALS: ${{ secrets.GIT_CREDENTIALS }}
+
       - uses: ./.github/actions/python-setup
         with:
           pyproject_directory: testsuite
diff --git a/.github/workflows/workflow-run-docker-rust-build.yaml b/.github/workflows/workflow-run-docker-rust-build.yaml
index 8208263bfe427..f11a01352f60c 100644
--- a/.github/workflows/workflow-run-docker-rust-build.yaml
+++ b/.github/workflows/workflow-run-docker-rust-build.yaml
@@ -25,6 +25,12 @@ on:
         required: false
         type: boolean
         description: Whether to build additional testing images. If not specified, only the base release images will be built
+      TARGET_REGISTRY:
+        default: gcp
+        required: false
+        type: string
+        description: The target docker registry to push to
+
   workflow_dispatch:
     inputs:
       GIT_SHA:
@@ -45,6 +51,11 @@ on:
         required: false
         type: boolean
         description: Whether to build additional testing images. If not specified, only the base release images will be built
+      TARGET_REGISTRY:
+        default: gcp
+        required: false
+        type: string
+        description: The target docker registry to push to
 
 env:
   GIT_SHA: ${{ inputs.GIT_SHA }}
@@ -55,6 +66,11 @@ env:
   GCP_DOCKER_ARTIFACT_REPO: ${{ secrets.GCP_DOCKER_ARTIFACT_REPO }}
   GCP_DOCKER_ARTIFACT_REPO_US: ${{ secrets.GCP_DOCKER_ARTIFACT_REPO_US }}
   AWS_ECR_ACCOUNT_NUM: ${{ secrets.ENV_ECR_AWS_ACCOUNT_NUM }}
+  TARGET_REGISTRY: ${{ inputs.TARGET_REGISTRY }}
+
+permissions:
+  contents: read
+  id-token: write #required for GCP Workload Identity federation which we use to login into Google Artifact Registry
 
 jobs:
   rust-all:
@@ -80,3 +96,4 @@ jobs:
           FEATURES: ${{ env.FEATURES }}
           BUILD_ADDL_TESTING_IMAGES: ${{ env.BUILD_ADDL_TESTING_IMAGES }}
           GIT_CREDENTIALS: ${{ secrets.GIT_CREDENTIALS }}
+          TARGET_REGISTRY: ${{ env.TARGET_REGISTRY }}
diff --git a/docker/builder/docker-bake-rust-all.hcl b/docker/builder/docker-bake-rust-all.hcl
index 115dd2e5eaa12..651d8053aad4b 100644
--- a/docker/builder/docker-bake-rust-all.hcl
+++ b/docker/builder/docker-bake-rust-all.hcl
@@ -27,7 +27,7 @@ variable "GCP_DOCKER_ARTIFACT_REPO_US" {}
 variable "AWS_ECR_ACCOUNT_NUM" {}
 
 variable "TARGET_REGISTRY" {
-  // must be "aws" | "remote" | "local", informs which docker tags are being generated
+  // must be "gcp" | "local" | "remote-all" | "remote" (deprecated, but kept for backwards compatibility. Same as "gcp"), informs which docker tags are being generated
   default = CI == "true" ? "remote" : "local"
 }
 
@@ -74,8 +74,8 @@ target "debian-base" {
 
 target "builder-base" {
   dockerfile = "docker/builder/builder.Dockerfile"
-  target = "builder-base"
-  context = "."
+  target     = "builder-base"
+  context    = "."
   contexts = {
     rust = "docker-image://rust:1.66.1-bullseye@sha256:f72949bcf1daf8954c0e0ed8b7e10ac4c641608f6aa5f0ef7c172c49f35bd9b5"
   }
@@ -92,7 +92,7 @@ target "builder-base" {
 
 target "aptos-node-builder" {
   dockerfile = "docker/builder/builder.Dockerfile"
-  target = "aptos-node-builder"
+  target     = "aptos-node-builder"
   contexts = {
     builder-base = "target:builder-base"
   }
@@ -103,9 +103,9 @@ target "aptos-node-builder" {
 
 target "tools-builder" {
   dockerfile = "docker/builder/builder.Dockerfile"
-  target = "tools-builder"
+  target     = "tools-builder"
   contexts = {
-    builder-base =  "target:builder-base"
+    builder-base = "target:builder-base"
   }
   secret = [
     "id=GIT_CREDENTIALS"
@@ -114,8 +114,8 @@ target "tools-builder" {
 
 target "_common" {
   contexts = {
-    debian-base = "target:debian-base"
-    node-builder = "target:aptos-node-builder"
+    debian-base   = "target:debian-base"
+    node-builder  = "target:aptos-node-builder"
     tools-builder = "target:tools-builder"
   }
   labels = {
@@ -124,12 +124,12 @@ target "_common" {
     "org.label-schema.git-sha"        = "${GIT_SHA}"
   }
   args = {
-    PROFILE            = "${PROFILE}"
-    FEATURES           = "${FEATURES}"
-    GIT_SHA            = "${GIT_SHA}"
-    GIT_BRANCH         = "${GIT_BRANCH}"
-    GIT_TAG            = "${GIT_TAG}"
-    BUILD_DATE         = "${BUILD_DATE}"
+    PROFILE    = "${PROFILE}"
+    FEATURES   = "${FEATURES}"
+    GIT_SHA    = "${GIT_SHA}"
+    GIT_BRANCH = "${GIT_BRANCH}"
+    GIT_TAG    = "${GIT_TAG}"
+    BUILD_DATE = "${BUILD_DATE}"
   }
 }
 
@@ -137,7 +137,7 @@ target "validator-testing" {
   inherits   = ["_common"]
   dockerfile = "docker/builder/validator-testing.Dockerfile"
   target     = "validator-testing"
-  cache-from = generate_cache_from("validator-testing") 
+  cache-from = generate_cache_from("validator-testing")
   cache-to   = generate_cache_to("validator-testing")
   tags       = generate_tags("validator-testing")
 }
@@ -146,7 +146,7 @@ target "tools" {
   inherits   = ["_common"]
   dockerfile = "docker/builder/tools.Dockerfile"
   target     = "tools"
-  cache-from = generate_cache_from("tools") 
+  cache-from = generate_cache_from("tools")
   cache-to   = generate_cache_to("tools")
   tags       = generate_tags("tools")
 }
@@ -155,7 +155,7 @@ target "forge" {
   inherits   = ["_common"]
   dockerfile = "docker/builder/forge.Dockerfile"
   target     = "forge"
-  cache-from = generate_cache_from("forge") 
+  cache-from = generate_cache_from("forge")
   cache-to   = generate_cache_to("forge")
   tags       = generate_tags("forge")
 }
@@ -164,7 +164,7 @@ target "validator" {
   inherits   = ["_common"]
   dockerfile = "docker/builder/validator.Dockerfile"
   target     = "validator"
-  cache-from = generate_cache_from("validator") 
+  cache-from = generate_cache_from("validator")
   cache-to   = generate_cache_to("validator")
   tags       = generate_tags("validator")
 }
@@ -173,7 +173,7 @@ target "tools" {
   inherits   = ["_common"]
   dockerfile = "docker/builder/tools.Dockerfile"
   target     = "tools"
-  cache-from = generate_cache_from("tools") 
+  cache-from = generate_cache_from("tools")
   cache-to   = generate_cache_to("tools")
   tags       = generate_tags("tools")
 }
@@ -182,7 +182,7 @@ target "node-checker" {
   inherits   = ["_common"]
   dockerfile = "docker/builder/node-checker.Dockerfile"
   target     = "node-checker"
-  cache-from = generate_cache_from("node-checker") 
+  cache-from = generate_cache_from("node-checker")
   cache-to   = generate_cache_to("node-checker")
   tags       = generate_tags("node-checker")
 }
@@ -191,8 +191,8 @@ target "faucet" {
   inherits   = ["_common"]
   dockerfile = "docker/builder/faucet.Dockerfile"
   target     = "faucet"
-  cache-from = generate_cache_from("faucet") 
-  cache-to   = generate_cache_to("faucet")  
+  cache-from = generate_cache_from("faucet")
+  cache-to   = generate_cache_to("faucet")
   tags       = generate_tags("faucet")
 }
 
@@ -200,17 +200,17 @@ target "telemetry-service" {
   inherits   = ["_common"]
   dockerfile = "docker/builder/telemetry-service.Dockerfile"
   target     = "telemetry-service"
-  cache-from = generate_cache_from("telemetry-service") 
-  cache-to   = generate_cache_to("telemetry-service")  
-  tags       = generate_tags("telemetry-service")  
+  cache-from = generate_cache_from("telemetry-service")
+  cache-to   = generate_cache_to("telemetry-service")
+  tags       = generate_tags("telemetry-service")
 }
 
 target "indexer-grpc" {
-  inherits = ["_common"]
+  inherits   = ["_common"]
   dockerfile = "docker/builder/indexer-grpc.Dockerfile"
-  target   = "indexer-grpc"
-  cache-to = generate_cache_to("indexer-grpc")
-  tags     = generate_tags("indexer-grpc")
+  target     = "indexer-grpc"
+  cache-to   = generate_cache_to("indexer-grpc")
+  tags       = generate_tags("indexer-grpc")
 }
 
 function "generate_cache_from" {
@@ -224,7 +224,7 @@ function "generate_cache_from" {
 
 function "generate_cache_to" {
   params = [target]
-  result = TARGET_REGISTRY == "remote" ? [
+  result = TARGET_REGISTRY != "local" ? [
     "type=registry,ref=${GCP_DOCKER_ARTIFACT_REPO}/${target}:cache-${IMAGE_TAG_PREFIX}${NORMALIZED_GIT_BRANCH_OR_PR}",
     "type=registry,ref=${GCP_DOCKER_ARTIFACT_REPO}/${target}:cache-${IMAGE_TAG_PREFIX}${GIT_SHA}"
   ] : []
@@ -232,15 +232,22 @@ function "generate_cache_to" {
 
 function "generate_tags" {
   params = [target]
-  result = TARGET_REGISTRY == "remote" ? [
+  result = TARGET_REGISTRY == "remote-all" ? [
+    "${GCP_DOCKER_ARTIFACT_REPO}/${target}:${IMAGE_TAG_PREFIX}${GIT_SHA}",
+    "${GCP_DOCKER_ARTIFACT_REPO}/${target}:${IMAGE_TAG_PREFIX}${NORMALIZED_GIT_BRANCH_OR_PR}",
+    "${GCP_DOCKER_ARTIFACT_REPO_US}/${target}:${IMAGE_TAG_PREFIX}${GIT_SHA}",
+    "${GCP_DOCKER_ARTIFACT_REPO_US}/${target}:${IMAGE_TAG_PREFIX}${NORMALIZED_GIT_BRANCH_OR_PR}",
+    "${ecr_base}/${target}:${IMAGE_TAG_PREFIX}${GIT_SHA}",
+    "${ecr_base}/${target}:${IMAGE_TAG_PREFIX}${NORMALIZED_GIT_BRANCH_OR_PR}",
+    ] : (
+    TARGET_REGISTRY == "gcp" || TARGET_REGISTRY == "remote" ? [
       "${GCP_DOCKER_ARTIFACT_REPO}/${target}:${IMAGE_TAG_PREFIX}${GIT_SHA}",
       "${GCP_DOCKER_ARTIFACT_REPO}/${target}:${IMAGE_TAG_PREFIX}${NORMALIZED_GIT_BRANCH_OR_PR}",
       "${GCP_DOCKER_ARTIFACT_REPO_US}/${target}:${IMAGE_TAG_PREFIX}${GIT_SHA}",
       "${GCP_DOCKER_ARTIFACT_REPO_US}/${target}:${IMAGE_TAG_PREFIX}${NORMALIZED_GIT_BRANCH_OR_PR}",
-      "${ecr_base}/${target}:${IMAGE_TAG_PREFIX}${GIT_SHA}",
-      "${ecr_base}/${target}:${IMAGE_TAG_PREFIX}${NORMALIZED_GIT_BRANCH_OR_PR}",
-    ] : [
-    "aptos-core/${target}:${IMAGE_TAG_PREFIX}${GIT_SHA}-from-local",
-    "aptos-core/${target}:${IMAGE_TAG_PREFIX}from-local",
-  ]
+      ] : [ // "local" or any other value
+      "aptos-core/${target}:${IMAGE_TAG_PREFIX}${GIT_SHA}-from-local",
+      "aptos-core/${target}:${IMAGE_TAG_PREFIX}from-local",
+    ]
+  )
 }
diff --git a/docker/builder/docker-bake-rust-all.sh b/docker/builder/docker-bake-rust-all.sh
index 4589fd1fa20ad..dc62f1f02ab28 100755
--- a/docker/builder/docker-bake-rust-all.sh
+++ b/docker/builder/docker-bake-rust-all.sh
@@ -51,9 +51,9 @@ echo "To build only a specific target, run: docker/builder/docker-bake-rust-all.
 echo "E.g. docker/builder/docker-bake-rust-all.sh forge-images"
 
 if [ "$CI" == "true" ]; then
-  TARGET_REGISTRY=remote docker buildx bake --progress=plain --file docker/builder/docker-bake-rust-all.hcl --push $BUILD_TARGET
+  docker buildx bake --progress=plain --file docker/builder/docker-bake-rust-all.hcl --push $BUILD_TARGET
 else
-  TARGET_REGISTRY=local docker buildx bake --file docker/builder/docker-bake-rust-all.hcl $BUILD_TARGET
+  docker buildx bake --file docker/builder/docker-bake-rust-all.hcl $BUILD_TARGET
 fi
 
 echo "Build complete. Docker buildx cache usage:"
diff --git a/testsuite/find_latest_image.py b/testsuite/find_latest_image.py
index 4cbfac2d88cce..4ea90743a59d5 100644
--- a/testsuite/find_latest_image.py
+++ b/testsuite/find_latest_image.py
@@ -13,6 +13,7 @@
 from forge import find_recent_images, image_exists
 from test_framework.shell import LocalShell
 from test_framework.git import Git
+from test_framework.cluster import Cloud
 
 # gh output logic from determinator
 from determinator import GithubOutput, write_github_output
@@ -34,7 +35,7 @@ def main() -> None:
         "--image-name",
         "-i",
         help="The name of the image to search for",
-        default="aptos/validator-testing",
+        default="validator-testing",
     )
     parser.add_argument(
         "--variant",
@@ -44,13 +45,22 @@ def main() -> None:
         dest="variants",
         default=[],
     )
+    parser.add_argument(
+        "--cloud",
+        "-c",
+        help="The cloud to use",
+        choices=[c.value for c in Cloud],
+        default=Cloud.GCP.value,
+    )
     args = parser.parse_args()
     image_name = args.image_name
+    cloud = Cloud(args.cloud)
+    log.info(f"Using cloud: {cloud}")
 
     # If the IMAGE_TAG environment variable is set, check that
     if IMAGE_TAG_ENV in os.environ and os.environ[IMAGE_TAG_ENV]:
         image_tag = os.environ[IMAGE_TAG_ENV]
-        if not image_exists(shell, image_name, image_tag):
+        if not image_exists(shell, image_name, image_tag, cloud=cloud):
             sys.exit(1)
 
     variants = args.variants
@@ -63,7 +73,9 @@ def main() -> None:
     # Find the latest image from git history
     num_images_to_find = 1  # for the purposes of this script, this is always 1
     images = list(
-        find_recent_images(shell, git, num_images_to_find, image_name, variant_prefixes)
+        find_recent_images(
+            shell, git, num_images_to_find, image_name, variant_prefixes, cloud=cloud
+        )
     )
     log.info(f"Found latest images: {images}")
 
diff --git a/testsuite/fixtures/testMain.fixture b/testsuite/fixtures/testMain.fixture
index 233d7d5c07293..0fd5f0bcbc28e 100644
--- a/testsuite/fixtures/testMain.fixture
+++ b/testsuite/fixtures/testMain.fixture
@@ -1,9 +1,13 @@
 Looking for cluster aptos-forge-big-1 in cloud AWS
 Found cluster: Cloud.AWS/us-west-2/aptos-forge-big-1
+Checking if image exists in GCP: aptos/validator-testing:banana
 Using the following image tags:
 	forge:  banana
 	swarm:  banana
 	swarm upgrade (if applicable):  banana
+Checking if image exists in GCP: aptos/validator-testing:banana
+Checking if image exists in GCP: aptos/validator-testing:banana
+Checking if image exists in GCP: aptos/forge:banana
 === Start temp-pre-comment ===
 ### Forge is running suite `banana-test` on `banana`
 * [Grafana dashboard (auto-refresh)](https://aptoslabs.grafana.net/d/overview/overview?orgId=1&refresh=10s&var-Datasource=VictoriaMetrics%20Global%20%28Non-mainnet%29&var-BigQuery=Google%20BigQuery&var-namespace=forge-perry-1659078000&var-metrics_source=All&var-chain_name=forge-big-1&refresh=10s&from=now-15m&to=now)
diff --git a/testsuite/forge.py b/testsuite/forge.py
index 0fd7f96fa66ff..d9ef684b12cdb 100644
--- a/testsuite/forge.py
+++ b/testsuite/forge.py
@@ -47,15 +47,18 @@
     "release": "",  # the default release profile has no tag prefix
 }
 
-VALIDATOR_IMAGE_NAME = "aptos/validator"
-VALIDATOR_TESTING_IMAGE_NAME = "aptos/validator-testing"
-FORGE_IMAGE_NAME = "aptos/forge"
+VALIDATOR_IMAGE_NAME = "validator"
+VALIDATOR_TESTING_IMAGE_NAME = "validator-testing"
+FORGE_IMAGE_NAME = "forge"
+ECR_REPO_PREFIX = "aptos"
 
 DEFAULT_CONFIG = "forge-wrapper-config"
 DEFAULT_CONFIG_KEY = "forge-wrapper-config.json"
 
 FORGE_TEST_RUNNER_TEMPLATE_PATH = "forge-test-runner-template.yaml"
 
+GAR_REPO_NAME = "us-west1-docker.pkg.dev/aptos-global/aptos-internal"
+
 
 @dataclass
 class RunResult:
@@ -676,12 +679,12 @@ def run(self, context: ForgeContext) -> ForgeResult:
 
         # determine the interal image repos based on the context of where the cluster is located
         if context.cloud == Cloud.AWS:
-            forge_image_full = f"{context.aws_account_num}.dkr.ecr.{context.aws_region}.amazonaws.com/aptos/forge:{context.forge_image_tag}"
+            forge_image_full = f"{context.aws_account_num}.dkr.ecr.{context.aws_region}.amazonaws.com/{ECR_REPO_PREFIX}/forge:{context.forge_image_tag}"
             validator_node_selector = "eks.amazonaws.com/nodegroup: validators"
         elif (
             context.cloud == Cloud.GCP
         ):  # the GCP project for images is separate than the cluster
-            forge_image_full = f"us-west1-docker.pkg.dev/aptos-global/aptos-internal/forge:{context.forge_image_tag}"
+            forge_image_full = f"{GAR_REPO_NAME}/forge:{context.forge_image_tag}"
             validator_node_selector = ""  # no selector
             # TODO: also no NAP node selector yet
             # TODO: also registries need to be set up such that the default compute service account can access it:  $PROJECT_ID-compute@developer.gserviceaccount.com
@@ -852,6 +855,7 @@ def find_recent_images_by_profile_or_features(
     num_images: int,
     enable_failpoints: Optional[bool],
     enable_performance_profile: Optional[bool],
+    cloud: Cloud = Cloud.GCP,
 ) -> Sequence[str]:
     image_tag_prefix = ""
     if enable_failpoints and enable_performance_profile:
@@ -870,6 +874,7 @@ def find_recent_images_by_profile_or_features(
         num_images,
         image_name=VALIDATOR_TESTING_IMAGE_NAME,
         image_tag_prefixes=[image_tag_prefix],
+        cloud=cloud,
     )
 
 
@@ -880,6 +885,7 @@ def find_recent_images(
     image_name: str,
     image_tag_prefixes: List[str] = [""],
     commit_threshold: int = 100,
+    cloud: Cloud = Cloud.GCP,
 ) -> Sequence[str]:
     """
     Find the last `num_images` images built from the current git repo by searching the git commit history
@@ -901,7 +907,7 @@ def find_recent_images(
         temp_ret = []  # count variants for this revision
         for prefix in image_tag_prefixes:
             image_tag = f"{prefix}{revision}"
-            exists = image_exists(shell, image_name, image_tag)
+            exists = image_exists(shell, image_name, image_tag, cloud=cloud)
             if exists:
                 temp_ret.append(image_tag)
             if len(temp_ret) >= num_variants:
@@ -916,19 +922,40 @@ def find_recent_images(
     return ret
 
 
-def image_exists(shell: Shell, image_name: str, image_tag: str) -> bool:
-    result = shell.run(
-        [
-            "aws",
-            "ecr",
-            "describe-images",
-            "--repository-name",
-            f"{image_name}",
-            "--image-ids",
-            f"imageTag={image_tag}",
-        ]
-    )
-    return result.exit_code == 0
+def image_exists(
+    shell: Shell,
+    image_name: str,
+    image_tag: str,
+    cloud: Cloud = Cloud.GCP,
+) -> bool:
+    """Check if an image exists in a given repository"""
+    if cloud == Cloud.GCP:
+        full_image = f"{GAR_REPO_NAME}/{image_name}:{image_tag}"
+        return shell.run(
+            [
+                "crane",
+                "manifest",
+                full_image,
+            ],
+            stream_output=True,
+        ).succeeded()
+    elif cloud == Cloud.AWS:
+        full_image = f"{ECR_REPO_PREFIX}/{image_name}:{image_tag}"
+        log.info(f"Checking if image exists in GCP: {full_image}")
+        return shell.run(
+            [
+                "aws",
+                "ecr",
+                "describe-images",
+                "--repository-name",
+                f"{ECR_REPO_PREFIX}/{image_name}",
+                "--image-ids",
+                f"imageTag={image_tag}",
+            ],
+            stream_output=True,
+        ).succeeded()
+    else:
+        raise Exception(f"Unknown cloud repo type: {cloud}")
 
 
 def sanitize_forge_resource_name(forge_resource: str) -> str:
@@ -1338,6 +1365,7 @@ def test(
                 2,
                 enable_failpoints=enable_failpoints,
                 enable_performance_profile=enable_performance_profile,
+                cloud=cloud_enum,
             )
         )
         # This might not work as intended because we dont know if that revision
@@ -1354,6 +1382,7 @@ def test(
             1,
             enable_failpoints=enable_failpoints,
             enable_performance_profile=enable_performance_profile,
+            cloud=cloud_enum,
         )[0]
 
         image_tag = image_tag or default_latest_image
@@ -1378,13 +1407,13 @@ def test(
 
     # finally, whether we've derived the image tags or used the user-inputted ones, check if they exist
     assert image_exists(
-        shell, VALIDATOR_TESTING_IMAGE_NAME, image_tag
+        shell, VALIDATOR_TESTING_IMAGE_NAME, image_tag, cloud=cloud_enum
     ), f"swarm (validator) image does not exist: {image_tag}"
     assert image_exists(
-        shell, VALIDATOR_TESTING_IMAGE_NAME, upgrade_image_tag
+        shell, VALIDATOR_TESTING_IMAGE_NAME, upgrade_image_tag, cloud=cloud_enum
     ), f"swarm upgrade (validator) image does not exist: {upgrade_image_tag}"
     assert image_exists(
-        shell, FORGE_IMAGE_NAME, forge_image_tag
+        shell, FORGE_IMAGE_NAME, forge_image_tag, cloud=cloud_enum
     ), f"forge (test runner) image does not exist: {forge_image_tag}"
 
     forge_args = create_forge_command(
diff --git a/testsuite/forge_test.py b/testsuite/forge_test.py
index b5b3510b15de2..ff3a2fcfc5e36 100644
--- a/testsuite/forge_test.py
+++ b/testsuite/forge_test.py
@@ -39,6 +39,7 @@
     main,
     sanitize_forge_resource_name,
     validate_forge_config,
+    GAR_REPO_NAME,
 )
 
 from click.testing import CliRunner, Result
@@ -56,6 +57,7 @@
 
 from test_framework.shell import SpyShell, FakeShell, FakeCommand, RunResult
 from test_framework.time import FakeTime
+from test_framework.cluster import Cloud
 
 # Show the entire diff when unittest fails assertion
 unittest.util._MAX_LENGTH = 2000  # type: ignore
@@ -278,7 +280,31 @@ def testFindRecentImage(self) -> None:
             ]
         )
         git = Git(shell)
-        image_tags = find_recent_images(shell, git, 1, "aptos/validator-testing")
+        image_tags = find_recent_images(
+            shell, git, 1, "validator-testing", cloud=Cloud.AWS
+        )
+        self.assertEqual(list(image_tags), ["lychee"])
+        shell.assert_commands(self)
+
+    def testFindRecentImageGcp(self) -> None:
+        shell = SpyShell(
+            [
+                FakeCommand("git rev-parse HEAD~0", RunResult(0, b"potato\n")),
+                FakeCommand(
+                    f"crane manifest {GAR_REPO_NAME}/validator-testing:potato",
+                    RunResult(1, b""),
+                ),
+                FakeCommand("git rev-parse HEAD~1", RunResult(0, b"lychee\n")),
+                FakeCommand(
+                    f"crane manifest {GAR_REPO_NAME}/validator-testing:lychee",
+                    RunResult(0, b""),
+                ),
+            ]
+        )
+        git = Git(shell)
+        image_tags = find_recent_images(
+            shell, git, 1, "validator-testing", cloud=Cloud.GCP
+        )
         self.assertEqual(list(image_tags), ["lychee"])
         shell.assert_commands(self)
 
@@ -294,7 +320,12 @@ def testFindRecentFailpointsImage(self) -> None:
         )
         git = Git(shell)
         image_tags = find_recent_images_by_profile_or_features(
-            shell, git, 1, enable_performance_profile=False, enable_failpoints=True
+            shell,
+            git,
+            1,
+            enable_performance_profile=False,
+            enable_failpoints=True,
+            cloud=Cloud.AWS,
         )
         self.assertEqual(list(image_tags), ["failpoints_tomato"])
         shell.assert_commands(self)
@@ -316,6 +347,7 @@ def testFindRecentPerformanceImage(self) -> None:
             1,
             enable_performance_profile=True,
             enable_failpoints=False,
+            cloud=Cloud.AWS,
         )
         self.assertEqual(list(image_tags), ["performance_potato"])
         shell.assert_commands(self)
@@ -368,7 +400,7 @@ def testFindRecentFewImages(
             ]
         )
         git = Git(shell)
-        images = find_recent_images(shell, git, 2, "aptos/validator")
+        images = find_recent_images(shell, git, 2, "validator", cloud=Cloud.AWS)
         self.assertEqual(list(images), ["crab", "shrimp"])
 
     def testFailpointsProvidedImageTag(self) -> None:

From b7ddfcf62635421d573f7e07a3406710835fb24f Mon Sep 17 00:00:00 2001
From: "Daniel Porteous (dport)" 
Date: Thu, 15 Jun 2023 14:30:04 +0100
Subject: [PATCH 176/200] [CLI][E2E] Add test for aptos move publish (#8590)

---
 .../move-examples/cli-e2e-tests/README.md     |   4 +
 .../common/sources/cli_e2e_tests.move         | 327 ++++++++++++++++++
 .../cli-e2e-tests/devnet/Move.toml            |  16 +
 .../cli-e2e-tests/devnet/sources              |   1 +
 .../cli-e2e-tests/mainnet/Move.toml           |  16 +
 .../cli-e2e-tests/mainnet/sources             |   1 +
 .../cli-e2e-tests/testnet/Move.toml           |  16 +
 .../cli-e2e-tests/testnet/sources             |   1 +
 crates/aptos/e2e/README.md                    |   9 +-
 crates/aptos/e2e/cases/move.py                |  61 ++++
 crates/aptos/e2e/main.py                      |   4 +
 crates/aptos/e2e/test_helpers.py              |  67 +++-
 12 files changed, 503 insertions(+), 20 deletions(-)
 create mode 100644 aptos-move/move-examples/cli-e2e-tests/README.md
 create mode 100644 aptos-move/move-examples/cli-e2e-tests/common/sources/cli_e2e_tests.move
 create mode 100644 aptos-move/move-examples/cli-e2e-tests/devnet/Move.toml
 create mode 120000 aptos-move/move-examples/cli-e2e-tests/devnet/sources
 create mode 100644 aptos-move/move-examples/cli-e2e-tests/mainnet/Move.toml
 create mode 120000 aptos-move/move-examples/cli-e2e-tests/mainnet/sources
 create mode 100644 aptos-move/move-examples/cli-e2e-tests/testnet/Move.toml
 create mode 120000 aptos-move/move-examples/cli-e2e-tests/testnet/sources
 create mode 100644 crates/aptos/e2e/cases/move.py

diff --git a/aptos-move/move-examples/cli-e2e-tests/README.md b/aptos-move/move-examples/cli-e2e-tests/README.md
new file mode 100644
index 0000000000000..8929f80118e3b
--- /dev/null
+++ b/aptos-move/move-examples/cli-e2e-tests/README.md
@@ -0,0 +1,4 @@
+# CLI E2E tests
+These packages, one per production network, are used by the CLI E2E tests to test the correctness of the `aptos move` subcommand group. As such there is no particular rhyme or reason to what goes into these, it is meant to be an expressive selection of different, new features we might want to assert.
+
+As it is now the 3 packages share the same source code. Down the line we might want to use these tests to confirm that the CLI works with a new feature as it lands in devnet, then testnet, then mainnet. For that we'd need to separate the source.
diff --git a/aptos-move/move-examples/cli-e2e-tests/common/sources/cli_e2e_tests.move b/aptos-move/move-examples/cli-e2e-tests/common/sources/cli_e2e_tests.move
new file mode 100644
index 0000000000000..613056d72f1be
--- /dev/null
+++ b/aptos-move/move-examples/cli-e2e-tests/common/sources/cli_e2e_tests.move
@@ -0,0 +1,327 @@
+module addr::cli_e2e_tests {
+    use std::error;
+    use std::option::{Self, Option};
+    use std::signer;
+    use std::string::{Self, String};
+
+    use aptos_framework::object::{Self, ConstructorRef, Object};
+
+    use aptos_token_objects::collection;
+    use aptos_token_objects::token;
+    use aptos_std::string_utils;
+
+    const ENOT_A_HERO: u64 = 1;
+    const ENOT_A_WEAPON: u64 = 2;
+    const ENOT_A_GEM: u64 = 3;
+    const ENOT_CREATOR: u64 = 4;
+    const EINVALID_WEAPON_UNEQUIP: u64 = 5;
+    const EINVALID_GEM_UNEQUIP: u64 = 6;
+    const EINVALID_TYPE: u64 = 7;
+
+    struct OnChainConfig has key {
+        collection: String,
+    }
+
+    #[resource_group_member(group = aptos_framework::object::ObjectGroup)]
+    struct Hero has key {
+        armor: Option>,
+        gender: String,
+        race: String,
+        shield: Option>,
+        weapon: Option>,
+        mutator_ref: token::MutatorRef,
+    }
+
+    #[resource_group_member(group = aptos_framework::object::ObjectGroup)]
+    struct Armor has key {
+        defense: u64,
+        gem: Option>,
+        weight: u64,
+    }
+
+    #[resource_group_member(group = aptos_framework::object::ObjectGroup)]
+    struct Gem has key {
+        attack_modifier: u64,
+        defense_modifier: u64,
+        magic_attribute: String,
+    }
+
+    #[resource_group_member(group = aptos_framework::object::ObjectGroup)]
+    struct Shield has key {
+        defense: u64,
+        gem: Option>,
+        weight: u64,
+    }
+
+    #[resource_group_member(group = aptos_framework::object::ObjectGroup)]
+    struct Weapon has key {
+        attack: u64,
+        gem: Option>,
+        weapon_type: String,
+        weight: u64,
+    }
+
+    fun init_module(account: &signer) {
+        let collection = string::utf8(b"Hero Quest!");
+        collection::create_unlimited_collection(
+            account,
+            string::utf8(b"collection description"),
+            collection,
+            option::none(),
+            string::utf8(b"collection uri"),
+        );
+
+        let on_chain_config = OnChainConfig {
+            collection: string::utf8(b"Hero Quest!"),
+        };
+        move_to(account, on_chain_config);
+    }
+
+    fun create(
+        creator: &signer,
+        description: String,
+        name: String,
+        uri: String,
+    ): ConstructorRef acquires OnChainConfig {
+        let on_chain_config = borrow_global(signer::address_of(creator));
+        token::create_named_token(
+            creator,
+            on_chain_config.collection,
+            description,
+            name,
+            option::none(),
+            uri,
+        )
+    }
+
+    // Creation methods
+
+    public fun create_hero(
+        creator: &signer,
+        description: String,
+        gender: String,
+        name: String,
+        race: String,
+        uri: String,
+    ): Object acquires OnChainConfig {
+        let constructor_ref = create(creator, description, name, uri);
+        let token_signer = object::generate_signer(&constructor_ref);
+
+        let hero = Hero {
+            armor: option::none(),
+            gender,
+            race,
+            shield: option::none(),
+            weapon: option::none(),
+            mutator_ref: token::generate_mutator_ref(&constructor_ref),
+        };
+        move_to(&token_signer, hero);
+
+        object::address_to_object(signer::address_of(&token_signer))
+    }
+
+    public fun create_weapon(
+        creator: &signer,
+        attack: u64,
+        description: String,
+        name: String,
+        uri: String,
+        weapon_type: String,
+        weight: u64,
+    ): Object acquires OnChainConfig {
+        let constructor_ref = create(creator, description, name, uri);
+        let token_signer = object::generate_signer(&constructor_ref);
+
+        let weapon = Weapon {
+            attack,
+            gem: option::none(),
+            weapon_type,
+            weight,
+        };
+        move_to(&token_signer, weapon);
+
+        object::address_to_object(signer::address_of(&token_signer))
+    }
+
+    public fun create_gem(
+        creator: &signer,
+        attack_modifier: u64,
+        defense_modifier: u64,
+        description: String,
+        magic_attribute: String,
+        name: String,
+        uri: String,
+    ): Object acquires OnChainConfig {
+        let constructor_ref = create(creator, description, name, uri);
+        let token_signer = object::generate_signer(&constructor_ref);
+
+        let gem = Gem {
+            attack_modifier,
+            defense_modifier,
+            magic_attribute,
+        };
+        move_to(&token_signer, gem);
+
+        object::address_to_object(signer::address_of(&token_signer))
+    }
+
+    // Transfer wrappers
+
+    public fun hero_equip_weapon(owner: &signer, hero: Object, weapon: Object) acquires Hero {
+        let hero_obj = borrow_global_mut(object::object_address(&hero));
+        option::fill(&mut hero_obj.weapon, weapon);
+        object::transfer_to_object(owner, weapon, hero);
+    }
+
+    public fun hero_unequip_weapon(owner: &signer, hero: Object, weapon: Object) acquires Hero {
+        let hero_obj = borrow_global_mut(object::object_address(&hero));
+        let stored_weapon = option::extract(&mut hero_obj.weapon);
+        assert!(stored_weapon == weapon, error::not_found(EINVALID_WEAPON_UNEQUIP));
+        object::transfer(owner, weapon, signer::address_of(owner));
+    }
+
+    public fun weapon_equip_gem(owner: &signer, weapon: Object, gem: Object) acquires Weapon {
+        let weapon_obj = borrow_global_mut(object::object_address(&weapon));
+        option::fill(&mut weapon_obj.gem, gem);
+        object::transfer_to_object(owner, gem, weapon);
+    }
+
+    public fun weapon_unequip_gem(owner: &signer, weapon: Object, gem: Object) acquires Weapon {
+        let weapon_obj = borrow_global_mut(object::object_address(&weapon));
+        let stored_gem = option::extract(&mut weapon_obj.gem);
+        assert!(stored_gem == gem, error::not_found(EINVALID_GEM_UNEQUIP));
+        object::transfer(owner, gem, signer::address_of(owner));
+    }
+
+    // Entry functions
+
+    entry fun mint_hero(
+        account: &signer,
+        description: String,
+        gender: String,
+        name: String,
+        race: String,
+        uri: String,
+    ) acquires OnChainConfig {
+        create_hero(account, description, gender, name, race, uri);
+    }
+
+    entry fun set_hero_description(
+        creator: &signer,
+        collection: String,
+        name: String,
+        description: String,
+    ) acquires Hero {
+        let (hero_obj, hero) = get_hero(
+            &signer::address_of(creator),
+            &collection,
+            &name,
+        );
+        let creator_addr = token::creator(hero_obj);
+        assert!(creator_addr == signer::address_of(creator), error::permission_denied(ENOT_CREATOR));
+        token::set_description(&hero.mutator_ref, description);
+    }
+
+    // View functions
+    #[view]
+    fun view_hero(creator: address, collection: String, name: String): Hero acquires Hero {
+        let token_address = token::create_token_address(
+            &creator,
+            &collection,
+            &name,
+        );
+        move_from(token_address)
+    }
+
+    #[view]
+    fun view_hero_by_object(hero_obj: Object): Hero acquires Hero {
+        let token_address = object::object_address(&hero_obj);
+        move_from(token_address)
+    }
+
+    #[view]
+    fun view_object(obj: Object): String acquires Armor, Gem, Hero, Shield, Weapon {
+        let token_address = object::object_address(&obj);
+        if (exists(token_address)) {
+            string_utils::to_string(borrow_global(token_address))
+        } else if (exists(token_address)) {
+            string_utils::to_string(borrow_global(token_address))
+        } else if (exists(token_address)) {
+            string_utils::to_string(borrow_global(token_address))
+        } else if (exists(token_address)) {
+            string_utils::to_string(borrow_global(token_address))
+        } else if (exists(token_address)) {
+            string_utils::to_string(borrow_global(token_address))
+        } else {
+            abort EINVALID_TYPE
+        }
+    }
+
+    inline fun get_hero(creator: &address, collection: &String, name: &String): (Object, &Hero) {
+        let token_address = token::create_token_address(
+            creator,
+            collection,
+            name,
+        );
+        (object::address_to_object(token_address), borrow_global(token_address))
+    }
+
+    #[test(account = @0x3)]
+    fun test_hero_with_gem_weapon(account: &signer) acquires Hero, OnChainConfig, Weapon {
+        init_module(account);
+
+        let hero = create_hero(
+            account,
+            string::utf8(b"The best hero ever!"),
+            string::utf8(b"Male"),
+            string::utf8(b"Wukong"),
+            string::utf8(b"Monkey God"),
+            string::utf8(b""),
+        );
+
+        let weapon = create_weapon(
+            account,
+            32,
+            string::utf8(b"A magical staff!"),
+            string::utf8(b"Ruyi Jingu Bang"),
+            string::utf8(b""),
+            string::utf8(b"staff"),
+            15,
+        );
+
+        let gem = create_gem(
+            account,
+            32,
+            32,
+            string::utf8(b"Beautiful specimen!"),
+            string::utf8(b"earth"),
+            string::utf8(b"jade"),
+            string::utf8(b""),
+        );
+
+        let account_address = signer::address_of(account);
+        assert!(object::is_owner(hero, account_address), 0);
+        assert!(object::is_owner(weapon, account_address), 1);
+        assert!(object::is_owner(gem, account_address), 2);
+
+        hero_equip_weapon(account, hero, weapon);
+        assert!(object::is_owner(hero, account_address), 3);
+        assert!(object::is_owner(weapon, object::object_address(&hero)), 4);
+        assert!(object::is_owner(gem, account_address), 5);
+
+        weapon_equip_gem(account, weapon, gem);
+        assert!(object::is_owner(hero, account_address), 6);
+        assert!(object::is_owner(weapon, object::object_address(&hero)), 7);
+        assert!(object::is_owner(gem, object::object_address(&weapon)), 8);
+
+        hero_unequip_weapon(account, hero, weapon);
+        assert!(object::is_owner(hero, account_address), 9);
+        assert!(object::is_owner(weapon, account_address), 10);
+        assert!(object::is_owner(gem, object::object_address(&weapon)), 11);
+
+        weapon_unequip_gem(account, weapon, gem);
+        assert!(object::is_owner(hero, account_address), 12);
+        assert!(object::is_owner(weapon, account_address), 13);
+        assert!(object::is_owner(gem, account_address), 14);
+    }
+}
diff --git a/aptos-move/move-examples/cli-e2e-tests/devnet/Move.toml b/aptos-move/move-examples/cli-e2e-tests/devnet/Move.toml
new file mode 100644
index 0000000000000..29db695268495
--- /dev/null
+++ b/aptos-move/move-examples/cli-e2e-tests/devnet/Move.toml
@@ -0,0 +1,16 @@
+[package]
+name = "cli_e2e_tests"
+version = "0.0.1"
+
+[addresses]
+addr = "_"
+
+[dependencies.AptosFramework]
+git = "https://github.com/aptos-labs/aptos-core.git"
+rev = "devnet"
+subdir = "aptos-move/framework/aptos-framework"
+
+[dependencies.AptosTokenObjects]
+git = "https://github.com/aptos-labs/aptos-core.git"
+rev = "devnet"
+subdir = "aptos-move/framework/aptos-token-objects"
diff --git a/aptos-move/move-examples/cli-e2e-tests/devnet/sources b/aptos-move/move-examples/cli-e2e-tests/devnet/sources
new file mode 120000
index 0000000000000..3fcdf678f47c5
--- /dev/null
+++ b/aptos-move/move-examples/cli-e2e-tests/devnet/sources
@@ -0,0 +1 @@
+../common/sources/
\ No newline at end of file
diff --git a/aptos-move/move-examples/cli-e2e-tests/mainnet/Move.toml b/aptos-move/move-examples/cli-e2e-tests/mainnet/Move.toml
new file mode 100644
index 0000000000000..b74dc02f72f5a
--- /dev/null
+++ b/aptos-move/move-examples/cli-e2e-tests/mainnet/Move.toml
@@ -0,0 +1,16 @@
+[package]
+name = "cli_e2e_tests"
+version = "0.0.1"
+
+[addresses]
+addr = "_"
+
+[dependencies.AptosFramework]
+git = "https://github.com/aptos-labs/aptos-core.git"
+rev = "mainnet"
+subdir = "aptos-move/framework/aptos-framework"
+
+[dependencies.AptosTokenObjects]
+git = "https://github.com/aptos-labs/aptos-core.git"
+rev = "mainnet"
+subdir = "aptos-move/framework/aptos-token-objects"
diff --git a/aptos-move/move-examples/cli-e2e-tests/mainnet/sources b/aptos-move/move-examples/cli-e2e-tests/mainnet/sources
new file mode 120000
index 0000000000000..3fcdf678f47c5
--- /dev/null
+++ b/aptos-move/move-examples/cli-e2e-tests/mainnet/sources
@@ -0,0 +1 @@
+../common/sources/
\ No newline at end of file
diff --git a/aptos-move/move-examples/cli-e2e-tests/testnet/Move.toml b/aptos-move/move-examples/cli-e2e-tests/testnet/Move.toml
new file mode 100644
index 0000000000000..0ffe8f1734786
--- /dev/null
+++ b/aptos-move/move-examples/cli-e2e-tests/testnet/Move.toml
@@ -0,0 +1,16 @@
+[package]
+name = "cli_e2e_tests"
+version = "0.0.1"
+
+[addresses]
+addr = "_"
+
+[dependencies.AptosFramework]
+git = "https://github.com/aptos-labs/aptos-core.git"
+rev = "testnet"
+subdir = "aptos-move/framework/aptos-framework"
+
+[dependencies.AptosTokenObjects]
+git = "https://github.com/aptos-labs/aptos-core.git"
+rev = "testnet"
+subdir = "aptos-move/framework/aptos-token-objects"
diff --git a/aptos-move/move-examples/cli-e2e-tests/testnet/sources b/aptos-move/move-examples/cli-e2e-tests/testnet/sources
new file mode 120000
index 0000000000000..3fcdf678f47c5
--- /dev/null
+++ b/aptos-move/move-examples/cli-e2e-tests/testnet/sources
@@ -0,0 +1 @@
+../common/sources/
\ No newline at end of file
diff --git a/crates/aptos/e2e/README.md b/crates/aptos/e2e/README.md
index e0787ee26c9a1..740d6ff7facbe 100644
--- a/crates/aptos/e2e/README.md
+++ b/crates/aptos/e2e/README.md
@@ -19,9 +19,14 @@ To learn how to use the CLI testing framework, run this:
 poetry run python main.py -h
 ```
 
-For example:
+For example, using the CLI from an image:
 ```
-poetry run python main.py --base-network mainnet --test-cli-tag mainnet
+poetry run python main.py --base-network mainnet --test-cli-tag nightly
+```
+
+Using the CLI from a local path:
+```
+poetry run python main.py -d --base-network mainnet --test-cli-path ~/aptos-core/target/debug/aptos
 ```
 
 ## Debugging
diff --git a/crates/aptos/e2e/cases/move.py b/crates/aptos/e2e/cases/move.py
new file mode 100644
index 0000000000000..a2b146cbb5ae1
--- /dev/null
+++ b/crates/aptos/e2e/cases/move.py
@@ -0,0 +1,61 @@
+# Copyright © Aptos Foundation
+# SPDX-License-Identifier: Apache-2.0
+
+import json
+
+from common import TestError
+from test_helpers import RunHelper
+from test_results import test_case
+
+
+@test_case
+def test_move_publish(run_helper: RunHelper, test_name=None):
+    # Prior to this function running the move/ directory was moved into the working
+    # directory in the host, which is then mounted into the container. The CLI is
+    # then run in this directory, meaning the move/ directory is in the same directory
+    # as the CLI is run from. This is why we can just refer to the package dir starting
+    # with move/ here.
+    package_dir = f"move/{run_helper.base_network}"
+
+    # Publish the module.
+    run_helper.run_command(
+        test_name,
+        [
+            "aptos",
+            "move",
+            "publish",
+            "--assume-yes",
+            "--package-dir",
+            package_dir,
+            "--named-addresses",
+            f"addr={run_helper.get_account_info().account_address}",
+        ],
+    )
+
+    # Get what modules exist on chain.
+    response = run_helper.run_command(
+        test_name,
+        [
+            "aptos",
+            "account",
+            "list",
+            "--account",
+            run_helper.get_account_info().account_address,
+            "--query",
+            "modules",
+        ],
+    )
+
+    # Confirm that the module exists on chain.
+    response = json.loads(response.stdout)
+    for module in response["Result"]:
+        if (
+            module["abi"]["address"]
+            == f"0x{run_helper.get_account_info().account_address}"
+            and module["abi"]["name"] == "cli_e2e_tests"
+        ):
+            return
+
+    raise TestError(
+        "Module apparently published successfully but it could not be found on chain"
+    )
diff --git a/crates/aptos/e2e/main.py b/crates/aptos/e2e/main.py
index 5403d01473382..d56a552a82af3 100644
--- a/crates/aptos/e2e/main.py
+++ b/crates/aptos/e2e/main.py
@@ -35,6 +35,7 @@
     test_account_lookup_address,
 )
 from cases.init import test_aptos_header_included, test_init, test_metrics_accessible
+from cases.move import test_move_publish
 from common import Network
 from local_testnet import run_node, stop_node, wait_for_startup
 from test_helpers import RunHelper
@@ -114,6 +115,9 @@ def run_tests(run_helper):
     # Make sure the aptos-cli header is included on the original request
     test_aptos_header_included(run_helper)
 
+    # Run move subcommand group tests.
+    test_move_publish(run_helper)
+
 
 def main():
     args = parse_args()
diff --git a/crates/aptos/e2e/test_helpers.py b/crates/aptos/e2e/test_helpers.py
index b668d2682589b..8ab427d573be3 100644
--- a/crates/aptos/e2e/test_helpers.py
+++ b/crates/aptos/e2e/test_helpers.py
@@ -4,6 +4,7 @@
 import logging
 import os
 import pathlib
+import shutil
 import subprocess
 import traceback
 from dataclasses import dataclass
@@ -45,6 +46,7 @@ def __init__(
         self.host_working_directory = host_working_directory
         self.image_repo_with_project = image_repo_with_project
         self.image_tag = image_tag
+        self.base_network = base_network
         self.cli_path = os.path.abspath(cli_path) if cli_path else cli_path
         self.base_network = base_network
         self.test_count = 0
@@ -61,25 +63,41 @@ def run_command(self, test_name, command, *args, **kwargs):
         file_name = f"{self.test_count:03}_{test_name}"
         self.test_count += 1
 
+        # If we're in a CI environment it is necessary to set the --user, otherwise it
+        # is not possible to interact with the files in the bindmount. For more details
+        # see here: https://github.com/community/community/discussions/44243.
+        if os.environ.get("CI"):
+            user_args = ["--user", f"{os.getuid()}:{os.getgid()}"]
+        else:
+            user_args = []
+
         # Build command.
         if self.image_tag:
-            full_command = [
-                "docker",
-                "run",
-                # For why we have to set --user, see here:
-                # https://github.com/community/community/discussions/44243
-                "--user",
-                f"{os.getuid()}:{os.getgid()}",
-                "--rm",
-                "--network",
-                "host",
-                "-i",
-                "-v",
-                f"{self.host_working_directory}:{WORKING_DIR_IN_CONTAINER}",
-                "--workdir",
-                WORKING_DIR_IN_CONTAINER,
-                self.build_image_name(),
-            ] + command
+            full_command = (
+                [
+                    "docker",
+                    "run",
+                ]
+                + user_args
+                + [
+                    "-e",
+                    # This is necessary to force the CLI to place the `.move` directory
+                    # inside the bindmount dir, which is the only writeable directory
+                    # inside the container when in CI. It's fine to do it outside of CI
+                    # as well.
+                    f"HOME={WORKING_DIR_IN_CONTAINER}",
+                    "--rm",
+                    "--network",
+                    "host",
+                    "-i",
+                    "-v",
+                    f"{self.host_working_directory}:{WORKING_DIR_IN_CONTAINER}",
+                    "--workdir",
+                    WORKING_DIR_IN_CONTAINER,
+                    self.build_image_name(),
+                ]
+                + command
+            )
         else:
             full_command = [self.cli_path] + command[1:]
         LOG.debug(f"Running command: {full_command}")
@@ -130,10 +148,23 @@ def run_command(self, test_name, command, *args, **kwargs):
 
             raise
 
+    # Top level function to run any preparation.
+    def prepare(self):
+        self.prepare_move()
+        self.prepare_cli()
+
+    # Move any Move files into the working directory.
+    def prepare_move(self):
+        shutil.copytree(
+            "../../../aptos-move/move-examples/cli-e2e-tests",
+            os.path.join(self.host_working_directory, "move"),
+            ignore=shutil.ignore_patterns("build"),
+        )
+
     # If image_Tag is set, pull the test CLI image. We don't technically have to do
     # this separately but it makes the steps clearer. Otherwise, cli_path must be
     # set, in which case we ensure the file is there.
-    def prepare(self):
+    def prepare_cli(self):
         if self.image_tag:
             image_name = self.build_image_name()
             LOG.info(f"Pre-pulling image for CLI we're testing: {image_name}")

From 74ccc19df4b687088e016011288f5eef132531bd Mon Sep 17 00:00:00 2001
From: runtianz 
Date: Thu, 15 Jun 2023 09:28:28 -0700
Subject: [PATCH 177/200] [aptos-vm] Skip converting storage error (#8674)

* [aptos-vm] Skip converting storage error

* fixup! [aptos-vm] Skip converting storage error
---
 aptos-move/aptos-vm/src/errors.rs | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/aptos-move/aptos-vm/src/errors.rs b/aptos-move/aptos-vm/src/errors.rs
index 49dc6796a2329..919748dc28a14 100644
--- a/aptos-move/aptos-vm/src/errors.rs
+++ b/aptos-move/aptos-vm/src/errors.rs
@@ -132,6 +132,8 @@ pub fn convert_prologue_error(
             };
             VMStatus::Error(new_major_status, None)
         },
+        // Storage error can be a result of speculation failure so throw the error back for caller to handle.
+        e @ VMStatus::Error(StatusCode::STORAGE_ERROR, _) => e,
         status @ VMStatus::ExecutionFailure { .. } | status @ VMStatus::Error(..) => {
             speculative_error!(
                 log_context,
@@ -176,7 +178,8 @@ pub fn convert_epilogue_error(
                 VMStatus::Error(StatusCode::UNEXPECTED_ERROR_FROM_KNOWN_MOVE_FUNCTION, None)
             },
         },
-
+        // Storage error can be a result of speculation failure so throw the error back for caller to handle.
+        e @ VMStatus::Error(StatusCode::STORAGE_ERROR, _) => e,
         status => {
             speculative_error!(
                 log_context,
@@ -198,7 +201,8 @@ pub fn expect_only_successful_execution(
     let status = error.into_vm_status();
     Err(match status {
         VMStatus::Executed => VMStatus::Executed,
-
+        // Storage error can be a result of speculation failure so throw the error back for caller to handle.
+        e @ VMStatus::Error(StatusCode::STORAGE_ERROR, _) => e,
         status => {
             // Only trigger a warning here as some errors could be a result of the speculative parallel execution.
             // We will report the errors after we obtained the final transaction output in update_counters_for_processed_chunk

From 141323a7d975c430267841f9eb5dcba54be488ab Mon Sep 17 00:00:00 2001
From: xbtmatt <90358481+xbtmatt@users.noreply.github.com>
Date: Thu, 15 Jun 2023 10:55:58 -0700
Subject: [PATCH 178/200] Adding an example of a token that is non-transferable
 for the first 7 days of ownership

Moved the unit tests to a different file

Added the token_lockup unit tests to move_unit_tests.rs
---
 .../move-examples/tests/move_unit_tests.rs    |   1 +
 .../move-examples/token_objects/README.md     |   1 +
 .../token_objects/token_lockup/Move.toml      |  10 ++
 .../token_lockup/sources/token_lockup.move    | 105 +++++++++++
 .../token_lockup/sources/unit_tests.move      | 170 ++++++++++++++++++
 5 files changed, 287 insertions(+)
 create mode 100644 aptos-move/move-examples/token_objects/token_lockup/Move.toml
 create mode 100644 aptos-move/move-examples/token_objects/token_lockup/sources/token_lockup.move
 create mode 100644 aptos-move/move-examples/token_objects/token_lockup/sources/unit_tests.move

diff --git a/aptos-move/move-examples/tests/move_unit_tests.rs b/aptos-move/move-examples/tests/move_unit_tests.rs
index b59c434c51510..926d93a075003 100644
--- a/aptos-move/move-examples/tests/move_unit_tests.rs
+++ b/aptos-move/move-examples/tests/move_unit_tests.rs
@@ -179,6 +179,7 @@ fn test_token_objects() {
         AccountAddress::from_hex_literal("0xcafe").unwrap(),
     )]);
     run_tests_for_pkg("token_objects/hero", named_address.clone());
+    run_tests_for_pkg("token_objects/token_lockup", named_address.clone());
     run_tests_for_pkg("token_objects/ambassador/move", named_address);
 }
 
diff --git a/aptos-move/move-examples/token_objects/README.md b/aptos-move/move-examples/token_objects/README.md
index c1c001773cfee..82c86543a4baa 100644
--- a/aptos-move/move-examples/token_objects/README.md
+++ b/aptos-move/move-examples/token_objects/README.md
@@ -3,3 +3,4 @@
 This directory contains various token object examples, including:
 * hero
 * ambassador: a soulbound token example
+* token lockup: an example of how to disable transferring a token for the first 7 days of ownership
\ No newline at end of file
diff --git a/aptos-move/move-examples/token_objects/token_lockup/Move.toml b/aptos-move/move-examples/token_objects/token_lockup/Move.toml
new file mode 100644
index 0000000000000..3d8f62cb13e63
--- /dev/null
+++ b/aptos-move/move-examples/token_objects/token_lockup/Move.toml
@@ -0,0 +1,10 @@
+[package]
+name = 'Token Lockup'
+version = '1.0.0'
+
+[addresses]
+token_objects = "_"
+
+[dependencies]
+AptosFramework = { local = "../../../framework/aptos-framework" }
+AptosTokenObjects = { local = "../../../framework/aptos-token-objects" }
diff --git a/aptos-move/move-examples/token_objects/token_lockup/sources/token_lockup.move b/aptos-move/move-examples/token_objects/token_lockup/sources/token_lockup.move
new file mode 100644
index 0000000000000..2f664d4579961
--- /dev/null
+++ b/aptos-move/move-examples/token_objects/token_lockup/sources/token_lockup.move
@@ -0,0 +1,105 @@
+module token_objects::token_lockup {
+   use std::signer;
+   use std::option;
+   use std::error;
+   use std::string::{Self, String};
+   use std::object::{Self, Object, TransferRef, ConstructorRef};
+   use std::timestamp;
+   use aptos_token_objects::royalty::{Royalty};
+   use aptos_token_objects::token::{Self, Token};
+   use aptos_token_objects::collection;
+
+   #[resource_group_member(group = aptos_framework::object::ObjectGroup)]
+   struct LockupConfig has key {
+      last_transfer: u64,
+      transfer_ref: TransferRef,
+   }
+
+   /// The owner of the token has not owned it for long enough
+   const ETOKEN_IN_LOCKUP: u64 = 0;
+   /// The owner must own the token to transfer it
+   const ENOT_TOKEN_OWNER: u64 = 1;
+
+   const COLLECTION_NAME: vector = b"Rickety Raccoons";
+   const COLLECTION_DESCRIPTION: vector = b"A collection of rickety raccoons!";
+   const COLLECTION_URI: vector = b"https://ricketyracoonswebsite.com/collection/rickety-raccoon.png";
+   const TOKEN_URI: vector = b"https://ricketyracoonswebsite.com/tokens/raccoon.png";
+   const MAXIMUM_SUPPLY: u64 = 1000;
+   // 24 hours in one day * 60 minutes in one hour * 60 seconds in one minute * 7 days
+   const LOCKUP_PERIOD_SECS: u64 = (24 * 60 * 60) * 7;
+
+   public fun initialize_collection(creator: &signer) {
+      collection::create_fixed_collection(
+         creator,
+         string::utf8(COLLECTION_DESCRIPTION),
+         MAXIMUM_SUPPLY,
+         string::utf8(COLLECTION_NAME),
+         option::none(),
+         string::utf8(COLLECTION_URI),
+      );
+   }
+
+   public fun mint_to(
+      creator: &signer,
+      token_name: String,
+      to: address,
+   ): ConstructorRef {
+      let token_constructor_ref = token::create_named_token(
+         creator,
+         string::utf8(COLLECTION_NAME),
+         string::utf8(COLLECTION_DESCRIPTION),
+         token_name,
+         option::none(),
+         string::utf8(TOKEN_URI),
+      );
+
+      let transfer_ref = object::generate_transfer_ref(&token_constructor_ref);
+      let token_signer = object::generate_signer(&token_constructor_ref);
+      let token_object = object::object_from_constructor_ref(&token_constructor_ref);
+
+      // transfer the token to the receiving account before we permanently disable ungated transfer
+      object::transfer(creator, token_object, to);
+
+      // disable the ability to transfer the token through any means other than the `transfer` function we define
+      object::disable_ungated_transfer(&transfer_ref);
+
+      move_to(
+         &token_signer,
+         LockupConfig {
+            last_transfer: timestamp::now_seconds(),
+            transfer_ref,
+         }
+      );
+
+      token_constructor_ref
+   }
+
+   public entry fun transfer(
+      from: &signer,
+      token: Object,
+      to: address,
+   ) acquires LockupConfig {
+      // redundant error checking for clear error message
+      assert!(object::is_owner(token, signer::address_of(from)), error::permission_denied(ENOT_TOKEN_OWNER));
+      let now = timestamp::now_seconds();
+      let lockup_config = borrow_global_mut(object::object_address(&token));
+
+      let time_since_transfer = now - lockup_config.last_transfer;
+      let lockup_period_secs = LOCKUP_PERIOD_SECS;
+      assert!(time_since_transfer >= lockup_period_secs, error::permission_denied(ETOKEN_IN_LOCKUP));
+
+      // generate linear transfer ref and transfer the token object
+      let linear_transfer_ref = object::generate_linear_transfer_ref(&lockup_config.transfer_ref);
+      object::transfer_with_ref(linear_transfer_ref, to);
+
+      // update the lockup config to reflect the latest transfer time
+      *&mut lockup_config.last_transfer = now;
+   }
+
+   #[view]
+   public fun view_last_transfer(
+      token: Object,
+   ): u64 acquires LockupConfig {
+      borrow_global(object::object_address(&token)).last_transfer
+   }
+}
diff --git a/aptos-move/move-examples/token_objects/token_lockup/sources/unit_tests.move b/aptos-move/move-examples/token_objects/token_lockup/sources/unit_tests.move
new file mode 100644
index 0000000000000..e99a23320453d
--- /dev/null
+++ b/aptos-move/move-examples/token_objects/token_lockup/sources/unit_tests.move
@@ -0,0 +1,170 @@
+module token_objects::unit_tests {
+   #[test_only]
+   use std::signer;
+   #[test_only]
+   use aptos_framework::object;
+   #[test_only]
+   use aptos_framework::account;
+   #[test_only]
+   use aptos_framework::timestamp;
+   #[test_only]
+   use token_objects::token_lockup;
+   #[test_only]
+   use std::string::{Self};
+   #[test_only]
+   use aptos_token_objects::token::{Token};
+
+   const TEST_START_TIME: u64 = 1000000000;
+   // 24 hours in one day * 60 minutes in one hour * 60 seconds in one minute * 7 days
+   const LOCKUP_PERIOD_SECS: u64 = (24 * 60 * 60) * 7;
+
+   #[test_only]
+   fun setup_test(
+       creator: &signer,
+       owner_1: &signer,
+       owner_2: &signer,
+       aptos_framework: &signer,
+       start_time: u64,
+   ) {
+         timestamp::set_time_has_started_for_testing(aptos_framework);
+         timestamp::update_global_time_for_test_secs(start_time);
+         account::create_account_for_test(signer::address_of(creator));
+         account::create_account_for_test(signer::address_of(owner_1));
+         account::create_account_for_test(signer::address_of(owner_2));
+         token_lockup::initialize_collection(creator);
+   }
+
+   #[test_only]
+   fun fast_forward_secs(seconds: u64) {
+      timestamp::update_global_time_for_test_secs(timestamp::now_seconds() + seconds);
+   }
+
+   #[test (creator = @0xFA, owner_1 = @0xA, owner_2 = @0xB, aptos_framework = @0x1)]
+   /// Tests transferring multiple tokens to different owners with slightly different initial lockup times
+   fun test_happy_path(
+      creator: &signer,
+      owner_1: &signer,
+      owner_2: &signer,
+      aptos_framework: &signer,
+   ) {
+      setup_test(
+         creator,
+         owner_1,
+         owner_2,
+         aptos_framework,
+         TEST_START_TIME
+      );
+
+      let owner_1_addr = signer::address_of(owner_1);
+      let owner_2_addr = signer::address_of(owner_2);
+
+      // mint 1 token to each of the 2 owner accounts
+      let token_1_constructor_ref = token_lockup::mint_to(creator, string::utf8(b"Token #1"), owner_1_addr);
+      let token_2_constructor_ref = token_lockup::mint_to(creator, string::utf8(b"Token #2"), owner_2_addr);
+      // mint 1 more token to owner_1 one second later
+      fast_forward_secs(1);
+      let token_3_constructor_ref = token_lockup::mint_to(creator, string::utf8(b"Token #3"), owner_1_addr);
+
+      let token_1_obj = object::object_from_constructor_ref(&token_1_constructor_ref);
+      let token_2_obj = object::object_from_constructor_ref(&token_2_constructor_ref);
+      let token_3_obj = object::object_from_constructor_ref(&token_3_constructor_ref);
+
+      // fast forward global time by 1 week - 1 second
+      fast_forward_secs((LOCKUP_PERIOD_SECS) - 1);
+
+      // ensures that the `last_transfer` for each token is correct
+      assert!(token_lockup::view_last_transfer(token_1_obj) == TEST_START_TIME, 0);
+      assert!(token_lockup::view_last_transfer(token_2_obj) == TEST_START_TIME, 1);
+      assert!(token_lockup::view_last_transfer(token_3_obj) == TEST_START_TIME + 1, 2);
+
+
+      // transfer the first token from owner_1 to owner_2
+      token_lockup::transfer(owner_1, token_1_obj, owner_2_addr);
+      // transfer the second token from owner_2 to owner_1
+      token_lockup::transfer(owner_2, token_2_obj, owner_1_addr);
+      // fast forward global time by 1 second
+      fast_forward_secs(1);
+      // transfer the third token from owner_1 to owner_2
+      token_lockup::transfer(owner_1, token_3_obj, owner_2_addr);
+      // ensures that the `last_transfer` for each token is correct
+      assert!(token_lockup::view_last_transfer(token_1_obj) == TEST_START_TIME + (LOCKUP_PERIOD_SECS), 3);
+      assert!(token_lockup::view_last_transfer(token_2_obj) == TEST_START_TIME + (LOCKUP_PERIOD_SECS), 4);
+      assert!(token_lockup::view_last_transfer(token_3_obj) == TEST_START_TIME + (LOCKUP_PERIOD_SECS) + 1, 5);
+
+      // ensures that the owners respectively are owner_2, owner_1, and owner_2
+      assert!(object::is_owner(token_1_obj, owner_2_addr), 6);
+      assert!(object::is_owner(token_2_obj, owner_1_addr), 7);
+      assert!(object::is_owner(token_3_obj, owner_2_addr), 8);
+   }
+
+   #[test (creator = @0xFA, owner_1 = @0xA, owner_2 = @0xB, aptos_framework = @0x1)]
+   #[expected_failure(abort_code = 0x50003, location = aptos_framework::object)]
+   fun transfer_raw_fail(
+      creator: &signer,
+      owner_1: &signer,
+      owner_2: &signer,
+      aptos_framework: &signer,
+   ) {
+      setup_test(
+         creator,
+         owner_1,
+         owner_2,
+         aptos_framework,
+         TEST_START_TIME
+      );
+
+      let token_1_constructor_ref = token_lockup::mint_to(creator, string::utf8(b"Token #1"), signer::address_of(owner_1));
+      object::transfer_raw(
+         owner_1,
+         object::address_from_constructor_ref(&token_1_constructor_ref),
+         signer::address_of(owner_2)
+      );
+   }
+
+   #[test (creator = @0xFA, owner_1 = @0xA, owner_2 = @0xB, aptos_framework = @0x1)]
+   #[expected_failure(abort_code = 0x50000, location = token_objects::token_lockup)]
+   fun transfer_too_early(
+      creator: &signer,
+      owner_1: &signer,
+      owner_2: &signer,
+      aptos_framework: &signer,
+   ) {
+      setup_test(
+         creator,
+         owner_1,
+         owner_2,
+         aptos_framework,
+         TEST_START_TIME
+      );
+
+      let token_1_constructor_ref = token_lockup::mint_to(creator, string::utf8(b"Token #1"), signer::address_of(owner_1));
+      let token_1_obj = object::object_from_constructor_ref(&token_1_constructor_ref);
+
+      // one second too early
+      fast_forward_secs((LOCKUP_PERIOD_SECS) - 1);
+      token_lockup::transfer(owner_1, token_1_obj, signer::address_of(owner_2));
+   }
+
+   #[test (creator = @0xFA, owner_1 = @0xA, owner_2 = @0xB, aptos_framework = @0x1)]
+   #[expected_failure(abort_code = 0x50001, location = token_objects::token_lockup)]
+   fun transfer_wrong_owner(
+      creator: &signer,
+      owner_1: &signer,
+      owner_2: &signer,
+      aptos_framework: &signer,
+   ) {
+      setup_test(
+         creator,
+         owner_1,
+         owner_2,
+         aptos_framework,
+         TEST_START_TIME
+      );
+
+      let token_1_constructor_ref = token_lockup::mint_to(creator, string::utf8(b"Token #1"), signer::address_of(owner_1));
+      let token_1_obj = object::object_from_constructor_ref(&token_1_constructor_ref);
+
+      fast_forward_secs(LOCKUP_PERIOD_SECS);
+      token_lockup::transfer(owner_2, token_1_obj, signer::address_of(owner_1));
+   }
+}

From 782a5b3141f853a251c9209c15b07a3b9b4fb3d9 Mon Sep 17 00:00:00 2001
From: aldenhu 
Date: Thu, 15 Jun 2023 18:28:59 +0000
Subject: [PATCH 179/200] replay-verify once per day

---
 .github/workflows/replay-verify.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/replay-verify.yaml b/.github/workflows/replay-verify.yaml
index e1ed6a6721510..2bbc6e9d6e0ee 100644
--- a/.github/workflows/replay-verify.yaml
+++ b/.github/workflows/replay-verify.yaml
@@ -23,7 +23,7 @@ on:
       - ".github/workflows/replay-verify.yaml"
       - "testsuite/replay_verify.py"
   schedule:
-    - cron: "0 8,20 * * *"
+    - cron: "0 22 * * *"
   push:
     branches:
       - aptos-release-v* # the aptos release branches

From 9ef8c601875f90a0baf5719d55c68ea80778b6b4 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Thu, 15 Jun 2023 12:40:04 -0700
Subject: [PATCH 180/200] [dashboards] sync grafana dashboards (#8633)

Co-authored-by: rustielin 
---
 dashboards/storage-overview.json    | 549 +++++++++++++---------------
 dashboards/storage-overview.json.gz | Bin 8790 -> 9025 bytes
 dashboards/system.json              | 108 +++---
 dashboards/system.json.gz           | Bin 2585 -> 2961 bytes
 4 files changed, 310 insertions(+), 347 deletions(-)

diff --git a/dashboards/storage-overview.json b/dashboards/storage-overview.json
index 98d5608a84569..41c45e92a298e 100644
--- a/dashboards/storage-overview.json
+++ b/dashboards/storage-overview.json
@@ -31,282 +31,269 @@
   "liveNow": false,
   "panels": [
     {
-      "collapsed": true,
+      "collapsed": false,
       "gridPos": { "h": 1, "w": 24, "x": 0, "y": 0 },
       "id": 3286,
-      "panels": [
+      "panels": [],
+      "title": "Overview",
+      "type": "row"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "PCD0403638111AF12" },
+      "description": "",
+      "gridPos": { "h": 3, "w": 24, "x": 0, "y": 1 },
+      "id": 3266,
+      "options": {
+        "content": "These are basic facts that can be useful for understanding what's happening on chain right now.\r\n\r\nFollow the sections below this to examine the three major focus areas of the storage system health.\r\n",
+        "mode": "markdown"
+      },
+      "pluginVersion": "9.1.1",
+      "type": "text"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "description": "",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": {
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "version",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "drawStyle": "line",
+            "fillOpacity": 0,
+            "gradientMode": "none",
+            "hideFrom": { "legend": false, "tooltip": false, "viz": false },
+            "lineInterpolation": "linear",
+            "lineStyle": { "fill": "solid" },
+            "lineWidth": 1,
+            "pointSize": 5,
+            "scaleDistribution": { "type": "linear" },
+            "showPoints": "never",
+            "spanNulls": false,
+            "stacking": { "group": "A", "mode": "none" },
+            "thresholdsStyle": { "mode": "off" }
+          },
+          "decimals": 0,
+          "links": [],
+          "mappings": [],
+          "thresholds": { "mode": "absolute", "steps": [{ "color": "green", "value": null }] },
+          "unit": "none"
+        },
+        "overrides": [
+          {
+            "matcher": { "id": "byName", "options": "epoch (max)" },
+            "properties": [
+              { "id": "custom.axisPlacement", "value": "hidden" },
+              { "id": "custom.axisLabel", "value": "epoch" },
+              { "id": "custom.lineStyle" },
+              { "id": "color", "value": { "fixedColor": "blue", "mode": "fixed" } },
+              { "id": "custom.lineWidth", "value": 1 },
+              { "id": "custom.axisColorMode", "value": "series" },
+              { "id": "custom.lineStyle", "value": { "dash": [10, 10], "fill": "dash" } },
+              { "id": "custom.axisPlacement", "value": "right" }
+            ]
+          }
+        ]
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 4 },
+      "id": 66,
+      "options": {
+        "legend": { "calcs": ["lastNotNull"], "displayMode": "table", "placement": "right", "showLegend": true },
+        "tooltip": { "mode": "multi", "sort": "none" }
+      },
+      "pluginVersion": "9.1.1",
+      "targets": [
         {
-          "datasource": { "type": "prometheus", "uid": "PCD0403638111AF12" },
-          "description": "",
-          "gridPos": { "h": 3, "w": 24, "x": 0, "y": 1 },
-          "id": 3266,
-          "options": {
-            "content": "These are basic facts that can be useful for understanding what's happening on chain right now.\r\n\r\nFollow the sections below this to examine the three major focus areas of the storage system health.\r\n",
-            "mode": "markdown"
-          },
-          "pluginVersion": "9.1.1",
-          "type": "text"
+          "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+          "editorMode": "code",
+          "expr": "max(aptos_storage_latest_transaction_version{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\"$kubernetes_pod_name\", role=~\"$role\"})",
+          "hide": false,
+          "interval": "",
+          "legendFormat": "latest (synced) (max)",
+          "range": true,
+          "refId": "A"
         },
         {
           "datasource": { "type": "prometheus", "uid": "${Datasource}" },
-          "description": "",
-          "fieldConfig": {
-            "defaults": {
-              "color": { "mode": "palette-classic" },
-              "custom": {
-                "axisCenteredZero": false,
-                "axisColorMode": "text",
-                "axisLabel": "version",
-                "axisPlacement": "auto",
-                "barAlignment": 0,
-                "drawStyle": "line",
-                "fillOpacity": 0,
-                "gradientMode": "none",
-                "hideFrom": { "legend": false, "tooltip": false, "viz": false },
-                "lineInterpolation": "linear",
-                "lineStyle": { "fill": "solid" },
-                "lineWidth": 1,
-                "pointSize": 5,
-                "scaleDistribution": { "type": "linear" },
-                "showPoints": "never",
-                "spanNulls": false,
-                "stacking": { "group": "A", "mode": "none" },
-                "thresholdsStyle": { "mode": "off" }
-              },
-              "decimals": 0,
-              "links": [],
-              "mappings": [],
-              "thresholds": { "mode": "absolute", "steps": [{ "color": "green", "value": null }] },
-              "unit": "none"
-            },
-            "overrides": [
-              {
-                "matcher": { "id": "byName", "options": "epoch (max)" },
-                "properties": [
-                  { "id": "custom.axisPlacement", "value": "hidden" },
-                  { "id": "custom.axisLabel", "value": "epoch" },
-                  { "id": "custom.lineStyle" },
-                  { "id": "color", "value": { "fixedColor": "blue", "mode": "fixed" } },
-                  { "id": "custom.lineWidth", "value": 1 },
-                  { "id": "custom.axisColorMode", "value": "series" },
-                  { "id": "custom.lineStyle", "value": { "dash": [10, 10], "fill": "dash" } },
-                  { "id": "custom.axisPlacement", "value": "right" }
-                ]
-              }
-            ]
-          },
-          "gridPos": { "h": 8, "w": 12, "x": 0, "y": 4 },
-          "id": 66,
-          "options": {
-            "legend": { "calcs": ["lastNotNull"], "displayMode": "table", "placement": "right", "showLegend": true },
-            "tooltip": { "mode": "multi", "sort": "none" }
-          },
-          "pluginVersion": "9.1.1",
-          "targets": [
-            {
-              "datasource": { "type": "prometheus", "uid": "${Datasource}" },
-              "editorMode": "code",
-              "expr": "max(aptos_storage_latest_transaction_version{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\"$kubernetes_pod_name\", role=~\"$role\"})",
-              "hide": false,
-              "interval": "",
-              "legendFormat": "latest (synced) (max)",
-              "range": true,
-              "refId": "A"
-            },
-            {
-              "datasource": { "type": "prometheus", "uid": "${Datasource}" },
-              "editorMode": "code",
-              "expr": "max(aptos_storage_ledger_version{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\"$kubernetes_pod_name\", role=~\"$role\"})",
-              "hide": false,
-              "interval": "",
-              "legendFormat": "committed (max)",
-              "range": true,
-              "refId": "C"
-            },
-            {
-              "datasource": { "type": "prometheus", "uid": "${Datasource}" },
-              "editorMode": "code",
-              "expr": "sort_desc(quantile by (pruner_name) (0.8, aptos_pruner_min_readable_version{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\"$kubernetes_pod_name\", role=~\"$role\", pruner_name !=\"state_store\"}))",
-              "hide": false,
-              "interval": "",
-              "legendFormat": "{{kubernetes_pod_name}} {{pruner_name}} pruned-till (p80)",
-              "range": true,
-              "refId": "B"
-            },
-            {
-              "datasource": { "type": "prometheus", "uid": "${Datasource}" },
-              "editorMode": "code",
-              "exemplar": false,
-              "expr": "max(aptos_storage_next_block_epoch{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\"$kubernetes_pod_name\", role=~\"$role\"})",
-              "hide": false,
-              "legendFormat": "epoch (max)",
-              "range": true,
-              "refId": "D"
-            }
-          ],
-          "title": "latest version, epoch, pruner versions",
-          "type": "timeseries"
+          "editorMode": "code",
+          "expr": "max(aptos_storage_ledger_version{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\"$kubernetes_pod_name\", role=~\"$role\"})",
+          "hide": false,
+          "interval": "",
+          "legendFormat": "committed (max)",
+          "range": true,
+          "refId": "C"
         },
         {
           "datasource": { "type": "prometheus", "uid": "${Datasource}" },
-          "fieldConfig": {
-            "defaults": {
-              "color": { "mode": "palette-classic" },
-              "custom": {
-                "axisCenteredZero": false,
-                "axisColorMode": "text",
-                "axisLabel": "",
-                "axisPlacement": "auto",
-                "barAlignment": 0,
-                "drawStyle": "line",
-                "fillOpacity": 0,
-                "gradientMode": "none",
-                "hideFrom": { "legend": false, "tooltip": false, "viz": false },
-                "lineInterpolation": "linear",
-                "lineWidth": 1,
-                "pointSize": 5,
-                "scaleDistribution": { "type": "linear" },
-                "showPoints": "never",
-                "spanNulls": false,
-                "stacking": { "group": "A", "mode": "none" },
-                "thresholdsStyle": { "mode": "off" }
-              },
-              "links": [],
-              "mappings": [],
-              "thresholds": {
-                "mode": "absolute",
-                "steps": [
-                  { "color": "green", "value": null },
-                  { "color": "red", "value": 80 }
-                ]
-              },
-              "unit": "none"
-            },
-            "overrides": [
-              {
-                "matcher": { "id": "byName", "options": "P50" },
-                "properties": [
-                  { "id": "custom.lineWidth", "value": 5 },
-                  { "id": "color", "value": { "fixedColor": "yellow", "mode": "fixed" } },
-                  { "id": "custom.lineStyle", "value": { "fill": "solid" } }
-                ]
-              }
-            ]
-          },
-          "gridPos": { "h": 8, "w": 12, "x": 12, "y": 4 },
-          "id": 257,
-          "options": {
-            "legend": { "calcs": ["lastNotNull"], "displayMode": "table", "placement": "right", "showLegend": false },
-            "tooltip": { "mode": "multi", "sort": "none" }
+          "editorMode": "code",
+          "expr": "sort_desc(quantile by (pruner_name, tag) (0.8, aptos_pruner_versions{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\"$kubernetes_pod_name\", role=~\"$role\", tag=\"min_readable\"}))",
+          "hide": false,
+          "interval": "",
+          "legendFormat": "{{kubernetes_pod_name}} {{pruner_name}} {{tag}} (p80)",
+          "range": true,
+          "refId": "B"
+        },
+        {
+          "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+          "editorMode": "code",
+          "exemplar": false,
+          "expr": "max(aptos_storage_next_block_epoch{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\"$kubernetes_pod_name\", role=~\"$role\"})",
+          "hide": false,
+          "legendFormat": "epoch (max)",
+          "range": true,
+          "refId": "D"
+        }
+      ],
+      "title": "latest version, epoch, pruner versions",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": {
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "drawStyle": "line",
+            "fillOpacity": 0,
+            "gradientMode": "none",
+            "hideFrom": { "legend": false, "tooltip": false, "viz": false },
+            "lineInterpolation": "linear",
+            "lineWidth": 1,
+            "pointSize": 5,
+            "scaleDistribution": { "type": "linear" },
+            "showPoints": "never",
+            "spanNulls": false,
+            "stacking": { "group": "A", "mode": "none" },
+            "thresholdsStyle": { "mode": "off" }
           },
-          "pluginVersion": "9.1.1",
-          "targets": [
-            {
-              "datasource": { "type": "prometheus", "uid": "${Datasource}" },
-              "editorMode": "code",
-              "expr": "sort_desc(irate(aptos_storage_latest_transaction_version{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\"$kubernetes_pod_name\", role=~\"$role\"}[1m]) < 10000)",
-              "interval": "",
-              "legendFormat": "{{kubernetes_pod_name}}",
-              "range": true,
-              "refId": "A"
-            },
-            {
-              "datasource": { "type": "prometheus", "uid": "${Datasource}" },
-              "editorMode": "code",
-              "expr": "quantile(0.5, (rate(aptos_storage_latest_transaction_version{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\"$kubernetes_pod_name\", role=~\"$role\"}[1m])))",
-              "hide": false,
-              "legendFormat": "P50",
-              "range": true,
-              "refId": "B"
-            }
-          ],
-          "title": "Transactions per second",
-          "type": "timeseries"
+          "links": [],
+          "mappings": [],
+          "thresholds": { "mode": "absolute", "steps": [{ "color": "green" }, { "color": "red", "value": 80 }] },
+          "unit": "none"
         },
+        "overrides": [
+          {
+            "matcher": { "id": "byName", "options": "P50" },
+            "properties": [
+              { "id": "custom.lineWidth", "value": 5 },
+              { "id": "color", "value": { "fixedColor": "yellow", "mode": "fixed" } },
+              { "id": "custom.lineStyle", "value": { "fill": "solid" } }
+            ]
+          }
+        ]
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 4 },
+      "id": 257,
+      "options": {
+        "legend": { "calcs": ["lastNotNull"], "displayMode": "table", "placement": "right", "showLegend": false },
+        "tooltip": { "mode": "multi", "sort": "none" }
+      },
+      "pluginVersion": "9.1.1",
+      "targets": [
         {
           "datasource": { "type": "prometheus", "uid": "${Datasource}" },
-          "fieldConfig": {
-            "defaults": {
-              "color": { "mode": "palette-classic" },
-              "custom": {
-                "axisCenteredZero": false,
-                "axisColorMode": "text",
-                "axisLabel": "",
-                "axisPlacement": "auto",
-                "barAlignment": 0,
-                "drawStyle": "line",
-                "fillOpacity": 0,
-                "gradientMode": "none",
-                "hideFrom": { "legend": false, "tooltip": false, "viz": false },
-                "lineInterpolation": "linear",
-                "lineWidth": 1,
-                "pointSize": 5,
-                "scaleDistribution": { "type": "linear" },
-                "showPoints": "never",
-                "spanNulls": false,
-                "stacking": { "group": "A", "mode": "none" },
-                "thresholdsStyle": { "mode": "off" }
-              },
-              "decimals": 2,
-              "links": [],
-              "mappings": [],
-              "thresholds": {
-                "mode": "absolute",
-                "steps": [
-                  { "color": "green", "value": null },
-                  { "color": "red", "value": 80 }
-                ]
-              },
-              "unit": "none"
-            },
-            "overrides": [
-              {
-                "matcher": { "id": "byName", "options": "P50" },
-                "properties": [
-                  { "id": "custom.lineWidth", "value": 5 },
-                  { "id": "color", "value": { "fixedColor": "yellow", "mode": "fixed" } }
-                ]
-              }
+          "editorMode": "code",
+          "expr": "sort_desc(irate(aptos_storage_latest_transaction_version{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\"$kubernetes_pod_name\", role=~\"$role\"}[1m]) < 10000)",
+          "interval": "",
+          "legendFormat": "{{kubernetes_pod_name}}",
+          "range": true,
+          "refId": "A"
+        },
+        {
+          "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+          "editorMode": "code",
+          "expr": "quantile(0.5, (rate(aptos_storage_latest_transaction_version{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\"$kubernetes_pod_name\", role=~\"$role\"}[1m])))",
+          "hide": false,
+          "legendFormat": "P50",
+          "range": true,
+          "refId": "B"
+        }
+      ],
+      "title": "Transactions per second",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": {
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "drawStyle": "line",
+            "fillOpacity": 0,
+            "gradientMode": "none",
+            "hideFrom": { "legend": false, "tooltip": false, "viz": false },
+            "lineInterpolation": "linear",
+            "lineWidth": 1,
+            "pointSize": 5,
+            "scaleDistribution": { "type": "linear" },
+            "showPoints": "never",
+            "spanNulls": false,
+            "stacking": { "group": "A", "mode": "none" },
+            "thresholdsStyle": { "mode": "off" }
+          },
+          "decimals": 2,
+          "links": [],
+          "mappings": [],
+          "thresholds": { "mode": "absolute", "steps": [{ "color": "green" }, { "color": "red", "value": 80 }] },
+          "unit": "none"
+        },
+        "overrides": [
+          {
+            "matcher": { "id": "byName", "options": "P50" },
+            "properties": [
+              { "id": "custom.lineWidth", "value": 5 },
+              { "id": "color", "value": { "fixedColor": "yellow", "mode": "fixed" } }
             ]
-          },
-          "gridPos": { "h": 8, "w": 12, "x": 0, "y": 12 },
-          "id": 258,
-          "options": {
-            "legend": { "calcs": ["lastNotNull"], "displayMode": "table", "placement": "right", "showLegend": false },
-            "tooltip": { "mode": "multi", "sort": "none" }
-          },
-          "pluginVersion": "9.1.1",
-          "targets": [
-            {
-              "datasource": { "type": "prometheus", "uid": "${Datasource}" },
-              "editorMode": "code",
-              "expr": "sort_desc(rate(aptos_storage_latest_transaction_version{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\"$kubernetes_pod_name\", role=~\"$role\"}[1m]) / on (kubernetes_pod_name, run_uuid) rate(aptos_storage_api_latency_seconds_count{api_name=\"save_transactions\", result=\"Ok\", role=~\"$role\"}[1m]) < 10000)",
-              "hide": false,
-              "interval": "",
-              "legendFormat": "{{kubernetes_pod_name}} ",
-              "range": true,
-              "refId": "A"
-            },
-            {
-              "datasource": { "type": "prometheus", "uid": "${Datasource}" },
-              "editorMode": "code",
-              "expr": "quantile(0.5, rate(aptos_storage_latest_transaction_version{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\"$kubernetes_pod_name\", role=~\"$role\"}[1m]) / on (kubernetes_pod_name, run_uuid) rate(aptos_storage_api_latency_seconds_count{api_name=\"save_transactions\", role=~\"$role\", result=\"Ok\"}[1m]) < 10000)",
-              "hide": false,
-              "legendFormat": "P50",
-              "range": true,
-              "refId": "B"
-            }
-          ],
-          "title": "Transactions per save",
-          "type": "timeseries"
+          }
+        ]
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 12 },
+      "id": 258,
+      "options": {
+        "legend": { "calcs": ["lastNotNull"], "displayMode": "table", "placement": "right", "showLegend": false },
+        "tooltip": { "mode": "multi", "sort": "none" }
+      },
+      "pluginVersion": "9.1.1",
+      "targets": [
+        {
+          "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+          "editorMode": "code",
+          "expr": "sort_desc(rate(aptos_storage_latest_transaction_version{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\"$kubernetes_pod_name\", role=~\"$role\"}[1m]) / on (kubernetes_pod_name, run_uuid) rate(aptos_storage_api_latency_seconds_count{api_name=\"save_transactions\", result=\"Ok\", role=~\"$role\"}[1m]) < 10000)",
+          "hide": false,
+          "interval": "",
+          "legendFormat": "{{kubernetes_pod_name}} ",
+          "range": true,
+          "refId": "A"
+        },
+        {
+          "datasource": { "type": "prometheus", "uid": "${Datasource}" },
+          "editorMode": "code",
+          "expr": "quantile(0.5, rate(aptos_storage_latest_transaction_version{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", kubernetes_pod_name=~\"$kubernetes_pod_name\", role=~\"$role\"}[1m]) / on (kubernetes_pod_name, run_uuid) rate(aptos_storage_api_latency_seconds_count{api_name=\"save_transactions\", role=~\"$role\", result=\"Ok\"}[1m]) < 10000)",
+          "hide": false,
+          "legendFormat": "P50",
+          "range": true,
+          "refId": "B"
         }
       ],
-      "title": "Overview",
-      "type": "row"
+      "title": "Transactions per save",
+      "type": "timeseries"
     },
     {
       "collapsed": true,
-      "gridPos": { "h": 1, "w": 24, "x": 0, "y": 1 },
+      "gridPos": { "h": 1, "w": 24, "x": 0, "y": 20 },
       "id": 3288,
       "panels": [
         {
@@ -330,7 +317,7 @@
               "thresholds": {
                 "mode": "absolute",
                 "steps": [
-                  { "color": "green", "value": null },
+                  { "color": "green" },
                   { "color": "#EAB839", "value": 100000 },
                   { "color": "red", "value": 1000000 }
                 ]
@@ -403,7 +390,7 @@
                 "thresholdsStyle": { "mode": "off" }
               },
               "mappings": [],
-              "thresholds": { "mode": "absolute", "steps": [{ "color": "green", "value": null }] },
+              "thresholds": { "mode": "absolute", "steps": [{ "color": "green" }] },
               "unit": "none"
             },
             "overrides": [
@@ -481,13 +468,7 @@
               },
               "decimals": 0,
               "mappings": [],
-              "thresholds": {
-                "mode": "absolute",
-                "steps": [
-                  { "color": "green", "value": null },
-                  { "color": "red", "value": 80 }
-                ]
-              },
+              "thresholds": { "mode": "absolute", "steps": [{ "color": "green" }, { "color": "red", "value": 80 }] },
               "unit": "bytes"
             },
             "overrides": [
@@ -575,7 +556,7 @@
                 "thresholdsStyle": { "mode": "off" }
               },
               "mappings": [],
-              "thresholds": { "mode": "absolute", "steps": [{ "color": "green", "value": null }] },
+              "thresholds": { "mode": "absolute", "steps": [{ "color": "green" }] },
               "unit": "short"
             },
             "overrides": [
@@ -646,7 +627,7 @@
                 "thresholdsStyle": { "mode": "off" }
               },
               "mappings": [],
-              "thresholds": { "mode": "absolute", "steps": [{ "color": "green", "value": null }] },
+              "thresholds": { "mode": "absolute", "steps": [{ "color": "green" }] },
               "unit": "bytes"
             },
             "overrides": [
@@ -717,13 +698,7 @@
               },
               "links": [],
               "mappings": [],
-              "thresholds": {
-                "mode": "absolute",
-                "steps": [
-                  { "color": "green", "value": null },
-                  { "color": "red", "value": 80 }
-                ]
-              },
+              "thresholds": { "mode": "absolute", "steps": [{ "color": "green" }, { "color": "red", "value": 80 }] },
               "unit": "decbytes"
             },
             "overrides": [
@@ -797,7 +772,7 @@
               "decimals": 0,
               "links": [],
               "mappings": [],
-              "thresholds": { "mode": "absolute", "steps": [{ "color": "green", "value": null }] },
+              "thresholds": { "mode": "absolute", "steps": [{ "color": "green" }] },
               "unit": "decbytes"
             },
             "overrides": [
@@ -902,7 +877,7 @@
               "decimals": 0,
               "links": [],
               "mappings": [],
-              "thresholds": { "mode": "absolute", "steps": [{ "color": "green", "value": null }] },
+              "thresholds": { "mode": "absolute", "steps": [{ "color": "green" }] },
               "unit": "decbytes"
             },
             "overrides": [
@@ -1006,7 +981,7 @@
               "decimals": 0,
               "links": [],
               "mappings": [],
-              "thresholds": { "mode": "absolute", "steps": [{ "color": "green", "value": null }] },
+              "thresholds": { "mode": "absolute", "steps": [{ "color": "green" }] },
               "unit": "decbytes"
             },
             "overrides": [
@@ -1126,13 +1101,7 @@
                 "thresholdsStyle": { "mode": "off" }
               },
               "mappings": [],
-              "thresholds": {
-                "mode": "absolute",
-                "steps": [
-                  { "color": "green", "value": null },
-                  { "color": "red", "value": 80 }
-                ]
-              },
+              "thresholds": { "mode": "absolute", "steps": [{ "color": "green" }, { "color": "red", "value": 80 }] },
               "unit": "bytes"
             },
             "overrides": []
@@ -1174,7 +1143,7 @@
     },
     {
       "collapsed": true,
-      "gridPos": { "h": 1, "w": 24, "x": 0, "y": 2 },
+      "gridPos": { "h": 1, "w": 24, "x": 0, "y": 21 },
       "id": 3292,
       "panels": [
         {
@@ -2155,7 +2124,7 @@
     },
     {
       "collapsed": true,
-      "gridPos": { "h": 1, "w": 24, "x": 0, "y": 3 },
+      "gridPos": { "h": 1, "w": 24, "x": 0, "y": 22 },
       "id": 3294,
       "panels": [
         {
@@ -2327,8 +2296,8 @@
       "type": "row"
     }
   ],
-  "refresh": false,
-  "schemaVersion": 37,
+  "refresh": "",
+  "schemaVersion": 38,
   "style": "dark",
   "tags": ["aptos-core"],
   "templating": {
@@ -2611,6 +2580,6 @@
   "timezone": "",
   "title": "storage-overview",
   "uid": "ptUp6Vn4k",
-  "version": 5,
+  "version": 6,
   "weekStart": ""
 }
diff --git a/dashboards/storage-overview.json.gz b/dashboards/storage-overview.json.gz
index cba94495d6f269166e078d6c9aa22940cc0bd9e8..95b9845ebb2d5e9f174f6e9198885028640a2de7 100644
GIT binary patch
literal 9025
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
z
ziArS^W!VrSio!L95HqZ+GKOYXo1H&B62B?z4$oK3aW%(Hyrem21qU2Y0KVb0nX$!e05ilkqOlS=b|tdWGAqA_`EnBC`WH8nP9fkaFj#(6>g1tj~+
zAO-8@F3N^Vk(d_sE4dS`MqVYo|LPb*^c?Krb64~UK>n~Oww6$-B;%d
z$YA>s2O1_BFk#1KBWy1QkjuINBsS^)IkddUaWOq_JP3v!poDY*43&dsYY#CP@rXX4
zgy_(SfUhx@_K;Lj^vj0_gZfgYgM~t^RIFudd!$mqGkvlf&^a#jOiSg@c|J8z1yPCn
zz!ie573l=I=HZv9-EsYHuT9Bf4beEOWJ}{oUjEIAkgMt=BrUf#lMyYZPgZG!aw6oq
z?g&|LL9yVi*mRjaCo+Do3o_P?5HARZ1%$!JnfI0WGK{zO9z&d{jl6I3a@iy0{yK2vQ#){Qd8~!XwfRA-HlL(w>ate&k=jRvH%QkXdQqvaZ8-SaFhimj>|R8>GAo1~rzs%c
zowNpyngQ0A6fd}4*={SvP-z_XSE4sNzxe}QT13KCS9f?j>~?V&;t*CH+wsFY#0c4r
zR`;b}(0qg?SXVw$b9J9|wC!*#vI1;nb(@}PO4FJ|X-xBdJuVE;I>Ak3JrICH==l#1
z#$Uahn!ycdmifqF&GeguHgYD0zF4U{BC5q6>CQ7%P9l(RL)Ruh&*;JU;=s$S%P)tm0HhL2R)a0I$61){2b!oH7(0h(aK(lkz^)9A2FFzjOOmm
zD8c6Lf6ZOdp7h}k`i{tv*XFLAX4rEEUjz5{)$1y%KDt0R4iZS01oT#_LnP#-nEHkD
z_?c9X(sDH3Vzc&RR+ou>5&6y1D?mBFTb|YEIFB@}VJka#N@wJ6G-z*1723KCj0DQl`Wy-O&@B#t+7D9bm%^7Y01^-(3d)@YhC~MX
z1;k16vtT+4$-I~nMq;&0gG4q2RvHW}%L9q^NM&F6Srptz#%4q$uq8zdLwv_Hlr-}K
zP`6TPo9M;v_pxDLFy43$ML;ettQvJZJ}2-F3jyAN23}s^<=jmw4~itq1+bXA{AzTH
z+!v9H`y!DK561Sx!}GhH2V-AjwrtFHtZr{OXmb^D-0fupHkI!@_*GKU8Eb{qfX*mg
z8sGDf#C`19)Rsi!d=;|UCnjWcVG@M$G4Jw_PV*{GIA>Qt4dpodMaaYc-kOW%k)0Xe
z1SdVc8tqtu7uub|NNm;)E6<_`78{pVjYS^6?ktx665BFbFDd|7t9@tojfUqxH;(8X
zE|Jfl4e8~9)9talNw(xBX$$*fW>IoN(PbXcpCk5TQZaBs|C;RQ=zu-Z><;N)(>8dw
z((Kw&cPGDPADyy~*tdtr?1viOo!Kl0NH0;_e~1m4XvEm$hKsNUvB7(C@H30%<6{tg
n9h}~K$J}t{X=GeOeE=BG824_8Qi-O!^|tjt8f?vLpS}SA1g2q{

literal 8790
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
M1M$&U#Z<)s0BZXE!2kdN

diff --git a/dashboards/system.json b/dashboards/system.json
index 89b58bdde6041..c3c332050b6f2 100644
--- a/dashboards/system.json
+++ b/dashboards/system.json
@@ -48,46 +48,49 @@
   "liveNow": false,
   "panels": [
     {
-      "aliasColors": {},
-      "bars": false,
-      "dashLength": 10,
-      "dashes": false,
       "datasource": { "type": "prometheus", "uid": "${Datasource}" },
-      "editable": false,
-      "error": false,
-      "fieldConfig": { "defaults": { "unit": "" }, "overrides": [] },
-      "fill": 0,
-      "fillGradient": 0,
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": {
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "drawStyle": "line",
+            "fillOpacity": 0,
+            "gradientMode": "none",
+            "hideFrom": { "legend": false, "tooltip": false, "viz": false },
+            "lineInterpolation": "linear",
+            "lineWidth": 1,
+            "pointSize": 5,
+            "scaleDistribution": { "type": "linear" },
+            "showPoints": "never",
+            "spanNulls": false,
+            "stacking": { "group": "A", "mode": "none" },
+            "thresholdsStyle": { "mode": "off" }
+          },
+          "mappings": [],
+          "min": 0,
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              { "color": "green", "value": null },
+              { "color": "red", "value": 80 }
+            ]
+          },
+          "unit": "percentunit"
+        },
+        "overrides": []
+      },
       "gridPos": { "h": 11, "w": 8, "x": 0, "y": 0 },
-      "hiddenSeries": false,
       "id": 6,
-      "legend": {
-        "alignAsTable": false,
-        "avg": false,
-        "current": false,
-        "hideEmpty": false,
-        "hideZero": false,
-        "max": false,
-        "min": false,
-        "rightSide": false,
-        "show": false,
-        "total": false,
-        "values": false
+      "options": {
+        "legend": { "calcs": [], "displayMode": "list", "placement": "bottom", "showLegend": false },
+        "tooltip": { "mode": "multi", "sort": "none" }
       },
-      "lines": true,
-      "linewidth": 1,
-      "nullPointMode": "null",
-      "options": { "alertThreshold": true },
-      "percentage": false,
-      "pluginVersion": "10.0.0-cloud.3.b04cc88b",
-      "pointradius": 2,
-      "points": false,
-      "renderer": "flot",
-      "seriesOverrides": [],
-      "spaceLength": 10,
-      "span": 0,
-      "stack": false,
-      "steppedLine": false,
+      "pluginVersion": "10.0.1-cloud.2.a7a20fbf",
       "targets": [
         {
           "expr": "rate(container_cpu_usage_seconds_total{chain_name=~\"$chain_name\", cluster=~\"$cluster\", metrics_source=~\"$metrics_source\", namespace=~\"$namespace\", container=~\"$container\"}[$interval])",
@@ -97,17 +100,8 @@
           "refId": "A"
         }
       ],
-      "thresholds": [],
-      "timeRegions": [],
       "title": "CPU Usage",
-      "tooltip": { "shared": true, "sort": 0, "value_type": "individual" },
-      "type": "graph",
-      "xaxis": { "format": "", "logBase": 0, "mode": "time", "show": true, "values": [] },
-      "yaxes": [
-        { "format": "percentunit", "logBase": 1, "min": 0, "show": true },
-        { "format": "short", "logBase": 1, "show": true }
-      ],
-      "yaxis": { "align": false }
+      "type": "timeseries"
     },
     {
       "aliasColors": {},
@@ -141,7 +135,7 @@
       "nullPointMode": "null",
       "options": { "alertThreshold": true },
       "percentage": false,
-      "pluginVersion": "10.0.0-cloud.3.b04cc88b",
+      "pluginVersion": "10.0.1-cloud.2.a7a20fbf",
       "pointradius": 2,
       "points": false,
       "renderer": "flot",
@@ -203,7 +197,7 @@
       "nullPointMode": "null",
       "options": { "alertThreshold": true },
       "percentage": false,
-      "pluginVersion": "10.0.0-cloud.3.b04cc88b",
+      "pluginVersion": "10.0.1-cloud.2.a7a20fbf",
       "pointradius": 2,
       "points": false,
       "renderer": "flot",
@@ -268,7 +262,7 @@
       "nullPointMode": "null",
       "options": { "alertThreshold": true },
       "percentage": false,
-      "pluginVersion": "10.0.0-cloud.3.b04cc88b",
+      "pluginVersion": "10.0.1-cloud.2.a7a20fbf",
       "pointradius": 2,
       "points": false,
       "renderer": "flot",
@@ -333,7 +327,7 @@
       "nullPointMode": "null",
       "options": { "alertThreshold": true },
       "percentage": false,
-      "pluginVersion": "10.0.0-cloud.3.b04cc88b",
+      "pluginVersion": "10.0.1-cloud.2.a7a20fbf",
       "pointradius": 2,
       "points": false,
       "renderer": "flot",
@@ -397,7 +391,7 @@
       "nullPointMode": "null",
       "options": { "alertThreshold": true },
       "percentage": false,
-      "pluginVersion": "10.0.0-cloud.3.b04cc88b",
+      "pluginVersion": "10.0.1-cloud.2.a7a20fbf",
       "pointradius": 2,
       "points": false,
       "renderer": "flot",
@@ -459,7 +453,7 @@
       "nullPointMode": "null",
       "options": { "alertThreshold": true },
       "percentage": false,
-      "pluginVersion": "10.0.0-cloud.3.b04cc88b",
+      "pluginVersion": "10.0.1-cloud.2.a7a20fbf",
       "pointradius": 2,
       "points": false,
       "renderer": "flot",
@@ -521,7 +515,7 @@
       "nullPointMode": "null",
       "options": { "alertThreshold": true },
       "percentage": false,
-      "pluginVersion": "10.0.0-cloud.3.b04cc88b",
+      "pluginVersion": "10.0.1-cloud.2.a7a20fbf",
       "pointradius": 2,
       "points": false,
       "renderer": "flot",
@@ -555,7 +549,7 @@
       "yaxis": { "align": false }
     }
   ],
-  "refresh": false,
+  "refresh": "",
   "schemaVersion": 38,
   "style": "dark",
   "tags": ["aptos-core"],
@@ -730,8 +724,8 @@
         "multiFormat": "",
         "name": "interval",
         "options": [
-          { "selected": false, "text": "auto", "value": "$__auto_interval_interval" },
-          { "selected": true, "text": "1m", "value": "1m" },
+          { "selected": true, "text": "auto", "value": "$__auto_interval_interval" },
+          { "selected": false, "text": "1m", "value": "1m" },
           { "selected": false, "text": "5m", "value": "5m" },
           { "selected": false, "text": "10m", "value": "10m" },
           { "selected": false, "text": "30m", "value": "30m" },
@@ -760,6 +754,6 @@
   "timezone": "",
   "title": "system",
   "uid": "system",
-  "version": 2,
+  "version": 3,
   "weekStart": ""
 }
diff --git a/dashboards/system.json.gz b/dashboards/system.json.gz
index aec70bf782cf8f87424b0ee029d2ab7e1d1d77e1..c0fabd47711064bea06b60fed605a5058518ef10 100644
GIT binary patch
literal 2961
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
H@?ih~J1n9|

literal 2585
zcmV+!3g-16iwFP!000001MOUGZ`(K${@!092)RR=v%OZ{x4`0%Z8nSEZeMQG2Dobr
zftF~S8;Mj&Dv8(U{p~v>^+s7~qFjXSR+XpAUwdybouP)YiI
z=Vv2y`hC|~RFq(fMv-bJd5SCYDG3{-Bw+Lx^cMc-VrKr}Eh)=LIbBIVx)JJa!irpB=V0u7jAQ+=a;GU{HQ6~HNxmQj&
zL}EH(h==ynmW#8pqSE|oV^-v)J#!0R%aZsa(dKe*YDZQ1nEats4=dt`P+aJ^iQT`X
zn9u5s#gv`@3YrU(SBfM~>eXR6e!(-*AQndiN8xh89j!IKkj)*c0>(l6QVEd}zNF|<
zYub$3iefTI6k#E)UN@-?G!nlGI~PBMMZSR_f3yR%x!Q&D(+4oVk^
zL(Y0#W;CS;yO%?F_g-;a*DZgm`}U}
z%(790v5K8}S&U(Vsi-*f+WfGnzNnz8y12G_%(?bDTRK+od&%gSOiZsK9-}mp!rY~l7@R>5
zj?2zK34~aK?@Fg*5=B)<*8&LMA;DBy1ruohj%C`lT_Ak8%KH0oz0h?XSNYShq95XV
zi0Lurq`_|5AiKqFgeRDWMS{xLZ9)&k`zFJv;^a9H1kuO$k`=j|HYg&
z6vgPGNlIvgl#|I+9-DNw6w;9FJXDCWbv(>YSj>txKn
zj8F&=LB%8;Y}l>n|JWR4_Whe#?BsNsH)q<$*EioU=g4TY~^
zFb}3s?yIEw!=Inrwet281Q7_dFcxk~%x5KrD8or0d=pi4sV!2Kln!kOU0&R2wfU%w
z;{5KDyZE>U>wq~R@pF|Vs6bJqG6@0RH}g70R4U%Pua^1<9OmTpHf_{uzr>m98a{
z!cPSbzv1RXqCf%4s5GMrB1B?UZLrZ_FR91#J|1iU|8Tx@8fOt8P)OwL;mqXzm{jAy
zR)$p_5^-v1mGiepO{~7b$w^0(9t=&|zZp&1>}XO)lRBEz(WI}Di)o`fHFAb*$cu$D
zpDR0Xiebt=PzgQ56=V%hgfoOVxRrC8jxdzL;6W3H;>@NkW7zH(L&q2%Gh=wLU$=0+
zD+_&*;2#Qe!N9
zj?n}7frj%BXL;!7oT#V&RUi939;K-33yX}vU5L*}u)H^N$Gqg#Tjwo!Y4+3Xr$I{y
zOS&D9j*HZGKw6R!ulw0(M@Aks8EF+D-hIEjf3$tH|NY+P(eB~i_Tf#>O=|psVyQM<
zfd2%ToME$l@eR2Iy_LmA3NZLiem3&B?o`cvHd--zYRtYnC|c^^pe4iy(Al8Ju6IChO*iQ^;!qDv=5s{YC=
zh)@(Yzbgd_PL$#6@-lf_QB>dv2eL#^wM@OMMX5O<%83YiZJgQpIbtIeIqPp2?Z*%o
zAdu8N^ei92wVIaBQ=<*l6yg-`Q8|d3l6r(jII2%N2JS|hD29?Z+b@4x&tc_7LuF~1
z(MyMQDzEOTCZAeyc|14-s5FT)Llo73eG%Tll!8uS_V0
zPk`2E#L8`fz}kDIZX1Ah>TCf*%fAa`>f!k&Ca+Tn+&)+;z(T0+esJll7!HqcwIu%h
zlE?jHi6{iM@B{%E;ThuJx|>Evz5?R6g4{3F?r#j*t09|(EE}k~aK+$x*8#Gmg!hBZ
zYp_dzZ#k+JgsyjI(7jH)Rj{ytyXO0#W7Tkb$6+;lURfE;Rw29esI@4bwN?<#cNd7C
zD4J_^uL0)b@%drE`I4Q3MP*lD1#y0NQTu9?!-5b1G2<52E%}N8z7_3gkN9Hystw{V
z!+H6YVr7*AYvnUnzo^mAf!8<4d$fqF$JLK{V7(8ZrOEu#{lUfRgx!RNH-z666Kn*b
z74m-4`_z3q47LH|V58wH?>~HU*9RN_eE!M3!B)ckpcSQ(Eiaam`TpW
zdP8wF@O1}Ej6!M2H=c6{Bi~WF?)>t^GdJRk_Wl4bXo6b+y^}FG(y_LtQ!r}5rs;}ky&ZT*ExH|rTbfKRJ*m-|Tue=VI>fWtXPDpU7k9o5LhHMgr
zXPdJL9WRyH^u>6v@kGyDGRH9ZHb4V_WOg;Da+L^Vw>6CnxHFJ$Zkvl3jAkH0Ac_Dk?0mX


From 3df73160a8656d42586aa573f616b7e624fdbdb3 Mon Sep 17 00:00:00 2001
From: Stelian Ionescu 
Date: Thu, 15 Jun 2023 16:05:50 -0400
Subject: [PATCH 181/200] [Helm] Fix loadtest cronjob (#8643)

---
 .../testnet-addons/templates/loadtest.yaml    | 46 +++++++++++++------
 terraform/helm/testnet-addons/values.yaml     |  6 +++
 2 files changed, 38 insertions(+), 14 deletions(-)

diff --git a/terraform/helm/testnet-addons/templates/loadtest.yaml b/terraform/helm/testnet-addons/templates/loadtest.yaml
index 845a87579a4b7..c1a61feca8f44 100644
--- a/terraform/helm/testnet-addons/templates/loadtest.yaml
+++ b/terraform/helm/testnet-addons/templates/loadtest.yaml
@@ -16,8 +16,6 @@ spec:
           labels:
             {{- include "testnet-addons.selectorLabels" . | nindent 12 }}
             app.kubernetes.io/name: load-test
-          annotations:
-            seccomp.security.alpha.kubernetes.io/pod: runtime/default
         spec:
           restartPolicy: Never
           priorityClassName: {{ include "testnet-addons.fullname" . }}-high
@@ -26,7 +24,7 @@ spec:
             image: {{ .Values.load_test.image.repo }}:{{ .Values.load_test.image.tag | default .Values.imageTag }}
             imagePullPolicy: {{ .Values.load_test.image.pullPolicy }}
             command:
-            - transaction-emitter
+            - aptos-transaction-emitter
             - emit-tx
             - --mint-key={{ .Values.load_test.config.mint_key }}
             - --chain-id={{ .Values.genesis.chain_id }}
@@ -34,25 +32,36 @@ spec:
             {{- $numTargets := 0 }}
             {{- $targetSuffix := "" }}
             {{- $targetGroups := list }}
-            {{- if $.Values.load_test.config.use_validators }}
+            {{- if $.Values.load_test.config.use_pfns }}
+              {{- $numTargets = $.Values.load_test.config.numFullnodeGroups }}
+              {{- $targetSuffix = "fullnode" }}
+              {{- $targetGroups = list }}
+            {{- else if $.Values.load_test.config.use_validators }}
               {{- $numTargets = $.Values.genesis.numValidators }}
               {{- $targetSuffix = "validator" }}
               {{- $targetGroups = list }}
             {{- else }}
               {{- $numTargets = $.Values.load_test.config.numFullnodeGroups }}
               {{- $targetSuffix = "fullnode" }}
-              {{- $targetGroups = $.Values.load_test.fullnodeGroups }}
+              {{- $targetGroups = $.Values.load_test.fullnode.groups }}
             {{- end }}
-            {{- range $i := until (int $numTargets) }}
-              {{- $port := 80 }}
-              {{- if $targetGroups }}
-              {{- range $group := $targetGroups }}
-              {{- $nodeName := join "-" (list $.Values.genesis.username_prefix $i $group.name "lb") }}
-            - --targets=http://{{ $nodeName }}:{{ $port }}
+            {{- if $.Values.load_test.config.use_pfns }}
+              {{- range $i := until (int $numTargets) }}
+            - --targets=http://{{ printf "fullnode%d.%s" $i $.Values.service.domain }}
+            # - --targets=https://{{ printf "%s" $.Values.service.domain }}
               {{- end }}
-              {{- else }}
-              {{- $nodeName := join "-" (list $.Values.genesis.username_prefix $i $targetSuffix "lb") }}
+            {{- else }}
+              {{- range $i := until (int $numTargets) }}
+                {{- $port := 80 }}
+                {{- if $targetGroups }}
+                {{- range $group := $targetGroups }}
+                {{- $nodeName := join "-" (list $.Values.genesis.username_prefix $i $group.name "lb") }}
+            - --targets=http://{{ $nodeName }}:{{ $port }}
+                {{- end }}
+                {{- else }}
+                {{- $nodeName := join "-" (list $.Values.genesis.username_prefix $i $targetSuffix "lb") }}
             - --targets=http://{{ $nodeName }}:{{ $port }}
+               {{- end }}
               {{- end }}
             {{- end }}
           {{- with .Values.load_test }}
@@ -63,10 +72,14 @@ spec:
             - --mempool-backlog={{ .config.mempool_backlog }}
             {{- end }}
             - --duration={{ .config.duration }}
+            # - --delay-after-minting=300
+            - --expected-max-txns={{ .config.expected_max_txns }}
             - --txn-expiration-time-secs={{ .config.txn_expiration_time_secs }}
+            - --max-transactions-per-account={{ .config.max_transactions_per_account }}
+            - --transaction-type={{ .config.transaction_type }}
             env:
             - name: RUST_BACKTRACE
-              value: "1"
+              value: "full"
             - name: REUSE_ACC
               value: "1"
             {{- with .resources }}
@@ -79,6 +92,8 @@ spec:
               capabilities:
                 drop:
                 - ALL
+              seccompProfile:
+                type: RuntimeDefault
           {{- with .nodeSelector }}
           nodeSelector:
             {{- toYaml . | nindent 12 }}
@@ -96,6 +111,9 @@ spec:
             runAsUser: 6180
             runAsGroup: 6180
             fsGroup: 6180
+            # sysctls:
+            # - name: net.ipv4.tcp_tw_reuse
+            #   value: "1"
           {{- end }}
           serviceAccountName: {{ include "testnet-addons.serviceAccountName" . }}
           {{- if .Values.imagePullSecret }}
diff --git a/terraform/helm/testnet-addons/values.yaml b/terraform/helm/testnet-addons/values.yaml
index f407c62591e2b..bd5d5b9900935 100644
--- a/terraform/helm/testnet-addons/values.yaml
+++ b/terraform/helm/testnet-addons/values.yaml
@@ -69,6 +69,12 @@ load_test:
     txn_expiration_time_secs: 30
     # -- Whether to submit transactions through validator REST API
     use_validators: false
+    # -- If true, run $numFullnodeGroups parallel load tests
+    use_pfns: true
+    # -- Default 20k * $duration
+    expected_max_txns: 6000000
+    max_transactions_per_account: 5
+    transaction_type: coin-transfer
 
 serviceAccount:
   # -- Specifies whether a service account should be created

From 3aaedca04d916188e02e7c5a15e98836b3a6b751 Mon Sep 17 00:00:00 2001
From: Rati Gelashvili 
Date: Fri, 16 Jun 2023 01:47:32 +0400
Subject: [PATCH 182/200] Separate speculative logging errors out in alerting
 (lower priority) (#8615)

---
 aptos-move/aptos-vm-logging/src/counters.rs | 10 +++++++
 aptos-move/aptos-vm-logging/src/lib.rs      | 31 +++++++++++++++------
 2 files changed, 33 insertions(+), 8 deletions(-)

diff --git a/aptos-move/aptos-vm-logging/src/counters.rs b/aptos-move/aptos-vm-logging/src/counters.rs
index 106541e018e35..ee3f54dcabfb5 100644
--- a/aptos-move/aptos-vm-logging/src/counters.rs
+++ b/aptos-move/aptos-vm-logging/src/counters.rs
@@ -9,3 +9,13 @@ use once_cell::sync::Lazy;
 pub static CRITICAL_ERRORS: Lazy = Lazy::new(|| {
     register_int_counter!("aptos_vm_critical_errors", "Number of critical errors").unwrap()
 });
+
+/// Count the number of errors within the speculative logging logic / implementation.
+/// Intended to trigger lower priority / urgency alerts.
+pub static SPECULATIVE_LOGGING_ERRORS: Lazy = Lazy::new(|| {
+    register_int_counter!(
+        "aptos_vm_speculative_logging_errors",
+        "Number of errors in speculative logging implementation"
+    )
+    .unwrap()
+});
diff --git a/aptos-move/aptos-vm-logging/src/lib.rs b/aptos-move/aptos-vm-logging/src/lib.rs
index f7ccae76dec36..57637ba18a513 100644
--- a/aptos-move/aptos-vm-logging/src/lib.rs
+++ b/aptos-move/aptos-vm-logging/src/lib.rs
@@ -11,7 +11,10 @@ pub mod prelude {
     };
 }
 
-use crate::{counters::CRITICAL_ERRORS, log_schema::AdapterLogSchema};
+use crate::{
+    counters::{CRITICAL_ERRORS, SPECULATIVE_LOGGING_ERRORS},
+    log_schema::AdapterLogSchema,
+};
 use aptos_logger::{prelude::*, Level};
 use aptos_speculative_state_helper::{SpeculativeEvent, SpeculativeEvents};
 use arc_swap::ArcSwapOption;
@@ -98,11 +101,11 @@ pub fn speculative_log(level: Level, context: &AdapterLogSchema, message: String
             Some(log_events) => {
                 let log_event = VMLogEntry::new(level, context.clone(), message);
                 if let Err(e) = log_events.record(txn_idx, log_event) {
-                    alert!("{:?}", e);
+                    speculative_alert!("{:?}", e);
                 };
             },
             None => {
-                alert!(
+                speculative_alert!(
                     "Speculative state not initialized to log message = {}",
                     message
                 );
@@ -120,14 +123,16 @@ pub fn flush_speculative_logs(num_to_flush: usize) {
             match Arc::try_unwrap(log_events_ptr) {
                 Ok(log_events) => log_events.flush(num_to_flush),
                 Err(_) => {
-                    alert!("Speculative log storage must be uniquely owned to flush");
+                    speculative_alert!("Speculative log storage must be uniquely owned to flush");
                 },
             };
         },
         None => {
             if !speculation_disabled() {
                 // Alert only if speculation is not disabled.
-                alert!("Clear all logs called on uninitialized speculative log storage");
+                speculative_alert!(
+                    "Clear all logs called on uninitialized speculative log storage"
+                );
             }
         },
     }
@@ -139,19 +144,21 @@ pub fn clear_speculative_txn_logs(txn_idx: usize) {
     match &*BUFFERED_LOG_EVENTS.load() {
         Some(log_events) => {
             if let Err(e) = log_events.clear_txn_events(txn_idx) {
-                alert!("{:?}", e);
+                speculative_alert!("{:?}", e);
             };
         },
         None => {
             if !speculation_disabled() {
                 // Alert only if speculation is not disabled.
-                alert!("Clear all logs called on uninitialized speculative log storage");
+                speculative_alert!(
+                    "Clear all logs called on uninitialized speculative log storage"
+                );
             }
         },
     }
 }
 
-/// Combine logging and error and incrementing critical errors counter for alerting.
+/// Alert for vm critical errors.
 #[macro_export]
 macro_rules! alert {
     ($($args:tt)+) => {
@@ -160,6 +167,14 @@ macro_rules! alert {
     };
 }
 
+#[macro_export]
+macro_rules! speculative_alert {
+    ($($args:tt)+) => {
+	warn!($($args)+);
+	SPECULATIVE_LOGGING_ERRORS.inc();
+    };
+}
+
 #[macro_export]
 macro_rules! speculative_error {
     ($($args:tt)+) => {

From 989e4efe6db448d31c4bbdb8549ed3d8fce6e40f Mon Sep 17 00:00:00 2001
From: danielx <66756900+danielxiangzl@users.noreply.github.com>
Date: Thu, 15 Jun 2023 14:53:35 -0700
Subject: [PATCH 183/200] [Executor][GasMeter] Add Fee Statement in VM output
 (#8635)

---
 .../aptos-gas-profiling/src/profiler.rs       |   8 +
 aptos-move/aptos-gas/src/gas_meter.rs         |  36 ++++
 aptos-move/aptos-vm-types/src/output.rs       |  27 ++-
 aptos-move/aptos-vm-types/src/tests/utils.rs  |   3 +-
 aptos-move/aptos-vm/src/aptos_vm.rs           |  35 ++--
 aptos-move/aptos-vm/src/aptos_vm_impl.rs      |  11 +-
 aptos-move/aptos-vm/src/block_executor/mod.rs |  12 ++
 aptos-move/block-executor/src/counters.rs     |  98 +++++++---
 aptos-move/block-executor/src/executor.rs     | 184 +++++++++++++++---
 .../src/proptest_types/types.rs               |   5 +
 aptos-move/block-executor/src/task.rs         |   4 +
 .../src/txn_last_input_output.rs              |  10 +-
 storage/aptosdb/src/fake_aptosdb.rs           |   2 +-
 types/src/fee_statement.rs                    |  88 +++++++++
 types/src/lib.rs                              |   1 +
 15 files changed, 436 insertions(+), 88 deletions(-)
 create mode 100644 types/src/fee_statement.rs

diff --git a/aptos-move/aptos-gas-profiling/src/profiler.rs b/aptos-move/aptos-gas-profiling/src/profiler.rs
index e96a9819d4b31..92ea37e82e4f0 100644
--- a/aptos-move/aptos-gas-profiling/src/profiler.rs
+++ b/aptos-move/aptos-gas-profiling/src/profiler.rs
@@ -478,6 +478,14 @@ where
         fn storage_discount_for_events(&self, total_cost: Fee) -> Fee;
 
         fn storage_fee_for_transaction_storage(&self, txn_size: NumBytes) -> Fee;
+
+        fn execution_gas_used(&self) -> Gas;
+
+        fn io_gas_used(&self) -> Gas;
+
+        fn storage_fee_used_in_gas_units(&self) -> Gas;
+
+        fn storage_fee_used(&self) -> Fee;
     }
 
     delegate_mut! {
diff --git a/aptos-move/aptos-gas/src/gas_meter.rs b/aptos-move/aptos-gas/src/gas_meter.rs
index 8ec9b746020cc..93438c868456d 100644
--- a/aptos-move/aptos-gas/src/gas_meter.rs
+++ b/aptos-move/aptos-gas/src/gas_meter.rs
@@ -334,6 +334,18 @@ pub trait AptosGasMeter: MoveGasMeter {
 
         Ok(())
     }
+
+    /// Return the total gas used for execution.
+    fn execution_gas_used(&self) -> Gas;
+
+    /// Return the total gas used for io.
+    fn io_gas_used(&self) -> Gas;
+
+    /// Return the total gas used for storage.
+    fn storage_fee_used_in_gas_units(&self) -> Gas;
+
+    /// Return the total fee used for storage.
+    fn storage_fee_used(&self) -> Fee;
 }
 
 /// The official gas meter used inside the Aptos VM.
@@ -348,6 +360,9 @@ pub struct StandardGasMeter {
 
     execution_gas_used: InternalGas,
     io_gas_used: InternalGas,
+    // The gas consumed by the storage operations.
+    storage_fee_in_internal_units: InternalGas,
+    // The storage fee consumed by the storage operations.
     storage_fee_used: Fee,
 
     should_leak_memory_for_native: bool,
@@ -370,6 +385,7 @@ impl StandardGasMeter {
             balance,
             execution_gas_used: 0.into(),
             io_gas_used: 0.into(),
+            storage_fee_in_internal_units: 0.into(),
             storage_fee_used: 0.into(),
             memory_quota,
             should_leak_memory_for_native: false,
@@ -1000,6 +1016,7 @@ impl AptosGasMeter for StandardGasMeter {
 
         self.charge(gas_consumed_internal)?;
 
+        self.storage_fee_in_internal_units += gas_consumed_internal;
         self.storage_fee_used += amount;
         if self.feature_version >= 7 && self.storage_fee_used > self.gas_params.txn.max_storage_fee
         {
@@ -1036,4 +1053,23 @@ impl AptosGasMeter for StandardGasMeter {
         self.charge_execution(cost)
             .map_err(|e| e.finish(Location::Undefined))
     }
+
+    fn execution_gas_used(&self) -> Gas {
+        self.execution_gas_used
+            .to_unit_round_up_with_params(&self.gas_params.txn)
+    }
+
+    fn io_gas_used(&self) -> Gas {
+        self.io_gas_used
+            .to_unit_round_up_with_params(&self.gas_params.txn)
+    }
+
+    fn storage_fee_used_in_gas_units(&self) -> Gas {
+        self.storage_fee_in_internal_units
+            .to_unit_round_up_with_params(&self.gas_params.txn)
+    }
+
+    fn storage_fee_used(&self) -> Fee {
+        self.storage_fee_used
+    }
 }
diff --git a/aptos-move/aptos-vm-types/src/output.rs b/aptos-move/aptos-vm-types/src/output.rs
index 593b01996a7a5..eb34dab0b24ec 100644
--- a/aptos-move/aptos-vm-types/src/output.rs
+++ b/aptos-move/aptos-vm-types/src/output.rs
@@ -6,6 +6,7 @@ use aptos_aggregator::delta_change_set::DeltaChangeSet;
 use aptos_state_view::StateView;
 use aptos_types::{
     contract_event::ContractEvent,
+    fee_statement::FeeStatement,
     state_store::state_key::StateKey,
     transaction::{TransactionOutput, TransactionStatus},
     write_set::{WriteOp, WriteSet},
@@ -17,15 +18,19 @@ use move_core_types::vm_status::VMStatus;
 #[derive(Debug, Clone)]
 pub struct VMOutput {
     change_set: VMChangeSet,
-    gas_used: u64,
+    fee_statement: FeeStatement,
     status: TransactionStatus,
 }
 
 impl VMOutput {
-    pub fn new(change_set: VMChangeSet, gas_used: u64, status: TransactionStatus) -> Self {
+    pub fn new(
+        change_set: VMChangeSet,
+        fee_statement: FeeStatement,
+        status: TransactionStatus,
+    ) -> Self {
         Self {
             change_set,
-            gas_used,
+            fee_statement,
             status,
         }
     }
@@ -35,13 +40,17 @@ impl VMOutput {
     pub fn empty_with_status(status: TransactionStatus) -> Self {
         Self {
             change_set: VMChangeSet::empty(),
-            gas_used: 0,
+            fee_statement: FeeStatement::zero(),
             status,
         }
     }
 
     pub fn unpack(self) -> (VMChangeSet, u64, TransactionStatus) {
-        (self.change_set, self.gas_used, self.status)
+        (self.change_set, self.fee_statement.gas_used(), self.status)
+    }
+
+    pub fn unpack_with_fee_statement(self) -> (VMChangeSet, FeeStatement, TransactionStatus) {
+        (self.change_set, self.fee_statement, self.status)
     }
 
     pub fn write_set(&self) -> &WriteSet {
@@ -57,7 +66,11 @@ impl VMOutput {
     }
 
     pub fn gas_used(&self) -> u64 {
-        self.gas_used
+        self.fee_statement.gas_used()
+    }
+
+    pub fn fee_statement(&self) -> &FeeStatement {
+        &self.fee_statement
     }
 
     pub fn status(&self) -> &TransactionStatus {
@@ -78,7 +91,7 @@ impl VMOutput {
         }
 
         // Try to materialize deltas and add them to the write set.
-        let (change_set, gas_used, status) = self.unpack();
+        let (change_set, gas_used, status) = self.unpack_with_fee_statement();
         let materialized_change_set = change_set.try_materialize(state_view)?;
         Ok(VMOutput::new(materialized_change_set, gas_used, status))
     }
diff --git a/aptos-move/aptos-vm-types/src/tests/utils.rs b/aptos-move/aptos-vm-types/src/tests/utils.rs
index 2b2743750c56d..a98da919f083c 100644
--- a/aptos-move/aptos-vm-types/src/tests/utils.rs
+++ b/aptos-move/aptos-vm-types/src/tests/utils.rs
@@ -4,6 +4,7 @@
 use crate::{change_set::VMChangeSet, check_change_set::CheckChangeSet, output::VMOutput};
 use aptos_aggregator::delta_change_set::{serialize, DeltaChangeSet, DeltaOp};
 use aptos_types::{
+    fee_statement::FeeStatement,
     state_store::state_key::StateKey,
     transaction::{ExecutionStatus, TransactionStatus},
     write_set::{WriteOp, WriteSetMut},
@@ -89,7 +90,7 @@ pub(crate) fn build_vm_output(
     const STATUS: TransactionStatus = TransactionStatus::Keep(ExecutionStatus::Success);
     VMOutput::new(
         build_change_set(write_set, delta_change_set),
-        GAS_USED,
+        FeeStatement::new(GAS_USED, GAS_USED, 0, 0, 0),
         STATUS,
     )
 }
diff --git a/aptos-move/aptos-vm/src/aptos_vm.rs b/aptos-move/aptos-vm/src/aptos_vm.rs
index bf2d836e81dd6..c2a71c6f172bd 100644
--- a/aptos-move/aptos-vm/src/aptos_vm.rs
+++ b/aptos-move/aptos-vm/src/aptos_vm.rs
@@ -32,6 +32,7 @@ use aptos_types::{
     account_config::new_block_event_key,
     block_executor::partitioner::ExecutableTransactions,
     block_metadata::BlockMetadata,
+    fee_statement::FeeStatement,
     on_chain_config::{new_epoch_event_key, FeatureFlag, TimedFeatureOverride},
     transaction::{
         EntryFunction, ExecutionError, ExecutionStatus, ModuleBundle, Multisig,
@@ -253,6 +254,23 @@ impl AptosVM {
         )
     }
 
+    fn fee_statement_from_gas_meter(
+        txn_data: &TransactionMetadata,
+        gas_meter: &impl AptosGasMeter,
+    ) -> FeeStatement {
+        let gas_used = txn_data
+            .max_gas_amount()
+            .checked_sub(gas_meter.balance())
+            .expect("Balance should always be less than or equal to max gas amount");
+        FeeStatement::new(
+            gas_used.into(),
+            u64::from(gas_meter.execution_gas_used()),
+            u64::from(gas_meter.io_gas_used()),
+            u64::from(gas_meter.storage_fee_used_in_gas_units()),
+            u64::from(gas_meter.storage_fee_used()),
+        )
+    }
+
     fn failed_transaction_cleanup_and_keep_vm_status(
         &self,
         error_code: VMStatus,
@@ -303,11 +321,11 @@ impl AptosVM {
                 ) {
                     return discard_error_vm_status(e);
                 }
+                let fee_statement = AptosVM::fee_statement_from_gas_meter(txn_data, gas_meter);
                 let txn_output = get_transaction_output(
                     &mut (),
                     session,
-                    gas_meter.balance(),
-                    txn_data,
+                    fee_statement,
                     status,
                     change_set_configs,
                 )
@@ -334,14 +352,10 @@ impl AptosVM {
                 .run_success_epilogue(session, gas_meter.balance(), txn_data, log_context)
         })?;
         let change_set = respawned_session.finish(change_set_configs)?;
-        let gas_used = txn_data
-            .max_gas_amount()
-            .checked_sub(gas_meter.balance())
-            .expect("Balance should always be less than or equal to max gas amount");
-
+        let fee_statement = AptosVM::fee_statement_from_gas_meter(txn_data, gas_meter);
         let output = VMOutput::new(
             change_set,
-            gas_used.into(),
+            fee_statement,
             TransactionStatus::Keep(ExecutionStatus::Success),
         );
 
@@ -1281,7 +1295,7 @@ impl AptosVM {
         self.read_writeset(resolver, change_set.write_set())?;
         SYSTEM_TRANSACTIONS_EXECUTED.inc();
 
-        let output = VMOutput::new(change_set, 0, VMStatus::Executed.into());
+        let output = VMOutput::new(change_set, FeeStatement::zero(), VMStatus::Executed.into());
         Ok((VMStatus::Executed, output))
     }
 
@@ -1326,8 +1340,7 @@ impl AptosVM {
         let output = get_transaction_output(
             &mut (),
             session,
-            0.into(),
-            &txn_data,
+            FeeStatement::zero(),
             ExecutionStatus::Success,
             &self
                 .0
diff --git a/aptos-move/aptos-vm/src/aptos_vm_impl.rs b/aptos-move/aptos-vm/src/aptos_vm_impl.rs
index 2e54f2f2a9fee..cf757e4e1c355 100644
--- a/aptos-move/aptos-vm/src/aptos_vm_impl.rs
+++ b/aptos-move/aptos-vm/src/aptos_vm_impl.rs
@@ -20,6 +20,7 @@ use aptos_state_view::StateView;
 use aptos_types::{
     account_config::{TransactionValidation, APTOS_TRANSACTION_VALIDATION, CORE_CODE_ADDRESS},
     chain_id::ChainId,
+    fee_statement::FeeStatement,
     on_chain_config::{
         ApprovedExecutionHashes, ConfigurationResource, FeatureFlag, Features, GasSchedule,
         GasScheduleV2, OnChainConfig, TimedFeatures, Version,
@@ -653,21 +654,15 @@ impl<'a> AptosVMInternals<'a> {
 pub(crate) fn get_transaction_output(
     ap_cache: &mut A,
     session: SessionExt,
-    gas_left: Gas,
-    txn_data: &TransactionMetadata,
+    fee_statement: FeeStatement,
     status: ExecutionStatus,
     change_set_configs: &ChangeSetConfigs,
 ) -> Result {
-    let gas_used = txn_data
-        .max_gas_amount()
-        .checked_sub(gas_left)
-        .expect("Balance should always be less than or equal to max gas amount");
-
     let change_set = session.finish(ap_cache, change_set_configs)?;
 
     Ok(VMOutput::new(
         change_set,
-        gas_used.into(),
+        fee_statement,
         TransactionStatus::Keep(status),
     ))
 }
diff --git a/aptos-move/aptos-vm/src/block_executor/mod.rs b/aptos-move/aptos-vm/src/block_executor/mod.rs
index 02571191498e9..4450be1bb87ac 100644
--- a/aptos-move/aptos-vm/src/block_executor/mod.rs
+++ b/aptos-move/aptos-vm/src/block_executor/mod.rs
@@ -27,6 +27,7 @@ use aptos_state_view::{StateView, StateViewId};
 use aptos_types::{
     block_executor::partitioner::{ExecutableTransactions, SubBlock, TransactionWithDependencies},
     executable::ExecutableTestType,
+    fee_statement::FeeStatement,
     state_store::state_key::StateKey,
     transaction::{Transaction, TransactionOutput, TransactionStatus},
     write_set::WriteOp,
@@ -128,6 +129,17 @@ impl BlockExecutorTransactionOutput for AptosTransactionOutput {
             .get()
             .map_or(0, |output| output.gas_used())
     }
+
+    // Return the fee statement of the transaction.
+    // Should never be called after vm_output is consumed.
+    fn fee_statement(&self) -> FeeStatement {
+        self.vm_output
+            .lock()
+            .as_ref()
+            .expect("Output to be set to get fee statement")
+            .fee_statement()
+            .clone()
+    }
 }
 
 pub struct BlockAptosVM();
diff --git a/aptos-move/block-executor/src/counters.rs b/aptos-move/block-executor/src/counters.rs
index b7b0edf6ca412..d8ef23ca3fbe9 100644
--- a/aptos-move/block-executor/src/counters.rs
+++ b/aptos-move/block-executor/src/counters.rs
@@ -2,10 +2,50 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use aptos_metrics_core::{
-    exponential_buckets, register_histogram, register_int_counter, Histogram, IntCounter,
+    exponential_buckets, register_histogram, register_histogram_vec, register_int_counter,
+    Histogram, HistogramVec, IntCounter,
 };
 use once_cell::sync::Lazy;
 
+pub struct GasType;
+
+impl GasType {
+    pub const EXECUTION_GAS: &'static str = "execution_gas";
+    pub const IO_GAS: &'static str = "io_gas";
+    pub const NON_STORAGE_GAS: &'static str = "non_storage_gas";
+    pub const STORAGE_FEE: &'static str = "storage_fee";
+    pub const STORAGE_GAS: &'static str = "storage_gas";
+    pub const TOTAL_GAS: &'static str = "total_gas";
+}
+
+/// Record the block gas during parallel execution.
+pub fn observe_parallel_execution_block_gas(cost: u64, gas_type: &'static str) {
+    PARALLEL_BLOCK_GAS
+        .with_label_values(&[gas_type])
+        .observe(cost as f64);
+}
+
+/// Record the txn gas during parallel execution.
+pub fn observe_parallel_execution_txn_gas(cost: u64, gas_type: &'static str) {
+    PARALLEL_TXN_GAS
+        .with_label_values(&[gas_type])
+        .observe(cost as f64);
+}
+
+/// Record the block gas during sequential execution.
+pub fn observe_sequential_execution_block_gas(cost: u64, gas_type: &'static str) {
+    SEQUENTIAL_BLOCK_GAS
+        .with_label_values(&[gas_type])
+        .observe(cost as f64);
+}
+
+/// Record the txn gas during sequential execution.
+pub fn observe_sequential_execution_txn_gas(cost: u64, gas_type: &'static str) {
+    SEQUENTIAL_TXN_GAS
+        .with_label_values(&[gas_type])
+        .observe(cost as f64);
+}
+
 /// Count of times the module publishing fallback was triggered in parallel execution.
 pub static MODULE_PUBLISHING_FALLBACK_COUNT: Lazy = Lazy::new(|| {
     register_int_counter!(
@@ -128,56 +168,56 @@ pub static DEPENDENCY_WAIT_SECONDS: Lazy = Lazy::new(|| {
     .unwrap()
 });
 
-pub static PARALLEL_PER_BLOCK_GAS: Lazy = Lazy::new(|| {
-    register_histogram!(
-        "aptos_execution_par_per_block_gas",
-        "The per-block consumed gas in parallel execution (Block STM)",
-        exponential_buckets(/*start=*/ 1.0, /*factor=*/ 2.0, /*count=*/ 30).unwrap(),
+pub static PARALLEL_BLOCK_GAS: Lazy = Lazy::new(|| {
+    register_histogram_vec!(
+        "aptos_execution_parallel_block_gas",
+        "Histogram for different block gas costs (execution, io, storage, storage fee, non-storage) during parallel execution",
+        &["stage"]
     )
     .unwrap()
 });
 
-pub static SEQUENTIAL_PER_BLOCK_GAS: Lazy = Lazy::new(|| {
-    register_histogram!(
-        "aptos_execution_seq_per_block_gas",
-        "The per-block consumed gas in sequential execution",
-        exponential_buckets(/*start=*/ 1.0, /*factor=*/ 2.0, /*count=*/ 30).unwrap(),
+pub static PARALLEL_TXN_GAS: Lazy = Lazy::new(|| {
+    register_histogram_vec!(
+        "aptos_execution_parallel_txn_gas",
+        "Histogram for different average txn gas costs (execution, io, storage, storage fee, non-storage) during parallel execution",
+        &["stage"]
     )
     .unwrap()
 });
 
-pub static PARALLEL_PER_BLOCK_COMMITTED_TXNS: Lazy = Lazy::new(|| {
-    register_histogram!(
-        "aptos_execution_par_per_block_committed_txns",
-        "The per-block committed txns in parallel execution (Block STM)",
-        exponential_buckets(/*start=*/ 1.0, /*factor=*/ 2.0, /*count=*/ 30).unwrap(),
+pub static SEQUENTIAL_BLOCK_GAS: Lazy = Lazy::new(|| {
+    register_histogram_vec!(
+        "aptos_execution_sequential_block_gas",
+        "Histogram for different block gas costs (execution, io, storage, storage fee, non-storage) during sequential execution",
+        &["stage"]
     )
     .unwrap()
 });
 
-pub static SEQUENTIAL_PER_BLOCK_COMMITTED_TXNS: Lazy = Lazy::new(|| {
-    register_histogram!(
-        "aptos_execution_seq_per_block_committed_txns",
-        "The per-block committed txns in sequential execution",
-        exponential_buckets(/*start=*/ 1.0, /*factor=*/ 2.0, /*count=*/ 30).unwrap(),
+pub static SEQUENTIAL_TXN_GAS: Lazy = Lazy::new(|| {
+    register_histogram_vec!(
+        "aptos_execution_sequential_txn_gas",
+        "Histogram for different average txn gas costs (execution, io, storage, storage fee, non-storage) during sequential execution",
+        &["stage"]
     )
     .unwrap()
 });
 
-pub static PARALLEL_PER_TXN_GAS: Lazy = Lazy::new(|| {
+pub static PARALLEL_BLOCK_COMMITTED_TXNS: Lazy = Lazy::new(|| {
     register_histogram!(
-        "aptos_execution_par_per_txn_gas",
-        "The per-txn consumed gas in parallel execution (Block STM)",
-        exponential_buckets(/*start=*/ 1.0, /*factor=*/ 1.5, /*count=*/ 30).unwrap(),
+        "aptos_execution_par_block_committed_txns",
+        "The per-block committed txns in parallel execution (Block STM)",
+        exponential_buckets(/*start=*/ 1.0, /*factor=*/ 2.0, /*count=*/ 30).unwrap(),
     )
     .unwrap()
 });
 
-pub static SEQUENTIAL_PER_TXN_GAS: Lazy = Lazy::new(|| {
+pub static SEQUENTIAL_BLOCK_COMMITTED_TXNS: Lazy = Lazy::new(|| {
     register_histogram!(
-        "aptos_execution_seq_per_txn_gas",
-        "The per-txn consumed gas in sequential execution",
-        exponential_buckets(/*start=*/ 1.0, /*factor=*/ 1.5, /*count=*/ 30).unwrap(),
+        "aptos_execution_seq_block_committed_txns",
+        "The per-block committed txns in sequential execution",
+        exponential_buckets(/*start=*/ 1.0, /*factor=*/ 2.0, /*count=*/ 30).unwrap(),
     )
     .unwrap()
 });
diff --git a/aptos-move/block-executor/src/executor.rs b/aptos-move/block-executor/src/executor.rs
index 17bce0f8b4d12..c54f1d97af92a 100644
--- a/aptos-move/block-executor/src/executor.rs
+++ b/aptos-move/block-executor/src/executor.rs
@@ -5,7 +5,7 @@
 use crate::{
     counters,
     counters::{
-        PARALLEL_EXECUTION_SECONDS, RAYON_EXECUTION_SECONDS, TASK_EXECUTE_SECONDS,
+        GasType, PARALLEL_EXECUTION_SECONDS, RAYON_EXECUTION_SECONDS, TASK_EXECUTE_SECONDS,
         TASK_VALIDATE_SECONDS, VM_INIT_SECONDS, WORK_WITH_TASK_SECONDS,
     },
     errors::*,
@@ -23,7 +23,8 @@ use aptos_mvhashmap::{
 };
 use aptos_state_view::TStateView;
 use aptos_types::{
-    block_executor::partitioner::ExecutableTransactions, executable::Executable, write_set::WriteOp,
+    block_executor::partitioner::ExecutableTransactions, executable::Executable,
+    fee_statement::FeeStatement, write_set::WriteOp,
 };
 use aptos_vm_logging::{clear_speculative_txn_logs, init_speculative_logs};
 use num_cpus;
@@ -104,6 +105,120 @@ where
         }
     }
 
+    fn update_parallel_block_gas_counters(
+        &self,
+        accumulated_fee_statement: &FeeStatement,
+        num_committed: usize,
+    ) {
+        counters::observe_parallel_execution_block_gas(
+            accumulated_fee_statement.gas_used(),
+            GasType::TOTAL_GAS,
+        );
+        counters::observe_parallel_execution_block_gas(
+            accumulated_fee_statement.execution_gas_used(),
+            GasType::EXECUTION_GAS,
+        );
+        counters::observe_parallel_execution_block_gas(
+            accumulated_fee_statement.io_gas_used(),
+            GasType::IO_GAS,
+        );
+        counters::observe_parallel_execution_block_gas(
+            accumulated_fee_statement.storage_gas_used(),
+            GasType::STORAGE_GAS,
+        );
+        counters::observe_parallel_execution_block_gas(
+            accumulated_fee_statement.execution_gas_used()
+                + accumulated_fee_statement.io_gas_used(),
+            GasType::NON_STORAGE_GAS,
+        );
+        counters::observe_parallel_execution_block_gas(
+            accumulated_fee_statement.storage_fee_used(),
+            GasType::STORAGE_FEE,
+        );
+        counters::PARALLEL_BLOCK_COMMITTED_TXNS.observe(num_committed as f64);
+    }
+
+    fn update_parallel_txn_gas_counters(&self, fee_statement: &FeeStatement) {
+        counters::observe_parallel_execution_txn_gas(fee_statement.gas_used(), GasType::TOTAL_GAS);
+        counters::observe_parallel_execution_txn_gas(
+            fee_statement.execution_gas_used(),
+            GasType::EXECUTION_GAS,
+        );
+        counters::observe_parallel_execution_txn_gas(fee_statement.io_gas_used(), GasType::IO_GAS);
+        counters::observe_parallel_execution_txn_gas(
+            fee_statement.storage_gas_used(),
+            GasType::STORAGE_GAS,
+        );
+        counters::observe_parallel_execution_txn_gas(
+            fee_statement.execution_gas_used() + fee_statement.io_gas_used(),
+            GasType::NON_STORAGE_GAS,
+        );
+        counters::observe_parallel_execution_txn_gas(
+            fee_statement.storage_fee_used(),
+            GasType::STORAGE_FEE,
+        );
+    }
+
+    fn update_sequential_block_gas_counters(
+        &self,
+        accumulated_fee_statement: &FeeStatement,
+        num_committed: usize,
+    ) {
+        counters::observe_sequential_execution_block_gas(
+            accumulated_fee_statement.gas_used(),
+            GasType::TOTAL_GAS,
+        );
+        counters::observe_sequential_execution_block_gas(
+            accumulated_fee_statement.execution_gas_used(),
+            GasType::EXECUTION_GAS,
+        );
+        counters::observe_sequential_execution_block_gas(
+            accumulated_fee_statement.io_gas_used(),
+            GasType::IO_GAS,
+        );
+        counters::observe_sequential_execution_block_gas(
+            accumulated_fee_statement.storage_gas_used(),
+            GasType::STORAGE_GAS,
+        );
+        counters::observe_sequential_execution_block_gas(
+            accumulated_fee_statement.execution_gas_used()
+                + accumulated_fee_statement.io_gas_used(),
+            GasType::NON_STORAGE_GAS,
+        );
+        counters::observe_sequential_execution_block_gas(
+            accumulated_fee_statement.storage_fee_used(),
+            GasType::STORAGE_FEE,
+        );
+        counters::PARALLEL_BLOCK_COMMITTED_TXNS.observe(num_committed as f64);
+    }
+
+    fn update_sequential_txn_gas_counters(&self, fee_statement: &FeeStatement) {
+        counters::observe_sequential_execution_txn_gas(
+            fee_statement.gas_used(),
+            GasType::TOTAL_GAS,
+        );
+        counters::observe_sequential_execution_txn_gas(
+            fee_statement.execution_gas_used(),
+            GasType::EXECUTION_GAS,
+        );
+        counters::observe_sequential_execution_txn_gas(
+            fee_statement.io_gas_used(),
+            GasType::IO_GAS,
+        );
+        counters::observe_sequential_execution_txn_gas(
+            fee_statement.storage_gas_used(),
+            GasType::STORAGE_GAS,
+        );
+        counters::observe_sequential_execution_txn_gas(
+            fee_statement.execution_gas_used() + fee_statement.io_gas_used(),
+            GasType::NON_STORAGE_GAS,
+        );
+        counters::observe_sequential_execution_txn_gas(
+            fee_statement.storage_fee_used(),
+            GasType::STORAGE_FEE,
+        );
+    }
+
     fn execute(
         &self,
         version: Version,
@@ -250,9 +365,9 @@ where
         scheduler: &Scheduler,
         post_commit_txs: &Vec>,
         worker_idx: &mut usize,
-        accumulated_gas: &mut u64,
         scheduler_task: &mut SchedulerTask,
         last_input_output: &TxnLastInputOutput,
+        accumulated_fee_statement: &mut FeeStatement,
     ) {
         while let Some(txn_idx) = scheduler.try_commit() {
             // Create a CommitGuard to ensure Coordinator sends the committed txn index to Worker.
@@ -265,8 +380,10 @@ where
             if txn_idx as usize + 1 == scheduler.num_txns() as usize {
                 *scheduler_task = SchedulerTask::Done;
 
-                counters::PARALLEL_PER_BLOCK_GAS.observe(*accumulated_gas as f64);
-                counters::PARALLEL_PER_BLOCK_COMMITTED_TXNS.observe((txn_idx + 1) as f64);
+                self.update_parallel_block_gas_counters(
+                    accumulated_fee_statement,
+                    (txn_idx + 1) as usize,
+                );
                 info!(
                     "[BlockSTM]: Parallel execution completed, all {} txns committed.",
                     txn_idx + 1
@@ -274,34 +391,41 @@ where
                 break;
             }
 
-            // For committed txns with Success status, calculate the accumulated gas.
+            // For committed txns with Success status, calculate the accumulated gas costs.
             // For committed txns with Abort or SkipRest status, early halt BlockSTM.
-            match last_input_output.gas_used(txn_idx) {
-                Some(gas) => {
-                    *accumulated_gas += gas;
-                    counters::PARALLEL_PER_TXN_GAS.observe(gas as f64);
+            match last_input_output.fee_statement(txn_idx) {
+                Some(fee_statement) => {
+                    accumulated_fee_statement.add_fee_statement(&fee_statement);
+                    self.update_parallel_txn_gas_counters(&fee_statement);
                 },
                 None => {
                     scheduler.halt();
 
-                    counters::PARALLEL_PER_BLOCK_GAS.observe(*accumulated_gas as f64);
-                    counters::PARALLEL_PER_BLOCK_COMMITTED_TXNS.observe((txn_idx + 1) as f64);
+                    self.update_parallel_block_gas_counters(
+                        accumulated_fee_statement,
+                        (txn_idx + 1) as usize,
+                    );
                     info!("[BlockSTM]: Parallel execution early halted due to Abort or SkipRest txn, {} txns committed.", txn_idx + 1);
                     break;
                 },
             };
 
             if let Some(per_block_gas_limit) = maybe_block_gas_limit {
-                // When the accumulated gas of the committed txns exceeds PER_BLOCK_GAS_LIMIT, early halt BlockSTM.
-                if *accumulated_gas >= per_block_gas_limit {
+                // When the accumulated execution and io gas of the committed txns exceeds PER_BLOCK_GAS_LIMIT, early halt BlockSTM.
+                // Storage gas does not count towards the per block gas limit, as we measure execution related cost here.
+                let accumulated_non_storage_gas = accumulated_fee_statement.execution_gas_used()
+                    + accumulated_fee_statement.io_gas_used();
+                if accumulated_non_storage_gas >= per_block_gas_limit {
                     // Set the execution output status to be SkipRest, to skip the rest of the txns.
                     last_input_output.update_to_skip_rest(txn_idx);
                     scheduler.halt();
 
-                    counters::PARALLEL_PER_BLOCK_GAS.observe(*accumulated_gas as f64);
-                    counters::PARALLEL_PER_BLOCK_COMMITTED_TXNS.observe((txn_idx + 1) as f64);
+                    self.update_parallel_block_gas_counters(
+                        accumulated_fee_statement,
+                        (txn_idx + 1) as usize,
+                    );
                     counters::PARALLEL_EXCEED_PER_BLOCK_GAS_LIMIT_COUNT.inc();
-                    info!("[BlockSTM]: Parallel execution early halted due to accumulated_gas {} >= PER_BLOCK_GAS_LIMIT {}, {} txns committed", *accumulated_gas, per_block_gas_limit, txn_idx);
+                    info!("[BlockSTM]: Parallel execution early halted due to accumulated_non_storage_gas {} >= PER_BLOCK_GAS_LIMIT {}, {} txns committed", accumulated_non_storage_gas, per_block_gas_limit, txn_idx);
                     break;
                 }
             }
@@ -378,8 +502,9 @@ where
 
         let _timer = WORK_WITH_TASK_SECONDS.start_timer();
         let mut scheduler_task = SchedulerTask::NoTask;
-        let mut accumulated_gas = 0;
         let mut worker_idx = 0;
+
+        let mut accumulated_fee_statement = FeeStatement::zero();
         loop {
             // Only one thread does try_commit to avoid contention.
             match &role {
@@ -389,9 +514,9 @@ where
                         scheduler,
                         post_commit_txs,
                         &mut worker_idx,
-                        &mut accumulated_gas,
                         &mut scheduler_task,
                         last_input_output,
+                        &mut accumulated_fee_statement,
                     );
                 },
                 CommitRole::Worker(rx) => {
@@ -575,7 +700,9 @@ where
         let data_map = UnsyncMap::new();
 
         let mut ret = Vec::with_capacity(num_txns);
-        let mut accumulated_gas = 0;
+
+        let mut accumulated_fee_statement = FeeStatement::zero();
+
         for (idx, txn) in signature_verified_block.iter().enumerate() {
             let res = executor.execute_transaction(
                 &LatestView::::new_btree_view(base_view, &data_map, idx as TxnIndex),
@@ -596,10 +723,10 @@ where
                     for (ap, write_op) in output.get_writes().into_iter() {
                         data_map.write(ap, write_op);
                     }
-                    // Calculating the accumulated gas of the committed txns.
-                    let txn_gas = output.gas_used();
-                    accumulated_gas += txn_gas;
-                    counters::SEQUENTIAL_PER_TXN_GAS.observe(txn_gas as f64);
+                    // Calculating the accumulated gas costs of the committed txns.
+                    let fee_statement = output.fee_statement();
+                    accumulated_fee_statement.add_fee_statement(&fee_statement);
+                    self.update_sequential_txn_gas_counters(&accumulated_fee_statement);
                     ret.push(output);
                 },
                 ExecutionStatus::Abort(err) => {
@@ -617,9 +744,11 @@ where
             if let Some(per_block_gas_limit) = self.maybe_block_gas_limit {
                 // When the accumulated gas of the committed txns
                 // exceeds per_block_gas_limit, halt sequential execution.
-                if accumulated_gas >= per_block_gas_limit {
+                let accumulated_non_storage_gas = accumulated_fee_statement.execution_gas_used()
+                    + accumulated_fee_statement.io_gas_used();
+                if accumulated_non_storage_gas >= per_block_gas_limit {
                     counters::SEQUENTIAL_EXCEED_PER_BLOCK_GAS_LIMIT_COUNT.inc();
-                    info!("[Execution]: Sequential execution early halted due to accumulated_gas {} >= PER_BLOCK_GAS_LIMIT {}, {} txns committed", accumulated_gas, per_block_gas_limit, ret.len());
+                    info!("[Execution]: Sequential execution early halted due to accumulated_non_storage_gas {} >= PER_BLOCK_GAS_LIMIT {}, {} txns committed", accumulated_non_storage_gas, per_block_gas_limit, ret.len());
                     break;
                 }
             }
@@ -632,8 +761,7 @@ where
             );
         }
 
-        counters::SEQUENTIAL_PER_BLOCK_GAS.observe(accumulated_gas as f64);
-        counters::SEQUENTIAL_PER_BLOCK_COMMITTED_TXNS.observe(ret.len() as f64);
+        self.update_sequential_block_gas_counters(&accumulated_fee_statement, ret.len());
         ret.resize_with(num_txns, E::Output::skip_output);
         Ok(ret)
     }
diff --git a/aptos-move/block-executor/src/proptest_types/types.rs b/aptos-move/block-executor/src/proptest_types/types.rs
index d1064637c2813..f9aa9b2d3449b 100644
--- a/aptos-move/block-executor/src/proptest_types/types.rs
+++ b/aptos-move/block-executor/src/proptest_types/types.rs
@@ -16,6 +16,7 @@ use aptos_types::{
     access_path::AccessPath,
     account_address::AccountAddress,
     executable::ModulePath,
+    fee_statement::FeeStatement,
     state_store::{state_storage_usage::StateStorageUsage, state_value::StateValue},
     write_set::{TransactionWrite, WriteOp},
 };
@@ -516,6 +517,10 @@ where
     fn gas_used(&self) -> u64 {
         1
     }
+
+    fn fee_statement(&self) -> FeeStatement {
+        FeeStatement::new(1, 1, 0, 0, 0)
+    }
 }
 
 ///////////////////////////////////////////////////////////////////////////
diff --git a/aptos-move/block-executor/src/task.rs b/aptos-move/block-executor/src/task.rs
index ffc448e3d98af..63c0460212bca 100644
--- a/aptos-move/block-executor/src/task.rs
+++ b/aptos-move/block-executor/src/task.rs
@@ -7,6 +7,7 @@ use aptos_mvhashmap::types::TxnIndex;
 use aptos_state_view::TStateView;
 use aptos_types::{
     executable::ModulePath,
+    fee_statement::FeeStatement,
     write_set::{TransactionWrite, WriteOp},
 };
 use std::{fmt::Debug, hash::Hash};
@@ -95,4 +96,7 @@ pub trait TransactionOutput: Send + Sync + Debug {
 
     /// Return the amount of gas consumed by the transaction.
     fn gas_used(&self) -> u64;
+
+    /// Return the fee statement of the transaction.
+    fn fee_statement(&self) -> FeeStatement;
 }
diff --git a/aptos-move/block-executor/src/txn_last_input_output.rs b/aptos-move/block-executor/src/txn_last_input_output.rs
index 4e4e6f37e151e..520b61d823346 100644
--- a/aptos-move/block-executor/src/txn_last_input_output.rs
+++ b/aptos-move/block-executor/src/txn_last_input_output.rs
@@ -7,7 +7,10 @@ use crate::{
 };
 use anyhow::anyhow;
 use aptos_mvhashmap::types::{Incarnation, TxnIndex, Version};
-use aptos_types::{access_path::AccessPath, executable::ModulePath, write_set::WriteOp};
+use aptos_types::{
+    access_path::AccessPath, executable::ModulePath, fee_statement::FeeStatement,
+    write_set::WriteOp,
+};
 use arc_swap::ArcSwapOption;
 use crossbeam::utils::CachePadded;
 use dashmap::DashSet;
@@ -218,13 +221,14 @@ impl TxnLastInputO
         self.inputs[txn_idx as usize].load_full()
     }
 
-    pub fn gas_used(&self, txn_idx: TxnIndex) -> Option {
+    /// Returns the total gas, execution gas, io gas and storage gas of the transaction.
+    pub fn fee_statement(&self, txn_idx: TxnIndex) -> Option {
         match &self.outputs[txn_idx as usize]
             .load_full()
             .expect("[BlockSTM]: Execution output must be recorded after execution")
             .output_status
         {
-            ExecutionStatus::Success(output) => Some(output.gas_used()),
+            ExecutionStatus::Success(output) => Some(output.fee_statement()),
             _ => None,
         }
     }
diff --git a/storage/aptosdb/src/fake_aptosdb.rs b/storage/aptosdb/src/fake_aptosdb.rs
index 73ec96dc624f5..9001ebfcf5329 100644
--- a/storage/aptosdb/src/fake_aptosdb.rs
+++ b/storage/aptosdb/src/fake_aptosdb.rs
@@ -104,7 +104,7 @@ impl FakeBufferedState {
         ensure!(
             new_state_after_checkpoint.base_version >= self.state_after_checkpoint.base_version
         );
-        if let Some(updates_until_next_checkpoint_since_current) =
+        if let Some(_updates_until_next_checkpoint_since_current) =
             updates_until_next_checkpoint_since_current_option
         {
             self.state_after_checkpoint.current = new_state_after_checkpoint.base.clone();
diff --git a/types/src/fee_statement.rs b/types/src/fee_statement.rs
new file mode 100644
index 0000000000000..6c7738e1fae80
--- /dev/null
+++ b/types/src/fee_statement.rs
@@ -0,0 +1,88 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
+pub struct FeeStatement {
+    /// Total gas charge.
+    total_charge_gas_units: u64,
+    /// Execution gas charge.
+    execution_gas_units: u64,
+    /// IO gas charge.
+    io_gas_units: u64,
+    /// Storage gas charge.
+    storage_gas_units: u64,
+    /// Storage fee charge.
+    storage_fee_octas: u64,
+}
+
+impl FeeStatement {
+    pub fn zero() -> Self {
+        Self {
+            total_charge_gas_units: 0,
+            execution_gas_units: 0,
+            io_gas_units: 0,
+            storage_gas_units: 0,
+            storage_fee_octas: 0,
+        }
+    }
+
+    pub fn new(
+        total_charge_gas_units: u64,
+        execution_gas_units: u64,
+        io_gas_units: u64,
+        storage_gas_units: u64,
+        storage_fee_octas: u64,
+    ) -> Self {
+        Self {
+            total_charge_gas_units,
+            execution_gas_units,
+            io_gas_units,
+            storage_gas_units,
+            storage_fee_octas,
+        }
+    }
+
+    pub fn new_from_fee_statement(fee_statement: &FeeStatement) -> Self {
+        Self {
+            total_charge_gas_units: fee_statement.total_charge_gas_units,
+            execution_gas_units: fee_statement.execution_gas_units,
+            io_gas_units: fee_statement.io_gas_units,
+            storage_gas_units: fee_statement.storage_gas_units,
+            storage_fee_octas: fee_statement.storage_fee_octas,
+        }
+    }
+
+    pub fn gas_used(&self) -> u64 {
+        self.total_charge_gas_units
+    }
+
+    pub fn execution_gas_used(&self) -> u64 {
+        self.execution_gas_units
+    }
+
+    pub fn io_gas_used(&self) -> u64 {
+        self.io_gas_units
+    }
+
+    pub fn storage_gas_used(&self) -> u64 {
+        self.storage_gas_units
+    }
+
+    pub fn storage_fee_used(&self) -> u64 {
+        self.storage_fee_octas
+    }
+
+    pub fn add_fee_statement(&mut self, other: &FeeStatement) {
+        self.total_charge_gas_units += other.total_charge_gas_units;
+        self.execution_gas_units += other.execution_gas_units;
+        self.io_gas_units += other.io_gas_units;
+        self.storage_gas_units += other.storage_gas_units;
+        self.storage_fee_octas += other.storage_fee_octas;
+    }
+
+    pub fn fee_statement(&self) -> FeeStatement {
+        self.clone()
+    }
+}
diff --git a/types/src/lib.rs b/types/src/lib.rs
index 2f408f53786ac..ea758ebec8881 100644
--- a/types/src/lib.rs
+++ b/types/src/lib.rs
@@ -16,6 +16,7 @@ pub mod epoch_change;
 pub mod epoch_state;
 pub mod event;
 pub mod executable;
+pub mod fee_statement;
 pub mod governance;
 pub mod ledger_info;
 pub mod mempool_status;

From 81bc22401244af41220b556ee3b370acccf00382 Mon Sep 17 00:00:00 2001
From: igor-aptos <110557261+igor-aptos@users.noreply.github.com>
Date: Thu, 15 Jun 2023 15:13:25 -0700
Subject: [PATCH 184/200] Add workload_mix and realistic_env_graceful_overload,
 and cleanup continuous forge test (#8601)

---
 .github/workflows/forge-stable.yaml           | 163 +++++++-------
 .../src/emitter/account_minter.rs             |  11 +-
 .../src/emitter/mod.rs                        |  47 ++--
 .../src/emitter/submission_worker.rs          | 124 +++++------
 testsuite/forge-cli/src/main.rs               | 203 ++++++++++++------
 5 files changed, 314 insertions(+), 234 deletions(-)

diff --git a/.github/workflows/forge-stable.yaml b/.github/workflows/forge-stable.yaml
index 6eaaef78abb7c..3e98857906b16 100644
--- a/.github/workflows/forge-stable.yaml
+++ b/.github/workflows/forge-stable.yaml
@@ -108,44 +108,84 @@ jobs:
           fi
           echo "IMAGE_TAG: [${IMAGE_TAG}](https://github.com/${{ github.repository }}/commit/${IMAGE_TAG})" >> $GITHUB_STEP_SUMMARY
 
-  ### Performance Forge tests
 
-  run-forge-consensus-stress-test:
+  ### Real-world-network tests.
+
+  run-forge-realistic-env-max-load-long:
     if: ${{ github.event_name != 'pull_request' }}
     needs: determine-test-metadata
     uses: aptos-labs/aptos-core/.github/workflows/workflow-run-forge.yaml@main
     secrets: inherit
     with:
       IMAGE_TAG: ${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
-      FORGE_NAMESPACE: forge-consensus-stress-test-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
-      FORGE_RUNNER_DURATION_SECS: 2400
-      FORGE_TEST_SUITE: consensus_stress_test
-      POST_TO_SLACK: ${{ needs.determine-test-metadata.outputs.BRANCH == 'main' }} # only post to slack on main branch
+      FORGE_NAMESPACE: forge-realistic-env-max-load-long-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
+      FORGE_RUNNER_DURATION_SECS: 7200
+      FORGE_TEST_SUITE: realistic_env_max_load
+      POST_TO_SLACK: true
 
-  run-forge-account-creation-test:
+  run-forge-realistic-env-load-sweep:
     if: ${{ github.event_name != 'pull_request' }}
     needs: determine-test-metadata
     uses: aptos-labs/aptos-core/.github/workflows/workflow-run-forge.yaml@main
     secrets: inherit
     with:
       IMAGE_TAG: ${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
-      FORGE_NAMESPACE: forge-account-creation-test-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
-      FORGE_RUNNER_DURATION_SECS: 900
-      FORGE_TEST_SUITE: account_creation
-      POST_TO_SLACK: ${{ needs.determine-test-metadata.outputs.BRANCH == 'main' }} # only post to slack on main branch
+      FORGE_NAMESPACE: forge-realistic-env-load-sweep-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
+      # 5 tests, each 300s
+      FORGE_RUNNER_DURATION_SECS: 1500
+      FORGE_TEST_SUITE: realistic_env_load_sweep
+      POST_TO_SLACK: true
 
-  run-forge-performance-test:
+  run-forge-realistic-env-graceful-overload:
     if: ${{ github.event_name != 'pull_request' }}
     needs: determine-test-metadata
     uses: aptos-labs/aptos-core/.github/workflows/workflow-run-forge.yaml@main
     secrets: inherit
     with:
       IMAGE_TAG: ${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
-      FORGE_NAMESPACE: forge-performance-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
-      FORGE_RUNNER_DURATION_SECS: 7200
-      FORGE_TEST_SUITE: land_blocking
+      FORGE_NAMESPACE: forge-realistic-env-graceful-overload-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
+      FORGE_RUNNER_DURATION_SECS: 1200
+      FORGE_TEST_SUITE: realistic_env_graceful_overload
+      POST_TO_SLACK: true
+
+  run-forge-realistic-network-tuned-for-throughput:
+    if: ${{ github.event_name != 'pull_request' }}
+    needs: determine-test-metadata
+    uses: aptos-labs/aptos-core/.github/workflows/workflow-run-forge.yaml@main
+    secrets: inherit
+    with:
+      IMAGE_TAG: ${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
+      FORGE_NAMESPACE: forge-realistic-network-tuned-for-throughput-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
+      FORGE_RUNNER_DURATION_SECS: 900
+      FORGE_TEST_SUITE: realistic_network_tuned_for_throughput
       FORGE_ENABLE_PERFORMANCE: true
-      POST_TO_SLACK: ${{ needs.determine-test-metadata.outputs.BRANCH == 'main' }} # only post to slack on main branch
+      POST_TO_SLACK: true
+
+  ### Forge Correctness/Componenet/Stress tests
+
+  run-forge-consensus-stress-test:
+    if: ${{ github.event_name != 'pull_request' }}
+    needs: determine-test-metadata
+    uses: aptos-labs/aptos-core/.github/workflows/workflow-run-forge.yaml@main
+    secrets: inherit
+    with:
+      IMAGE_TAG: ${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
+      FORGE_NAMESPACE: forge-consensus-stress-test-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
+      FORGE_RUNNER_DURATION_SECS: 2400
+      FORGE_TEST_SUITE: consensus_stress_test
+      POST_TO_SLACK: true
+
+  run-forge-workload-mix-test:
+    if: ${{ github.event_name != 'pull_request' }}
+    needs: determine-test-metadata
+    uses: aptos-labs/aptos-core/.github/workflows/workflow-run-forge.yaml@main
+    secrets: inherit
+    with:
+      IMAGE_TAG: ${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
+      FORGE_NAMESPACE: forge-workload-mix-test-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
+      FORGE_RUNNER_DURATION_SECS: 900
+      FORGE_TEST_SUITE: workload_mix
+      POST_TO_SLACK: true
 
   run-forge-single-vfn-perf:
     if: ${{ github.event_name != 'pull_request' }}
@@ -158,7 +198,7 @@ jobs:
       # Run for 8 minutes
       FORGE_RUNNER_DURATION_SECS: 480
       FORGE_TEST_SUITE: single_vfn_perf
-      POST_TO_SLACK: ${{ needs.determine-test-metadata.outputs.BRANCH == 'main' }} # only post to slack on main branch
+      POST_TO_SLACK: true
 
   run-forge-haproxy:
     if: ${{ github.event_name != 'pull_request' }}
@@ -171,7 +211,19 @@ jobs:
       FORGE_RUNNER_DURATION_SECS: 600
       FORGE_ENABLE_HAPROXY: true
       FORGE_TEST_SUITE: land_blocking
-      POST_TO_SLACK: ${{ needs.determine-test-metadata.outputs.BRANCH == 'main' }} # only post to slack on main branch
+      POST_TO_SLACK: true
+
+  run-forge-fullnode-reboot-stress-test:
+    if: ${{ github.event_name != 'pull_request' }}
+    needs: determine-test-metadata
+    uses: aptos-labs/aptos-core/.github/workflows/workflow-run-forge.yaml@main
+    secrets: inherit
+    with:
+      IMAGE_TAG: ${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
+      FORGE_NAMESPACE: forge-fullnode-reboot-stress-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
+      FORGE_RUNNER_DURATION_SECS: 1800
+      FORGE_TEST_SUITE: fullnode_reboot_stress_test
+      POST_TO_SLACK: true
 
   ### Compatibility Forge tests
 
@@ -188,33 +240,7 @@ jobs:
       FORGE_TEST_SUITE: compat
       IMAGE_TAG: testnet
       GIT_SHA: ${{ needs.determine-test-metadata.outputs.IMAGE_TAG }} # this is the git ref to checkout
-      POST_TO_SLACK: ${{ needs.determine-test-metadata.outputs.BRANCH == 'main' }} # only post to slack on main branch
-
-  ### Chaos Forge tests
-
-  run-forge-three-region:
-    if: ${{ github.event_name != 'pull_request' }}
-    needs: determine-test-metadata
-    uses: aptos-labs/aptos-core/.github/workflows/workflow-run-forge.yaml@main
-    secrets: inherit
-    with:
-      IMAGE_TAG: ${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
-      FORGE_NAMESPACE: forge-three-region-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
-      FORGE_RUNNER_DURATION_SECS: 1800
-      FORGE_TEST_SUITE: three_region_simulation
-      POST_TO_SLACK: ${{ needs.determine-test-metadata.outputs.BRANCH == 'main' }} # only post to slack on main branch
-
-  run-forge-fullnode-reboot-stress-test:
-    if: ${{ github.event_name != 'pull_request' }}
-    needs: determine-test-metadata
-    uses: aptos-labs/aptos-core/.github/workflows/workflow-run-forge.yaml@main
-    secrets: inherit
-    with:
-      IMAGE_TAG: ${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
-      FORGE_NAMESPACE: forge-fullnode-reboot-stress-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
-      FORGE_RUNNER_DURATION_SECS: 1800
-      FORGE_TEST_SUITE: fullnode_reboot_stress_test
-      POST_TO_SLACK: ${{ needs.determine-test-metadata.outputs.BRANCH == 'main' }} # only post to slack on main branch
+      POST_TO_SLACK: true
 
   ### Changing working quorum Forge tests
 
@@ -228,7 +254,7 @@ jobs:
       FORGE_NAMESPACE: forge-changing-working-quorum-test-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
       FORGE_RUNNER_DURATION_SECS: 1200
       FORGE_TEST_SUITE: changing_working_quorum_test
-      POST_TO_SLACK: ${{ needs.determine-test-metadata.outputs.BRANCH == 'main' }} # only post to slack on main branch
+      POST_TO_SLACK: true
       FORGE_ENABLE_FAILPOINTS: true
 
   run-forge-changing-working-quorum-test-high-load:
@@ -241,7 +267,7 @@ jobs:
       FORGE_NAMESPACE: forge-changing-working-quorum-test-high-load-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
       FORGE_RUNNER_DURATION_SECS: 900
       FORGE_TEST_SUITE: changing_working_quorum_test_high_load
-      POST_TO_SLACK: ${{ needs.determine-test-metadata.outputs.BRANCH == 'main' }} # only post to slack on main branch
+      POST_TO_SLACK: true
       FORGE_ENABLE_FAILPOINTS: true
 
   ### State sync Forge tests
@@ -270,7 +296,7 @@ jobs:
       # Run for 40 minutes
       FORGE_RUNNER_DURATION_SECS: 2400
       FORGE_TEST_SUITE: state_sync_perf_fullnodes_execute_transactions
-      POST_TO_SLACK: ${{ needs.determine-test-metadata.outputs.BRANCH == 'main' }} # only post to slack on main branch
+      POST_TO_SLACK: true
 
   run-forge-state-sync-perf-fullnode-fast-sync-test:
     if: ${{ github.event_name != 'pull_request' }}
@@ -283,7 +309,7 @@ jobs:
       # Run for 40 minutes
       FORGE_RUNNER_DURATION_SECS: 2400
       FORGE_TEST_SUITE: state_sync_perf_fullnodes_fast_sync
-      POST_TO_SLACK: ${{ needs.determine-test-metadata.outputs.BRANCH == 'main' }} # only post to slack on main branch
+      POST_TO_SLACK: true
 
   run-forge-state-sync-perf-fullnode-apply-test:
     if: ${{ github.event_name != 'pull_request' }}
@@ -295,43 +321,4 @@ jobs:
       FORGE_NAMESPACE: forge-state-sync-perf-fullnode-apply-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
       FORGE_RUNNER_DURATION_SECS: 2400
       FORGE_TEST_SUITE: state_sync_perf_fullnodes_apply_outputs
-      POST_TO_SLACK: ${{ needs.determine-test-metadata.outputs.BRANCH == 'main' }} # only post to slack on main branch
-
-  ### Additional real-world-network tests. Eventually all consensus-related tests should migrate to real-world-network.
-
-  run-forge-realistic-env-max-throughput:
-    if: ${{ github.event_name != 'pull_request' }}
-    needs: determine-test-metadata
-    uses: aptos-labs/aptos-core/.github/workflows/workflow-run-forge.yaml@main
-    secrets: inherit
-    with:
-      IMAGE_TAG: ${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
-      FORGE_NAMESPACE: forge-realistic-env-max-throughput-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
-      FORGE_RUNNER_DURATION_SECS: 600
-      FORGE_TEST_SUITE: realistic_env_max_throughput
-      POST_TO_SLACK: true
-
-  run-forge-realistic-env-load-sweep:
-    if: ${{ github.event_name != 'pull_request' }}
-    needs: determine-test-metadata
-    uses: aptos-labs/aptos-core/.github/workflows/workflow-run-forge.yaml@main
-    secrets: inherit
-    with:
-      IMAGE_TAG: ${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
-      FORGE_NAMESPACE: forge-realistic-env-load-sweep-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
-      # 5 tests, each 300s
-      FORGE_RUNNER_DURATION_SECS: 1500
-      FORGE_TEST_SUITE: realistic_env_load_sweep
-      POST_TO_SLACK: true
-
-  run-forge-three-region-graceful-overload:
-    if: ${{ github.event_name != 'pull_request' }}
-    needs: determine-test-metadata
-    uses: aptos-labs/aptos-core/.github/workflows/workflow-run-forge.yaml@main
-    secrets: inherit
-    with:
-      IMAGE_TAG: ${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
-      FORGE_NAMESPACE: forge-three-region-graceful-overload-${{ needs.determine-test-metadata.outputs.IMAGE_TAG }}
-      FORGE_RUNNER_DURATION_SECS: 1800
-      FORGE_TEST_SUITE: three_region_simulation_graceful_overload
       POST_TO_SLACK: true
diff --git a/crates/transaction-emitter-lib/src/emitter/account_minter.rs b/crates/transaction-emitter-lib/src/emitter/account_minter.rs
index 88de068f20f2c..7b56d04549544 100644
--- a/crates/transaction-emitter-lib/src/emitter/account_minter.rs
+++ b/crates/transaction-emitter-lib/src/emitter/account_minter.rs
@@ -196,8 +196,10 @@ impl<'t> AccountMinter<'t> {
             request_counters.show_simple(),
         );
         info!(
-            "Creating additional {} accounts with {} coins each",
-            num_accounts, coins_per_account
+            "Creating additional {} accounts with {} coins each (txn {} gas price)",
+            num_accounts,
+            coins_per_account,
+            txn_factory.get_gas_unit_price(),
         );
 
         let seed_rngs = gen_rng_for_reusable_account(actual_num_seed_accounts);
@@ -281,7 +283,10 @@ impl<'t> AccountMinter<'t> {
         max_submit_batch_size: usize,
         counters: &CounterState,
     ) -> Result> {
-        info!("Creating and funding seeds accounts");
+        info!(
+            "Creating and funding seeds accounts (txn {} gas price)",
+            self.txn_factory.get_gas_unit_price()
+        );
         let mut i = 0;
         let mut seed_accounts = vec![];
         while i < seed_account_num {
diff --git a/crates/transaction-emitter-lib/src/emitter/mod.rs b/crates/transaction-emitter-lib/src/emitter/mod.rs
index 6a199ccd12457..79555f480e2e5 100644
--- a/crates/transaction-emitter-lib/src/emitter/mod.rs
+++ b/crates/transaction-emitter-lib/src/emitter/mod.rs
@@ -16,7 +16,7 @@ use again::RetryPolicy;
 use anyhow::{ensure, format_err, Result};
 use aptos_config::config::DEFAULT_MAX_SUBMIT_TRANSACTION_BATCH_SIZE;
 use aptos_logger::{debug, error, info, sample, sample::SampleRate, warn};
-use aptos_rest_client::Client as RestClient;
+use aptos_rest_client::{aptos_api_types::AptosErrorCode, error::RestError, Client as RestClient};
 use aptos_sdk::{
     move_types::account_address::AccountAddress,
     transaction_builder::{aptos_stdlib, TransactionFactory},
@@ -916,27 +916,13 @@ pub async fn query_sequence_numbers<'a, I>(
 where
     I: Iterator,
 {
-    let (addresses, futures): (Vec<_>, Vec<_>) = addresses
-        .map(|address| {
-            (
-                *address,
-                RETRY_POLICY.retry(move || client.get_account_bcs(*address)),
-            )
-        })
-        .unzip();
+    let futures = addresses
+        .map(|address| RETRY_POLICY.retry(move || get_account_if_exists(client, *address)));
 
     let (seq_nums, timestamps): (Vec<_>, Vec<_>) = try_join_all(futures)
         .await
         .map_err(|e| format_err!("Get accounts failed: {:?}", e))?
         .into_iter()
-        .zip(addresses.iter())
-        .map(|(resp, address)| {
-            let (account, state) = resp.into_parts();
-            (
-                (*address, account.sequence_number()),
-                Duration::from_micros(state.timestamp_usecs).as_secs(),
-            )
-        })
         .unzip();
 
     // return min for the timestamp, to make sure
@@ -944,6 +930,33 @@ where
     Ok((seq_nums, timestamps.into_iter().min().unwrap()))
 }
 
+async fn get_account_if_exists(
+    client: &RestClient,
+    address: AccountAddress,
+) -> Result<((AccountAddress, u64), u64)> {
+    let result = client.get_account_bcs(address).await;
+    match &result {
+        Ok(resp) => Ok((
+            (address, resp.inner().sequence_number()),
+            Duration::from_micros(resp.state().timestamp_usecs).as_secs(),
+        )),
+        Err(e) => {
+            // if account is not present, that is equivalent to sequence_number = 0
+            if let RestError::Api(api_error) = e {
+                if let AptosErrorCode::AccountNotFound = api_error.error.error_code {
+                    return Ok((
+                        (address, 0),
+                        Duration::from_micros(api_error.state.as_ref().unwrap().timestamp_usecs)
+                            .as_secs(),
+                    ));
+                }
+            }
+            result?;
+            unreachable!()
+        },
+    }
+}
+
 pub fn gen_transfer_txn_request(
     sender: &mut LocalAccount,
     receiver: &AccountAddress,
diff --git a/crates/transaction-emitter-lib/src/emitter/submission_worker.rs b/crates/transaction-emitter-lib/src/emitter/submission_worker.rs
index 47903e2cc35ca..54051976a00a4 100644
--- a/crates/transaction-emitter-lib/src/emitter/submission_worker.rs
+++ b/crates/transaction-emitter-lib/src/emitter/submission_worker.rs
@@ -98,73 +98,74 @@ impl SubmissionWorker {
             wait_until += wait_duration;
 
             let requests = self.gen_requests();
+            if !requests.is_empty() {
+                let mut account_to_start_and_end_seq_num = HashMap::new();
+                for req in requests.iter() {
+                    let cur = req.sequence_number();
+                    let _ = *account_to_start_and_end_seq_num
+                        .entry(req.sender())
+                        .and_modify(|(start, end)| {
+                            if *start > cur {
+                                *start = cur;
+                            }
+                            if *end < cur + 1 {
+                                *end = cur + 1;
+                            }
+                        })
+                        .or_insert((cur, cur + 1));
+                }
 
-            let mut account_to_start_and_end_seq_num = HashMap::new();
-            for req in requests.iter() {
-                let cur = req.sequence_number();
-                let _ = *account_to_start_and_end_seq_num
-                    .entry(req.sender())
-                    .and_modify(|(start, end)| {
-                        if *start > cur {
-                            *start = cur;
-                        }
-                        if *end < cur + 1 {
-                            *end = cur + 1;
-                        }
-                    })
-                    .or_insert((cur, cur + 1));
-            }
+                let txn_expiration_time = requests
+                    .iter()
+                    .map(|txn| txn.expiration_timestamp_secs())
+                    .max()
+                    .unwrap_or(0);
 
-            let txn_expiration_time = requests
-                .iter()
-                .map(|txn| txn.expiration_timestamp_secs())
-                .max()
-                .unwrap_or(0);
+                let txn_offset_time = Arc::new(AtomicU64::new(0));
 
-            let txn_offset_time = Arc::new(AtomicU64::new(0));
+                join_all(
+                    requests
+                        .chunks(self.params.max_submit_batch_size)
+                        .map(|reqs| {
+                            submit_transactions(
+                                &self.client,
+                                reqs,
+                                loop_start_time.clone(),
+                                txn_offset_time.clone(),
+                                loop_stats,
+                            )
+                        }),
+                )
+                .await;
 
-            join_all(
-                requests
-                    .chunks(self.params.max_submit_batch_size)
-                    .map(|reqs| {
-                        submit_transactions(
-                            &self.client,
-                            reqs,
-                            loop_start_time.clone(),
-                            txn_offset_time.clone(),
-                            loop_stats,
-                        )
-                    }),
-            )
-            .await;
+                if self.skip_latency_stats {
+                    // we also don't want to be stuck waiting for txn_expiration_time_secs
+                    // after stop is called, so we sleep until time or stop is set.
+                    self.sleep_check_done(Duration::from_secs(
+                        self.params.txn_expiration_time_secs + 20,
+                    ))
+                    .await
+                }
 
-            if self.skip_latency_stats {
-                // we also don't want to be stuck waiting for txn_expiration_time_secs
-                // after stop is called, so we sleep until time or stop is set.
-                self.sleep_check_done(Duration::from_secs(
-                    self.params.txn_expiration_time_secs + 20,
-                ))
-                .await
+                self.wait_and_update_stats(
+                    *loop_start_time,
+                    txn_offset_time.load(Ordering::Relaxed) / (requests.len() as u64),
+                    account_to_start_and_end_seq_num,
+                    // skip latency if asked to check seq_num only once
+                    // even if we check more often due to stop (to not affect sampling)
+                    self.skip_latency_stats,
+                    txn_expiration_time,
+                    // if we don't care about latency, we can recheck less often.
+                    // generally, we should never need to recheck, as we wait enough time
+                    // before calling here, but in case of shutdown/or client we are talking
+                    // to being stale (having stale transaction_version), we might need to wait.
+                    if self.skip_latency_stats { 10 } else { 1 }
+                        * self.params.check_account_sequence_sleep,
+                    loop_stats,
+                )
+                .await;
             }
 
-            self.wait_and_update_stats(
-                *loop_start_time,
-                txn_offset_time.load(Ordering::Relaxed) / (requests.len() as u64),
-                account_to_start_and_end_seq_num,
-                // skip latency if asked to check seq_num only once
-                // even if we check more often due to stop (to not affect sampling)
-                self.skip_latency_stats,
-                txn_expiration_time,
-                // if we don't care about latency, we can recheck less often.
-                // generally, we should never need to recheck, as we wait enough time
-                // before calling here, but in case of shutdown/or client we are talking
-                // to being stale (having stale transaction_version), we might need to wait.
-                if self.skip_latency_stats { 10 } else { 1 }
-                    * self.params.check_account_sequence_sleep,
-                loop_stats,
-            )
-            .await;
-
             let now = Instant::now();
             if wait_until > now {
                 self.sleep_check_done(wait_until - now).await;
@@ -354,11 +355,12 @@ pub async fn submit_transactions(
                         .map_or(-1, |v| v.into_inner().get() as i64);
 
                     warn!(
-                        "[{:?}] Failed to submit {} txns in a batch, first failure due to {:?}, for account {}, first asked: {}, failed seq nums: {:?}, failed error codes: {:?}, balance of {} and last transaction for account: {:?}",
+                        "[{:?}] Failed to submit {} txns in a batch, first failure due to {:?}, for account {}, chain id: {:?}, first asked: {}, failed seq nums: {:?}, failed error codes: {:?}, balance of {} and last transaction for account: {:?}",
                         client.path_prefix_string(),
                         failures.len(),
                         failure,
                         sender,
+                        txns[0].chain_id(),
                         txns[0].sequence_number(),
                         failures.iter().map(|f| txns[f.transaction_index].sequence_number()).collect::>(),
                         by_error,
diff --git a/testsuite/forge-cli/src/main.rs b/testsuite/forge-cli/src/main.rs
index 2c73b25f6621d..12b688a9f0a74 100644
--- a/testsuite/forge-cli/src/main.rs
+++ b/testsuite/forge-cli/src/main.rs
@@ -488,11 +488,12 @@ fn single_test_suite(test_name: &str, duration: Duration) -> Result
     let single_test_suite = match test_name {
         // Land-blocking tests to be run on every PR:
         "land_blocking" => land_blocking_test_suite(duration), // to remove land_blocking, superseeded by the below
-        "realistic_env_max_throughput" => realistic_env_max_throughput_test(duration),
+        "realistic_env_max_load" => realistic_env_max_load_test(duration),
         "compat" => compat(),
         "framework_upgrade" => upgrade(),
         // Rest of the tests:
         "realistic_env_load_sweep" => realistic_env_load_sweep_test(),
+        "realistic_env_graceful_overload" => realistic_env_graceful_overload(),
         "realistic_network_tuned_for_throughput" => realistic_network_tuned_for_throughput_test(),
         "epoch_changer_performance" => epoch_changer_performance(),
         "state_sync_perf_fullnodes_apply_outputs" => state_sync_perf_fullnodes_apply_outputs(),
@@ -513,10 +514,10 @@ fn single_test_suite(test_name: &str, duration: Duration) -> Result
         "single_vfn_perf" => single_vfn_perf(),
         "validator_reboot_stress_test" => validator_reboot_stress_test(),
         "fullnode_reboot_stress_test" => fullnode_reboot_stress_test(),
+        "workload_mix" => workload_mix_test(),
         "account_creation" | "nft_mint" | "publishing" | "module_loading"
         | "write_new_resource" => individual_workload_tests(test_name.into()),
         "graceful_overload" => graceful_overload(),
-        "three_region_simulation_graceful_overload" => three_region_sim_graceful_overload(),
         // not scheduled on continuous
         "load_vs_perf_benchmark" => load_vs_perf_benchmark(),
         "workload_vs_perf_benchmark" => workload_vs_perf_benchmark(),
@@ -543,6 +544,18 @@ fn single_test_suite(test_name: &str, duration: Duration) -> Result
     Ok(single_test_suite)
 }
 
+fn wrap_with_realistic_env(test: T) -> CompositeNetworkTest {
+    CompositeNetworkTest::new_with_two_wrappers(
+        MultiRegionNetworkEmulationTest {
+            override_config: None,
+        },
+        CpuChaosTest {
+            override_config: None,
+        },
+        test,
+    )
+}
+
 fn run_consensus_only_three_region_simulation() -> ForgeConfig {
     ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
@@ -764,34 +777,26 @@ fn realistic_env_load_sweep_test() -> ForgeConfig {
     ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
         .with_initial_fullnode_count(10)
-        .add_network_test(CompositeNetworkTest::new_with_two_wrappers(
-            MultiRegionNetworkEmulationTest {
-                override_config: None,
-            },
-            CpuChaosTest {
-                override_config: None,
-            },
-            LoadVsPerfBenchmark {
-                test: Box::new(PerformanceBenchmark),
-                workloads: Workloads::TPS(&[10, 100, 1000, 3000, 5000]),
-                criteria: [
-                    (9, 1.5, 3.),
-                    (95, 1.5, 3.),
-                    (950, 2., 3.),
-                    (2750, 2.5, 4.),
-                    (4600, 3., 5.),
-                ]
-                .into_iter()
-                .map(|(min_tps, max_lat_p50, max_lat_p99)| {
-                    SuccessCriteria::new(min_tps)
-                        .add_max_expired_tps(0)
-                        .add_max_failed_submission_tps(0)
-                        .add_latency_threshold(max_lat_p50, LatencyType::P50)
-                        .add_latency_threshold(max_lat_p99, LatencyType::P99)
-                })
-                .collect(),
-            },
-        ))
+        .add_network_test(wrap_with_realistic_env(LoadVsPerfBenchmark {
+            test: Box::new(PerformanceBenchmark),
+            workloads: Workloads::TPS(&[10, 100, 1000, 3000, 5000]),
+            criteria: [
+                (9, 1.5, 3.),
+                (95, 1.5, 3.),
+                (950, 2., 3.),
+                (2750, 2.5, 4.),
+                (4600, 3., 5.),
+            ]
+            .into_iter()
+            .map(|(min_tps, max_lat_p50, max_lat_p99)| {
+                SuccessCriteria::new(min_tps)
+                    .add_max_expired_tps(0)
+                    .add_max_failed_submission_tps(0)
+                    .add_latency_threshold(max_lat_p50, LatencyType::P50)
+                    .add_latency_threshold(max_lat_p99, LatencyType::P99)
+            })
+            .collect(),
+        }))
         // Test inherits the main EmitJobRequest, so update here for more precise latency measurements
         .with_emit_job(
             EmitJobRequest::default().latency_polling_interval(Duration::from_millis(100)),
@@ -920,7 +925,7 @@ fn graceful_overload() -> ForgeConfig {
         .with_initial_fullnode_count(10)
         .add_network_test(TwoTrafficsTest {
             inner_traffic: EmitJobRequest::default()
-                .mode(EmitJobMode::ConstTps { tps: 15000 })
+                .mode(EmitJobMode::ConstTps { tps: 10000 })
                 .init_gas_price_multiplier(20),
 
             // Additionally - we are not really gracefully handling overlaods,
@@ -928,7 +933,8 @@ fn graceful_overload() -> ForgeConfig {
             // don't regress, but something to investigate
             inner_success_criteria: SuccessCriteria::new(3400),
         })
-        // First start higher gas-fee traffic, to not cause issues with TxnEmitter setup - account creation
+        // First start non-overload (higher gas-fee) traffic,
+        // to not cause issues with TxnEmitter setup - account creation
         .with_emit_job(
             EmitJobRequest::default()
                 .mode(EmitJobMode::ConstTps { tps: 1000 })
@@ -956,7 +962,7 @@ fn graceful_overload() -> ForgeConfig {
         )
 }
 
-fn three_region_sim_graceful_overload() -> ForgeConfig {
+fn realistic_env_graceful_overload() -> ForgeConfig {
     ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
         // if we have full nodes for subset of validators, TPS drops.
@@ -965,24 +971,25 @@ fn three_region_sim_graceful_overload() -> ForgeConfig {
         // something to potentially improve upon.
         // So having VFNs for all validators
         .with_initial_fullnode_count(20)
-        .add_network_test(CompositeNetworkTest::new(
-            ThreeRegionSameCloudSimulationTest,
-            TwoTrafficsTest {
-                inner_traffic: EmitJobRequest::default()
-                    .mode(EmitJobMode::ConstTps { tps: 15000 })
-                    .init_gas_price_multiplier(20),
-                // Additionally - we are not really gracefully handling overlaods,
-                // setting limits based on current reality, to make sure they
-                // don't regress, but something to investigate
-                inner_success_criteria: SuccessCriteria::new(3400),
-            },
-        ))
+        .add_network_test(wrap_with_realistic_env(TwoTrafficsTest {
+            inner_traffic: EmitJobRequest::default()
+                .mode(EmitJobMode::ConstTps { tps: 15000 })
+                .init_gas_price_multiplier(20),
+            // Additionally - we are not really gracefully handling overlaods,
+            // setting limits based on current reality, to make sure they
+            // don't regress, but something to investigate
+            inner_success_criteria: SuccessCriteria::new(3400),
+        }))
         // First start higher gas-fee traffic, to not cause issues with TxnEmitter setup - account creation
         .with_emit_job(
             EmitJobRequest::default()
                 .mode(EmitJobMode::ConstTps { tps: 1000 })
                 .gas_price(5 * aptos_global_constants::GAS_UNIT_PRICE),
         )
+        .with_node_helm_config_fn(Arc::new(move |helm_values| {
+            helm_values["validator"]["config"]["execution"]
+                ["processed_transactions_detailed_counters"] = true.into();
+        }))
         .with_genesis_helm_config_fn(Arc::new(|helm_values| {
             helm_values["chain"]["epoch_duration_secs"] = 300.into();
         }))
@@ -1005,6 +1012,78 @@ fn three_region_sim_graceful_overload() -> ForgeConfig {
         )
 }
 
+fn workload_mix_test() -> ForgeConfig {
+    ForgeConfig::default()
+        .with_initial_validator_count(NonZeroUsize::new(5).unwrap())
+        .with_initial_fullnode_count(3)
+        .add_network_test(PerformanceBenchmark)
+        .with_node_helm_config_fn(Arc::new(move |helm_values| {
+            helm_values["validator"]["config"]["execution"]
+                ["processed_transactions_detailed_counters"] = true.into();
+        }))
+        .with_emit_job(
+            EmitJobRequest::default()
+                .mode(EmitJobMode::MaxLoad {
+                    mempool_backlog: 10000,
+                })
+                .transaction_mix(vec![
+                    (
+                        TransactionTypeArg::AccountGeneration.materialize_default(),
+                        5,
+                    ),
+                    (TransactionTypeArg::NoOp5Signers.materialize_default(), 1),
+                    (TransactionTypeArg::CoinTransfer.materialize_default(), 1),
+                    (TransactionTypeArg::PublishPackage.materialize_default(), 1),
+                    (
+                        TransactionTypeArg::AccountResource32B.materialize(1, true),
+                        1,
+                    ),
+                    // (
+                    //     TransactionTypeArg::AccountResource10KB.materialize(1, true),
+                    //     1,
+                    // ),
+                    (
+                        TransactionTypeArg::ModifyGlobalResource.materialize(1, false),
+                        1,
+                    ),
+                    // (
+                    //     TransactionTypeArg::ModifyGlobalResource.materialize(10, false),
+                    //     1,
+                    // ),
+                    (
+                        TransactionTypeArg::Batch100Transfer.materialize_default(),
+                        1,
+                    ),
+                    // (
+                    //     TransactionTypeArg::TokenV1NFTMintAndTransferSequential
+                    //         .materialize_default(),
+                    //     1,
+                    // ),
+                    // (
+                    //     TransactionTypeArg::TokenV1NFTMintAndTransferParallel.materialize_default(),
+                    //     1,
+                    // ),
+                    // (
+                    //     TransactionTypeArg::TokenV1FTMintAndTransfer.materialize_default(),
+                    //     1,
+                    // ),
+                    (
+                        TransactionTypeArg::TokenV2AmbassadorMint.materialize_default(),
+                        1,
+                    ),
+                ]),
+        )
+        .with_success_criteria(
+            SuccessCriteria::new(100)
+                .add_no_restarts()
+                .add_wait_for_catchup_s(240)
+                .add_chain_progress(StateProgressThreshold {
+                    max_no_progress_secs: 20.0,
+                    max_round_gap: 6,
+                }),
+        )
+}
+
 fn individual_workload_tests(test_name: String) -> ForgeConfig {
     let job = EmitJobRequest::default().mode(EmitJobMode::MaxLoad {
         mempool_backlog: 30000,
@@ -1370,29 +1449,23 @@ fn land_blocking_test_suite(duration: Duration) -> ForgeConfig {
 }
 
 // TODO: Replace land_blocking when performance reaches on par with current land_blocking
-fn realistic_env_max_throughput_test(duration: Duration) -> ForgeConfig {
+fn realistic_env_max_load_test(duration: Duration) -> ForgeConfig {
+    let duration_secs = duration.as_secs();
     ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
         .with_initial_fullnode_count(10)
-        .add_network_test(CompositeNetworkTest::new_with_two_wrappers(
-            MultiRegionNetworkEmulationTest {
-                override_config: None,
-            },
-            CpuChaosTest {
-                override_config: None,
-            },
-            TwoTrafficsTest {
-                inner_traffic: EmitJobRequest::default()
-                    .mode(EmitJobMode::MaxLoad {
-                        mempool_backlog: 40000,
-                    })
-                    .init_gas_price_multiplier(20),
-                inner_success_criteria: SuccessCriteria::new(5000),
-            },
-        ))
-        .with_genesis_helm_config_fn(Arc::new(|helm_values| {
-            // Have single epoch change in land blocking
-            helm_values["chain"]["epoch_duration_secs"] = 300.into();
+        .add_network_test(wrap_with_realistic_env(TwoTrafficsTest {
+            inner_traffic: EmitJobRequest::default()
+                .mode(EmitJobMode::MaxLoad {
+                    mempool_backlog: 40000,
+                })
+                .init_gas_price_multiplier(20),
+            inner_success_criteria: SuccessCriteria::new(5000),
+        }))
+        .with_genesis_helm_config_fn(Arc::new(move |helm_values| {
+            // Have single epoch change in land blocking, and a few on long-running
+            helm_values["chain"]["epoch_duration_secs"] =
+                (if duration_secs >= 1800 { 600 } else { 300 }).into();
         }))
         // First start higher gas-fee traffic, to not cause issues with TxnEmitter setup - account creation
         .with_emit_job(

From 695bbac6bbe5e3eba67b6a3eede042f961535b1d Mon Sep 17 00:00:00 2001
From: Zorrot Chen 
Date: Fri, 16 Jun 2023 06:54:29 +0800
Subject: [PATCH 185/200] [Spec] update specs of voting.move (#8557)

* init

* fix lint

* fix linter

* fix trimspace

* fix comment

* fix md
---
 .../framework/aptos-framework/doc/voting.md   | 32 ++++++---
 .../aptos-framework/sources/voting.spec.move  | 65 ++++++++++++++-----
 2 files changed, 70 insertions(+), 27 deletions(-)

diff --git a/aptos-move/framework/aptos-framework/doc/voting.md b/aptos-move/framework/aptos-framework/doc/voting.md
index 45d08706a1f34..ef1e50db8fae7 100644
--- a/aptos-move/framework/aptos-framework/doc/voting.md
+++ b/aptos-move/framework/aptos-framework/doc/voting.md
@@ -1555,11 +1555,6 @@ Return true if the voting period of the given proposal has already ended.
 

 
 
-The min_vote_threshold lower thanearly_resolution_vote_threshold.
-Make sure the execution script's hash is not empty.
-VotingForum existed under the voting_forum_address.
-The next_proposal_id in VotingForum is up to MAX_U64.
-CurrentTimeMicroseconds existed under the @aptos_framework.
 
 
 
requires chain_status::is_operating();
@@ -1638,9 +1633,16 @@ CurrentTimeMicroseconds existed under the @aptos_framework.
 
 
requires chain_status::is_operating();
 include AbortsIfNotContainProposalID<ProposalType>;
-aborts_if spec_get_proposal_state<ProposalType>(voting_forum_address, proposal_id) != PROPOSAL_STATE_SUCCEEDED;
 let voting_forum =  global<VotingForum<ProposalType>>(voting_forum_address);
 let proposal = table::spec_get(voting_forum.proposals, proposal_id);
+let early_resolution_threshold = option::spec_borrow(proposal.early_resolution_vote_threshold);
+let voting_period_over = timestamp::now_seconds() > proposal.expiration_secs;
+let be_resolved_early = option::spec_is_some(proposal.early_resolution_vote_threshold) &&
+                            (proposal.yes_votes >= early_resolution_threshold ||
+                             proposal.no_votes >= early_resolution_threshold);
+let voting_closed = voting_period_over || be_resolved_early;
+aborts_if voting_closed && (proposal.yes_votes <= proposal.no_votes || proposal.yes_votes + proposal.no_votes < proposal.min_vote_threshold);
+aborts_if !voting_closed;
 aborts_if proposal.is_resolved;
 aborts_if !std::string::spec_internal_check_utf8(RESOLVABLE_TIME_METADATA_KEY);
 aborts_if !simple_map::spec_contains_key(proposal.metadata, std::string::spec_utf8(RESOLVABLE_TIME_METADATA_KEY));
@@ -1762,11 +1764,23 @@ CurrentTimeMicroseconds existed under the @aptos_framework.
 
 
 
-
pragma opaque;
+
pragma addition_overflow_unchecked;
 requires chain_status::is_operating();
-pragma addition_overflow_unchecked;
 include AbortsIfNotContainProposalID<ProposalType>;
-ensures [abstract] result == spec_get_proposal_state<ProposalType>(voting_forum_address, proposal_id);
+let voting_forum = global<VotingForum<ProposalType>>(voting_forum_address);
+let proposal = table::spec_get(voting_forum.proposals, proposal_id);
+let early_resolution_threshold = option::spec_borrow(proposal.early_resolution_vote_threshold);
+let voting_period_over = timestamp::now_seconds() > proposal.expiration_secs;
+let be_resolved_early = option::spec_is_some(proposal.early_resolution_vote_threshold) &&
+                            (proposal.yes_votes >= early_resolution_threshold ||
+                             proposal.no_votes >= early_resolution_threshold);
+let voting_closed = voting_period_over || be_resolved_early;
+ensures voting_closed ==> if (proposal.yes_votes > proposal.no_votes && proposal.yes_votes + proposal.no_votes >= proposal.min_vote_threshold) {
+    result == PROPOSAL_STATE_SUCCEEDED
+} else {
+    result == PROPOSAL_STATE_FAILED
+};
+ensures !voting_closed ==> result == PROPOSAL_STATE_PENDING;
 

 
 
diff --git a/aptos-move/framework/aptos-framework/sources/voting.spec.move b/aptos-move/framework/aptos-framework/sources/voting.spec.move
index fd3625d61540e..0f523f8b083ad 100644
--- a/aptos-move/framework/aptos-framework/sources/voting.spec.move
+++ b/aptos-move/framework/aptos-framework/sources/voting.spec.move
@@ -36,11 +36,11 @@ spec aptos_framework::voting {
         include CreateProposalAbortsIf{is_multi_step_proposal: false};
     }
 
-    /// The min_vote_threshold lower thanearly_resolution_vote_threshold.
-    /// Make sure the execution script's hash is not empty.
-    /// VotingForum existed under the voting_forum_address.
-    /// The next_proposal_id in VotingForum is up to MAX_U64.
-    /// CurrentTimeMicroseconds existed under the @aptos_framework.
+    // The min_vote_threshold lower thanearly_resolution_vote_threshold.
+    // Make sure the execution script's hash is not empty.
+    // VotingForum existed under the voting_forum_address.
+    // The next_proposal_id in VotingForum is up to MAX_U64.
+    // CurrentTimeMicroseconds existed under the @aptos_framework.
     spec create_proposal_v2(
         proposer: address,
         voting_forum_address: address,
@@ -90,7 +90,8 @@ spec aptos_framework::voting {
         should_pass: bool,
     ) {
         use aptos_framework::chain_status;
-        requires chain_status::is_operating(); // Ensures existence of Timestamp
+        // Ensures existence of Timestamp
+        requires chain_status::is_operating();
 
         aborts_if !exists>(voting_forum_address);
         let voting_forum = global>(voting_forum_address);
@@ -116,14 +117,22 @@ spec aptos_framework::voting {
     ) {
 
         use aptos_framework::chain_status;
-
-        requires chain_status::is_operating(); // Ensures existence of Timestamp
+        // Ensures existence of Timestamp
+        requires chain_status::is_operating();
         include AbortsIfNotContainProposalID;
-        // If the proposal is not resolvable, this function aborts.
-        aborts_if spec_get_proposal_state(voting_forum_address, proposal_id) != PROPOSAL_STATE_SUCCEEDED;
 
         let voting_forum =  global>(voting_forum_address);
         let proposal = table::spec_get(voting_forum.proposals, proposal_id);
+        let early_resolution_threshold = option::spec_borrow(proposal.early_resolution_vote_threshold);
+        let voting_period_over = timestamp::now_seconds() > proposal.expiration_secs;
+        let be_resolved_early = option::spec_is_some(proposal.early_resolution_vote_threshold) &&
+                                    (proposal.yes_votes >= early_resolution_threshold ||
+                                     proposal.no_votes >= early_resolution_threshold);
+        let voting_closed = voting_period_over || be_resolved_early;
+        // Avoid Overflow
+        aborts_if voting_closed && (proposal.yes_votes <= proposal.no_votes || proposal.yes_votes + proposal.no_votes < proposal.min_vote_threshold);
+        // Resolvable_time Properties
+        aborts_if !voting_closed;
 
         aborts_if proposal.is_resolved;
         aborts_if !std::string::spec_internal_check_utf8(RESOLVABLE_TIME_METADATA_KEY);
@@ -138,7 +147,8 @@ spec aptos_framework::voting {
         proposal_id: u64,
     ): ProposalType {
         use aptos_framework::chain_status;
-        requires chain_status::is_operating(); // Ensures existence of Timestamp
+        // Ensures existence of Timestamp
+        requires chain_status::is_operating();
 
         pragma aborts_if_is_partial;
         include AbortsIfNotContainProposalID;
@@ -151,7 +161,8 @@ spec aptos_framework::voting {
         next_execution_hash: vector,
     ) {
         use aptos_framework::chain_status;
-        requires chain_status::is_operating(); // Ensures existence of Timestamp
+        // Ensures existence of Timestamp
+        requires chain_status::is_operating();
 
         pragma aborts_if_is_partial;
         include AbortsIfNotContainProposalID;
@@ -165,7 +176,8 @@ spec aptos_framework::voting {
 
     spec is_voting_closed(voting_forum_address: address, proposal_id: u64): bool {
         use aptos_framework::chain_status;
-        requires chain_status::is_operating(); // Ensures existence of Timestamp
+        // Ensures existence of Timestamp
+        requires chain_status::is_operating();
         include AbortsIfNotContainProposalID;
     }
 
@@ -184,14 +196,31 @@ spec aptos_framework::voting {
     ): u64 {
 
         use aptos_framework::chain_status;
-        pragma opaque;
-        requires chain_status::is_operating(); // Ensures existence of Timestamp
-        // Addition of yes_votes and no_votes might overflow.
+
         pragma addition_overflow_unchecked;
+        // Ensures existence of Timestamp
+        requires chain_status::is_operating();
 
         include AbortsIfNotContainProposalID;
-        // Any way to specify the result?
-        ensures [abstract] result == spec_get_proposal_state(voting_forum_address, proposal_id);
+
+        let voting_forum = global>(voting_forum_address);
+        let proposal = table::spec_get(voting_forum.proposals, proposal_id);
+        let early_resolution_threshold = option::spec_borrow(proposal.early_resolution_vote_threshold);
+        let voting_period_over = timestamp::now_seconds() > proposal.expiration_secs;
+        let be_resolved_early = option::spec_is_some(proposal.early_resolution_vote_threshold) &&
+                                    (proposal.yes_votes >= early_resolution_threshold ||
+                                     proposal.no_votes >= early_resolution_threshold);
+        let voting_closed = voting_period_over || be_resolved_early;
+        // Voting Succeeded or Failed
+        ensures voting_closed ==> if (proposal.yes_votes > proposal.no_votes && proposal.yes_votes + proposal.no_votes >= proposal.min_vote_threshold) {
+            result == PROPOSAL_STATE_SUCCEEDED
+        } else {
+            result == PROPOSAL_STATE_FAILED
+        };
+
+        // Voting is Pending
+        ensures !voting_closed ==> result == PROPOSAL_STATE_PENDING;
+
     }
 
     spec get_proposal_creation_secs(

From 903c68421c5509c8e3c4fcbdcb0e9fb9e27fc964 Mon Sep 17 00:00:00 2001
From: danielx <66756900+danielxiangzl@users.noreply.github.com>
Date: Thu, 15 Jun 2023 17:48:36 -0700
Subject: [PATCH 186/200] [BlockSTM] Better naming for execution task (#8694)

[BlockSTM] Better naming for execution task
---
 aptos-move/aptos-vm-types/src/output.rs       |  8 +-
 aptos-move/block-executor/src/executor.rs     | 34 ++++----
 aptos-move/block-executor/src/scheduler.rs    | 83 ++++++++++++-------
 .../block-executor/src/unit_tests/mod.rs      | 34 ++++----
 4 files changed, 92 insertions(+), 67 deletions(-)

diff --git a/aptos-move/aptos-vm-types/src/output.rs b/aptos-move/aptos-vm-types/src/output.rs
index eb34dab0b24ec..5e40abf94dc67 100644
--- a/aptos-move/aptos-vm-types/src/output.rs
+++ b/aptos-move/aptos-vm-types/src/output.rs
@@ -91,9 +91,13 @@ impl VMOutput {
         }
 
         // Try to materialize deltas and add them to the write set.
-        let (change_set, gas_used, status) = self.unpack_with_fee_statement();
+        let (change_set, fee_statement, status) = self.unpack_with_fee_statement();
         let materialized_change_set = change_set.try_materialize(state_view)?;
-        Ok(VMOutput::new(materialized_change_set, gas_used, status))
+        Ok(VMOutput::new(
+            materialized_change_set,
+            fee_statement,
+            status,
+        ))
     }
 
     /// Converts VMOutput into TransactionOutput which can be used by storage
diff --git a/aptos-move/block-executor/src/executor.rs b/aptos-move/block-executor/src/executor.rs
index c54f1d97af92a..2faf75efbd20c 100644
--- a/aptos-move/block-executor/src/executor.rs
+++ b/aptos-move/block-executor/src/executor.rs
@@ -9,7 +9,7 @@ use crate::{
         TASK_VALIDATE_SECONDS, VM_INIT_SECONDS, WORK_WITH_TASK_SECONDS,
     },
     errors::*,
-    scheduler::{DependencyStatus, Scheduler, SchedulerTask, Wave},
+    scheduler::{DependencyStatus, ExecutionTaskType, Scheduler, SchedulerTask, Wave},
     task::{ExecutionStatus, ExecutorTask, Transaction, TransactionOutput},
     txn_last_input_output::TxnLastInputOutput,
     view::{LatestView, MVHashMapView},
@@ -432,11 +432,11 @@ where
 
             // Remark: When early halting the BlockSTM, we have to make sure the current / new tasks
             // will be properly handled by the threads. For instance, it is possible that the committing
-            // thread holds an execution task from the last iteration, and then early halts the BlockSTM
-            // due to a txn execution abort. In this case, we cannot reset the scheduler_task of the
-            // committing thread (to be Done), otherwise some other pending thread waiting for the execution
-            // will be pending on read forever (since the halt logic let the execution task to wake up such
-            // pending task).
+            // thread holds an execution task of ExecutionTaskType::Wakeup(DependencyCondvar) for some
+            // other thread pending on the dependency conditional variable from the last iteration. If
+            // the committing thread early halts BlockSTM and resets its scheduler_task to be Done, the
+            // pending thread will be pending on read forever. In other words, we rely on the committing
+            // thread to wake up the pending execution thread, if the committing thread holds the Wakeup task.
         }
     }
 
@@ -539,16 +539,18 @@ where
                     versioned_cache,
                     scheduler,
                 ),
-                SchedulerTask::ExecutionTask(version_to_execute, None) => self.execute(
-                    version_to_execute,
-                    block,
-                    last_input_output,
-                    versioned_cache,
-                    scheduler,
-                    &executor,
-                    base_view,
-                ),
-                SchedulerTask::ExecutionTask(_, Some(condvar)) => {
+                SchedulerTask::ExecutionTask(version_to_execute, ExecutionTaskType::Execution) => {
+                    self.execute(
+                        version_to_execute,
+                        block,
+                        last_input_output,
+                        versioned_cache,
+                        scheduler,
+                        &executor,
+                        base_view,
+                    )
+                },
+                SchedulerTask::ExecutionTask(_, ExecutionTaskType::Wakeup(condvar)) => {
                     let (lock, cvar) = &*condvar;
                     // Mark dependency resolved.
                     *lock.lock() = DependencyStatus::Resolved;
diff --git a/aptos-move/block-executor/src/scheduler.rs b/aptos-move/block-executor/src/scheduler.rs
index 4a0c12312c3a8..f13dcbd2bcc33 100644
--- a/aptos-move/block-executor/src/scheduler.rs
+++ b/aptos-move/block-executor/src/scheduler.rs
@@ -39,13 +39,22 @@ pub enum DependencyResult {
     ExecutionHalted,
 }
 
+/// Two types of execution tasks: Execution and Wakeup.
+/// Execution is a normal execution task, Wakeup is a task that just wakes up a suspended execution.
+/// See explanations for the ExecutionStatus below.
+#[derive(Debug, Clone)]
+pub enum ExecutionTaskType {
+    Execution,
+    Wakeup(DependencyCondvar),
+}
+
 /// A holder for potential task returned from the Scheduler. ExecutionTask and ValidationTask
 /// each contain a version of transaction that must be executed or validated, respectively.
 /// NoTask holds no task (similar None if we wrapped tasks in Option), and Done implies that
 /// there are no more tasks and the scheduler is done.
 #[derive(Debug)]
 pub enum SchedulerTask {
-    ExecutionTask(Version, Option),
+    ExecutionTask(Version, ExecutionTaskType),
     ValidationTask(Version, Wave),
     NoTask,
     Done,
@@ -56,21 +65,24 @@ pub enum SchedulerTask {
 /// 'execution status' as 'status'. Each status contains the latest incarnation number,
 /// where incarnation = i means it is the i-th execution instance of the transaction.
 ///
-/// 'ReadyToExecute' means that the corresponding incarnation should be executed and the scheduler
+/// 'Ready' means that the corresponding incarnation should be executed and the scheduler
 /// must eventually create a corresponding execution task. The scheduler ensures that exactly one
-/// execution task gets created, changing the status to 'Executing' in the process. If a dependency
-/// condition variable is set, then an execution of a prior incarnation is waiting on it with
-/// a read dependency resolved (when dependency was encountered, the status changed to Suspended,
-/// and suspended changed to ReadyToExecute when the dependency finished its execution). In this case
-/// the caller need not create a new execution task, but just notify the suspended execution.
+/// execution task gets created, changing the status to 'Executing' in the process. 'Ready' status
+/// contains an ExecutionTaskType, which is either Execution or Wakeup. If it is Execution, then
+/// the scheduler creates an execution task for the corresponding incarnation. If it is Wakeup,
+/// a dependency condition variable is set in ExecutionTaskType::Wakeup(DependencyCondvar): an execution
+/// of a prior incarnation is waiting on it with a read dependency resolved (when dependency was
+/// encountered, the status changed to Suspended, and suspended changed to Ready when the dependency
+/// finished its execution). In this case the caller need not create a new execution task, but
+/// just notify the suspended execution via the dependency condition variable.
 ///
 /// 'Executing' status of an incarnation turns into 'Executed' if the execution task finishes, or
-/// if a dependency is encountered, it becomes 'ReadyToExecute(incarnation + 1)' once the
+/// if a dependency is encountered, it becomes 'Ready(incarnation + 1)' once the
 /// dependency is resolved. An 'Executed' status allows creation of validation tasks for the
 /// corresponding incarnation, and a validation failure leads to an abort. The scheduler ensures
 /// that there is exactly one abort, changing the status to 'Aborting' in the process. Once the
 /// thread that successfully aborted performs everything that's required, it sets the status
-/// to 'ReadyToExecute(incarnation + 1)', allowing the scheduler to create an execution
+/// to 'Ready(incarnation + 1)', allowing the scheduler to create an execution
 /// task for the next incarnation of the transaction.
 ///
 /// 'ExecutionHalted' is a transaction status marking that parallel execution is halted, due to
@@ -95,7 +107,7 @@ pub enum SchedulerTask {
 ///
 #[derive(Debug)]
 enum ExecutionStatus {
-    ReadyToExecute(Incarnation, Option),
+    Ready(Incarnation, ExecutionTaskType),
     Executing(Incarnation),
     Suspended(Incarnation, DependencyCondvar),
     Executed(Incarnation),
@@ -108,7 +120,7 @@ impl PartialEq for ExecutionStatus {
     fn eq(&self, other: &Self) -> bool {
         use ExecutionStatus::*;
         match (self, other) {
-            (&ReadyToExecute(ref a, _), &ReadyToExecute(ref b, _))
+            (&Ready(ref a, _), &Ready(ref b, _))
             | (&Executing(ref a), &Executing(ref b))
             | (&Suspended(ref a, _), &Suspended(ref b, _))
             | (&Executed(ref a), &Executed(ref b))
@@ -208,7 +220,7 @@ pub struct Scheduler {
     // validation/execution preferences stick to the worker threads).
     /// A shared index that tracks the minimum of all transaction indices that require execution.
     /// The threads increment the index and attempt to create an execution task for the corresponding
-    /// transaction, if the status of the txn is 'ReadyToExecute'. This implements a counting-based
+    /// transaction, if the status of the txn is 'Ready'. This implements a counting-based
     /// concurrent ordered set. It is reduced as necessary when transactions become ready to be
     /// executed, in particular, when execution finishes and dependencies are resolved.
     execution_idx: AtomicU32,
@@ -242,7 +254,7 @@ impl Scheduler {
             txn_status: (0..num_txns)
                 .map(|_| {
                     CachePadded::new((
-                        RwLock::new(ExecutionStatus::ReadyToExecute(0, None)),
+                        RwLock::new(ExecutionStatus::Ready(0, ExecutionTaskType::Execution)),
                         RwLock::new(ValidationStatus::new()),
                     ))
                 })
@@ -368,10 +380,10 @@ impl Scheduler {
                 {
                     return SchedulerTask::ValidationTask(version_to_validate, wave);
                 }
-            } else if let Some((version_to_execute, maybe_condvar)) =
+            } else if let Some((version_to_execute, execution_task_type)) =
                 self.try_execute_next_version()
             {
-                return SchedulerTask::ExecutionTask(version_to_execute, maybe_condvar);
+                return SchedulerTask::ExecutionTask(version_to_execute, execution_task_type);
             }
         }
     }
@@ -468,7 +480,7 @@ impl Scheduler {
         let min_dep = txn_deps
             .into_iter()
             .map(|dep| {
-                // Mark the status of dependencies as 'ReadyToExecute' since dependency on
+                // Mark the status of dependencies as 'Ready' since dependency on
                 // transaction txn_idx is now resolved.
                 self.resume(dep);
 
@@ -536,8 +548,11 @@ impl Scheduler {
             // re-execution task back to the caller. If incarnation fails, there is
             // nothing to do, as another thread must have succeeded to incarnate and
             // obtain the task for re-execution.
-            if let Some((new_incarnation, maybe_condvar)) = self.try_incarnate(txn_idx) {
-                return SchedulerTask::ExecutionTask((txn_idx, new_incarnation), maybe_condvar);
+            if let Some((new_incarnation, execution_task_type)) = self.try_incarnate(txn_idx) {
+                return SchedulerTask::ExecutionTask(
+                    (txn_idx, new_incarnation),
+                    execution_task_type,
+                );
             }
         }
 
@@ -573,10 +588,10 @@ impl Scheduler {
     pub fn resolve_condvar(&self, txn_idx: TxnIndex) {
         let mut status = self.txn_status[txn_idx as usize].0.write();
         {
-            // Only transactions with status Suspended or ReadyToExecute may have the condition variable of pending threads.
+            // Only transactions with status Suspended or Ready may have the condition variable of pending threads.
             match &*status {
                 ExecutionStatus::Suspended(_, condvar)
-                | ExecutionStatus::ReadyToExecute(_, Some(condvar)) => {
+                | ExecutionStatus::Ready(_, ExecutionTaskType::Wakeup(condvar)) => {
                     let (lock, cvar) = &*(condvar.clone());
                     // Mark parallel execution halted due to reasons like module r/w intersection.
                     *lock.lock() = DependencyStatus::ExecutionHalted;
@@ -639,11 +654,11 @@ impl Scheduler {
     }
 
     /// Try and incarnate a transaction. Only possible when the status is
-    /// ReadyToExecute(incarnation), in which case Some(incarnation) is returned and the
+    /// Ready(incarnation), in which case Some(incarnation) is returned and the
     /// status is (atomically, due to the mutex) updated to Executing(incarnation).
     /// An unsuccessful incarnation returns None. Since incarnation numbers never decrease
     /// for each transaction, incarnate function may not succeed more than once per version.
-    fn try_incarnate(&self, txn_idx: TxnIndex) -> Option<(Incarnation, Option)> {
+    fn try_incarnate(&self, txn_idx: TxnIndex) -> Option<(Incarnation, ExecutionTaskType)> {
         if txn_idx >= self.num_txns {
             return None;
         }
@@ -652,8 +667,8 @@ impl Scheduler {
         // However, it is likely an overkill (and overhead to actually upgrade),
         // while unlikely there would be much contention on a specific index lock.
         let mut status = self.txn_status[txn_idx as usize].0.write();
-        if let ExecutionStatus::ReadyToExecute(incarnation, maybe_condvar) = &*status {
-            let ret = (*incarnation, maybe_condvar.clone());
+        if let ExecutionStatus::Ready(incarnation, execution_task_type) = &*status {
+            let ret: (u32, ExecutionTaskType) = (*incarnation, (*execution_task_type).clone());
             *status = ExecutionStatus::Executing(*incarnation);
             Some(ret)
         } else {
@@ -695,7 +710,7 @@ impl Scheduler {
         let status = self.txn_status[txn_idx as usize].0.read();
         matches!(
             *status,
-            ExecutionStatus::ReadyToExecute(0, _)
+            ExecutionStatus::Ready(0, _)
                 | ExecutionStatus::Executing(0)
                 | ExecutionStatus::Suspended(0, _)
         )
@@ -744,11 +759,11 @@ impl Scheduler {
     /// Grab an index to try and execute next (by fetch-and-incrementing execution_idx).
     /// - If the index is out of bounds, return None (and invoke a check of whether
     /// all txns can be committed).
-    /// - If the transaction is ready for execution (ReadyToExecute state), attempt
+    /// - If the transaction is ready for execution (Ready state), attempt
     /// to create the next incarnation (should happen exactly once), and if successful,
     /// return the version to the caller for the corresponding ExecutionTask.
     /// - Otherwise, return None.
-    fn try_execute_next_version(&self) -> Option<(Version, Option)> {
+    fn try_execute_next_version(&self) -> Option<(Version, ExecutionTaskType)> {
         let idx_to_execute = self.execution_idx.fetch_add(1, Ordering::SeqCst);
 
         if idx_to_execute >= self.num_txns {
@@ -758,7 +773,9 @@ impl Scheduler {
         // If successfully incarnated (changed status from ready to executing),
         // return version for execution task, otherwise None.
         self.try_incarnate(idx_to_execute)
-            .map(|(incarnation, maybe_condvar)| ((idx_to_execute, incarnation), maybe_condvar))
+            .map(|(incarnation, execution_task_type)| {
+                ((idx_to_execute, incarnation), execution_task_type)
+            })
     }
 
     /// Put a transaction in a suspended state, with a condition variable that can be
@@ -767,7 +784,6 @@ impl Scheduler {
     /// Return false when the execution is halted.
     fn suspend(&self, txn_idx: TxnIndex, dep_condvar: DependencyCondvar) -> bool {
         let mut status = self.txn_status[txn_idx as usize].0.write();
-
         match *status {
             ExecutionStatus::Executing(incarnation) => {
                 *status = ExecutionStatus::Suspended(incarnation, dep_condvar);
@@ -778,7 +794,7 @@ impl Scheduler {
         }
     }
 
-    /// When a dependency is resolved, mark the transaction as ReadyToExecute with an
+    /// When a dependency is resolved, mark the transaction as Ready with an
     /// incremented incarnation number.
     /// The caller must ensure that the transaction is in the Suspended state.
     fn resume(&self, txn_idx: TxnIndex) {
@@ -789,7 +805,10 @@ impl Scheduler {
         }
 
         if let ExecutionStatus::Suspended(incarnation, dep_condvar) = &*status {
-            *status = ExecutionStatus::ReadyToExecute(*incarnation, Some(dep_condvar.clone()));
+            *status = ExecutionStatus::Ready(
+                *incarnation,
+                ExecutionTaskType::Wakeup(dep_condvar.clone()),
+            );
         } else {
             unreachable!();
         }
@@ -819,7 +838,7 @@ impl Scheduler {
 
         // Only makes sense when the current status is 'Aborting'.
         debug_assert!(*status == ExecutionStatus::Aborting(incarnation));
-        *status = ExecutionStatus::ReadyToExecute(incarnation + 1, None);
+        *status = ExecutionStatus::Ready(incarnation + 1, ExecutionTaskType::Execution);
     }
 
     /// Checks whether the done marker is set. The marker can only be set by 'try_commit'.
diff --git a/aptos-move/block-executor/src/unit_tests/mod.rs b/aptos-move/block-executor/src/unit_tests/mod.rs
index 60458ee9dae09..fc69a0bbd986e 100644
--- a/aptos-move/block-executor/src/unit_tests/mod.rs
+++ b/aptos-move/block-executor/src/unit_tests/mod.rs
@@ -5,7 +5,7 @@
 use crate::{
     executor::BlockExecutor,
     proptest_types::types::{DeltaDataView, ExpectedOutput, KeyType, Task, Transaction, ValueType},
-    scheduler::{DependencyResult, Scheduler, SchedulerTask},
+    scheduler::{DependencyResult, ExecutionTaskType, Scheduler, SchedulerTask},
 };
 use aptos_aggregator::delta_change_set::{delta_add, delta_sub, DeltaOp, DeltaUpdate};
 use aptos_mvhashmap::types::TxnIndex;
@@ -278,7 +278,7 @@ fn scheduler_tasks() {
         // No validation tasks.
         assert!(matches!(
             s.next_task(false),
-            SchedulerTask::ExecutionTask((j, 0), None) if i == j
+            SchedulerTask::ExecutionTask((j, 0), ExecutionTaskType::Execution) if i == j
         ));
     }
 
@@ -310,16 +310,16 @@ fn scheduler_tasks() {
 
     assert!(matches!(
         s.finish_abort(4, 0),
-        SchedulerTask::ExecutionTask((4, 1), None)
+        SchedulerTask::ExecutionTask((4, 1), ExecutionTaskType::Execution)
     ));
     assert!(matches!(
         s.finish_abort(1, 0),
-        SchedulerTask::ExecutionTask((1, 1), None)
+        SchedulerTask::ExecutionTask((1, 1), ExecutionTaskType::Execution)
     ));
     // Validation index = 2, wave = 1.
     assert!(matches!(
         s.finish_abort(3, 0),
-        SchedulerTask::ExecutionTask((3, 1), None)
+        SchedulerTask::ExecutionTask((3, 1), ExecutionTaskType::Execution)
     ));
 
     assert!(matches!(
@@ -369,7 +369,7 @@ fn scheduler_first_wave() {
         // Nothing to validate.
         assert!(matches!(
             s.next_task(false),
-            SchedulerTask::ExecutionTask((j, 0), None) if j == i
+            SchedulerTask::ExecutionTask((j, 0), ExecutionTaskType::Execution) if j == i
         ));
     }
 
@@ -387,7 +387,7 @@ fn scheduler_first_wave() {
     ));
     assert!(matches!(
         s.next_task(false),
-        SchedulerTask::ExecutionTask((5, 0), None)
+        SchedulerTask::ExecutionTask((5, 0), ExecutionTaskType::Execution)
     ));
     // Since (1, 0) is not EXECUTED, no validation tasks, and execution index
     // is already at the limit, so no tasks immediately available.
@@ -424,7 +424,7 @@ fn scheduler_dependency() {
         // Nothing to validate.
         assert!(matches!(
             s.next_task(false),
-            SchedulerTask::ExecutionTask((j, 0), None) if j == i
+            SchedulerTask::ExecutionTask((j, 0), ExecutionTaskType::Execution) if j == i
         ));
     }
 
@@ -458,7 +458,7 @@ fn scheduler_dependency() {
     // resumed task doesn't bump incarnation
     assert!(matches!(
         s.next_task(false),
-        SchedulerTask::ExecutionTask((4, 0), Some(_))
+        SchedulerTask::ExecutionTask((4, 0), ExecutionTaskType::Wakeup(_))
     ));
 }
 
@@ -471,7 +471,7 @@ fn incarnation_one_scheduler(num_txns: TxnIndex) -> Scheduler {
         // Get the first executions out of the way.
         assert!(matches!(
             s.next_task(false),
-            SchedulerTask::ExecutionTask((j, 0), None) if j == i
+            SchedulerTask::ExecutionTask((j, 0), ExecutionTaskType::Execution) if j == i
         ));
         assert!(matches!(
             s.finish_execution(i, 0, false),
@@ -484,7 +484,7 @@ fn incarnation_one_scheduler(num_txns: TxnIndex) -> Scheduler {
         assert!(s.try_abort(i, 0));
         assert!(matches!(
             s.finish_abort(i, 0),
-            SchedulerTask::ExecutionTask((j, 1), None) if i == j
+            SchedulerTask::ExecutionTask((j, 1), ExecutionTaskType::Execution) if i == j
         ));
     }
     s
@@ -528,7 +528,7 @@ fn scheduler_incarnation() {
 
     assert!(matches!(
         s.finish_abort(2, 1),
-        SchedulerTask::ExecutionTask((2, 2), None)
+        SchedulerTask::ExecutionTask((2, 2), ExecutionTaskType::Execution)
     ));
     // wave = 2, validation index = 2.
     assert!(matches!(
@@ -541,15 +541,15 @@ fn scheduler_incarnation() {
 
     assert!(matches!(
         s.next_task(false),
-        SchedulerTask::ExecutionTask((1, 1), Some(_))
+        SchedulerTask::ExecutionTask((1, 1), ExecutionTaskType::Wakeup(_))
     ));
     assert!(matches!(
         s.next_task(false),
-        SchedulerTask::ExecutionTask((3, 1), Some(_))
+        SchedulerTask::ExecutionTask((3, 1), ExecutionTaskType::Wakeup(_))
     ));
     assert!(matches!(
         s.next_task(false),
-        SchedulerTask::ExecutionTask((4, 2), None)
+        SchedulerTask::ExecutionTask((4, 2), ExecutionTaskType::Execution)
     ));
     // execution index = 5
 
@@ -585,7 +585,7 @@ fn scheduler_basic() {
         // Nothing to validate.
         assert!(matches!(
             s.next_task(false),
-            SchedulerTask::ExecutionTask((j, 0), None) if j == i
+            SchedulerTask::ExecutionTask((j, 0), ExecutionTaskType::Execution) if j == i
         ));
     }
 
@@ -635,7 +635,7 @@ fn scheduler_drain_idx() {
         // Nothing to validate.
         assert!(matches!(
             s.next_task(false),
-            SchedulerTask::ExecutionTask((j, 0), None) if j == i
+            SchedulerTask::ExecutionTask((j, 0), ExecutionTaskType::Execution) if j == i
         ));
     }
 

From fa01eb064287a138eb73a4e895befde6819414e9 Mon Sep 17 00:00:00 2001
From: Zorrot Chen 
Date: Fri, 16 Jun 2023 14:40:09 +0800
Subject: [PATCH 187/200] [Spec] update specs of aptos_governance (#8657)

* init

* new schema

* fix comment and lint

* fix comment and schema

* add md

---------

Co-authored-by: chan-bing 
---
 .../aptos-framework/doc/aptos_governance.md   | 337 +++++++++++----
 .../sources/aptos_governance.spec.move        | 395 +++++++++++++++---
 2 files changed, 588 insertions(+), 144 deletions(-)

diff --git a/aptos-move/framework/aptos-framework/doc/aptos_governance.md b/aptos-move/framework/aptos-framework/doc/aptos_governance.md
index d78f3b61a221c..94ec6f5ae0ed0 100644
--- a/aptos-move/framework/aptos-framework/doc/aptos_governance.md
+++ b/aptos-move/framework/aptos-framework/doc/aptos_governance.md
@@ -1487,8 +1487,7 @@ Address @aptos_framework must exist GovernanceConfig and GovernanceEvents.
 The same as spec of create_proposal_v2().
 
 
-
pragma aborts_if_is_partial;
-requires chain_status::is_operating();
+
requires chain_status::is_operating();
 include CreateProposalAbortsIf;
 

 
@@ -1505,43 +1504,11 @@ The same as spec of chain_status::is_operating();
+
requires chain_status::is_operating();
 include CreateProposalAbortsIf;
 

 
 
-stake_pool must exist StakePool.
-The delegated voter under the resource StakePool of the stake_pool must be the proposer address.
-Address @aptos_framework must exist GovernanceEvents.
-
-
-
-
-
-
schema CreateProposalAbortsIf {
-    proposer: &signer;
-    stake_pool: address;
-    execution_hash: vector<u8>;
-    metadata_location: vector<u8>;
-    metadata_hash: vector<u8>;
-    let proposer_address = signer::address_of(proposer);
-    let governance_config = global<GovernanceConfig>(@aptos_framework);
-    let stake_pool_res = global<stake::StakePool>(stake_pool);
-    aborts_if !exists<staking_config::StakingConfig>(@aptos_framework);
-    aborts_if !exists<stake::StakePool>(stake_pool);
-    aborts_if global<stake::StakePool>(stake_pool).delegated_voter != proposer_address;
-    include AbortsIfNotGovernanceConfig;
-    let current_time = timestamp::now_seconds();
-    let proposal_expiration = current_time + governance_config.voting_duration_secs;
-    aborts_if stake_pool_res.locked_until_secs < proposal_expiration;
-    aborts_if !exists<GovernanceEvents>(@aptos_framework);
-    let allow_validator_set_change = global<staking_config::StakingConfig>(@aptos_framework).allow_validator_set_change;
-    aborts_if !allow_validator_set_change && !exists<stake::ValidatorSet>(@aptos_framework);
-}
-

-
-
 
 
 
@@ -1557,21 +1524,105 @@ The delegated voter under the resource StakePool of the stake_pool must be the v
 Address @aptos_framework must exist VotingRecords and GovernanceProposal.
 
 
-
pragma aborts_if_is_partial;
-requires chain_status::is_operating();
-let voter_address = signer::address_of(voter);
-let stake_pool_res = global<stake::StakePool>(stake_pool);
-aborts_if !exists<stake::StakePool>(stake_pool);
-aborts_if stake_pool_res.delegated_voter != voter_address;
+
requires chain_status::is_operating();
+include VotingGetDelegatedVoterAbortsIf { sign: voter };
 aborts_if !exists<VotingRecords>(@aptos_framework);
-aborts_if !exists<voting::VotingForum<GovernanceProposal>>(@aptos_framework);
+let voting_records = global<VotingRecords>(@aptos_framework);
+let record_key = RecordKey {
+    stake_pool,
+    proposal_id,
+};
+let post post_voting_records = global<VotingRecords>(@aptos_framework);
+aborts_if table::spec_contains(voting_records.votes, record_key);
+ensures table::spec_get(post_voting_records.votes, record_key) == true;
+include GetVotingPowerAbortsIf { pool_address: stake_pool };
 let allow_validator_set_change = global<staking_config::StakingConfig>(@aptos_framework).allow_validator_set_change;
-aborts_if !allow_validator_set_change && !exists<stake::ValidatorSet>(@aptos_framework);
+let stake_pool_res = global<stake::StakePool>(stake_pool);
+let voting_power_0 = stake_pool_res.active.value + stake_pool_res.pending_active.value + stake_pool_res.pending_inactive.value;
+let voting_power_1 = stake_pool_res.active.value + stake_pool_res.pending_inactive.value;
+aborts_if allow_validator_set_change && voting_power_0 <= 0;
+aborts_if !allow_validator_set_change && stake::spec_is_current_epoch_validator(stake_pool) && voting_power_1 <= 0;
+aborts_if !allow_validator_set_change && !stake::spec_is_current_epoch_validator(stake_pool);
+aborts_if !exists<voting::VotingForum<GovernanceProposal>>(@aptos_framework);
 let voting_forum = global<voting::VotingForum<GovernanceProposal>>(@aptos_framework);
 let proposal = table::spec_get(voting_forum.proposals, proposal_id);
+aborts_if !table::spec_contains(voting_forum.proposals, proposal_id);
 let proposal_expiration = proposal.expiration_secs;
 let locked_until_secs = global<stake::StakePool>(stake_pool).locked_until_secs;
 aborts_if proposal_expiration > locked_until_secs;
+aborts_if timestamp::now_seconds() > proposal_expiration;
+aborts_if proposal.is_resolved;
+aborts_if !string::spec_internal_check_utf8(voting::IS_MULTI_STEP_PROPOSAL_IN_EXECUTION_KEY);
+let execution_key = utf8(voting::IS_MULTI_STEP_PROPOSAL_IN_EXECUTION_KEY);
+aborts_if simple_map::spec_contains_key(proposal.metadata, execution_key) &&
+          simple_map::spec_get(proposal.metadata, execution_key) != std::bcs::to_bytes(false);
+aborts_if allow_validator_set_change &&
+    if (should_pass) { proposal.yes_votes + voting_power_0 > MAX_U128 } else { proposal.no_votes + voting_power_0 > MAX_U128 };
+aborts_if !allow_validator_set_change &&
+    if (should_pass) { proposal.yes_votes + voting_power_1 > MAX_U128 } else { proposal.no_votes + voting_power_1 > MAX_U128 };
+let post post_voting_forum = global<voting::VotingForum<GovernanceProposal>>(@aptos_framework);
+let post post_proposal = table::spec_get(post_voting_forum.proposals, proposal_id);
+ensures allow_validator_set_change ==>
+    if (should_pass) { post_proposal.yes_votes == proposal.yes_votes + voting_power_0 } else { post_proposal.no_votes == proposal.no_votes + voting_power_0 };
+ensures !allow_validator_set_change ==>
+    if (should_pass) { post_proposal.yes_votes == proposal.yes_votes + voting_power_1 } else { post_proposal.no_votes == proposal.no_votes + voting_power_1 };
+aborts_if !string::spec_internal_check_utf8(voting::RESOLVABLE_TIME_METADATA_KEY);
+let key = utf8(voting::RESOLVABLE_TIME_METADATA_KEY);
+ensures simple_map::spec_contains_key(post_proposal.metadata, key);
+ensures simple_map::spec_get(post_proposal.metadata, key) == std::bcs::to_bytes(timestamp::now_seconds());
+aborts_if !exists<GovernanceEvents>(@aptos_framework);
+let early_resolution_threshold = option::spec_borrow(proposal.early_resolution_vote_threshold);
+let is_voting_period_over = timestamp::now_seconds() > proposal_expiration;
+let new_proposal_yes_votes_0 = proposal.yes_votes + voting_power_0;
+let can_be_resolved_early_0 = option::spec_is_some(proposal.early_resolution_vote_threshold) &&
+                            (new_proposal_yes_votes_0 >= early_resolution_threshold ||
+                             proposal.no_votes >= early_resolution_threshold);
+let is_voting_closed_0 = is_voting_period_over || can_be_resolved_early_0;
+let proposal_state_successed_0 = is_voting_closed_0 && new_proposal_yes_votes_0 > proposal.no_votes &&
+                                 new_proposal_yes_votes_0 + proposal.no_votes >= proposal.min_vote_threshold;
+let new_proposal_no_votes_0 = proposal.no_votes + voting_power_0;
+let can_be_resolved_early_1 = option::spec_is_some(proposal.early_resolution_vote_threshold) &&
+                            (proposal.yes_votes >= early_resolution_threshold ||
+                             new_proposal_no_votes_0 >= early_resolution_threshold);
+let is_voting_closed_1 = is_voting_period_over || can_be_resolved_early_1;
+let proposal_state_successed_1 = is_voting_closed_1 && proposal.yes_votes > new_proposal_no_votes_0 &&
+                                 proposal.yes_votes + new_proposal_no_votes_0 >= proposal.min_vote_threshold;
+let new_proposal_yes_votes_1 = proposal.yes_votes + voting_power_1;
+let can_be_resolved_early_2 = option::spec_is_some(proposal.early_resolution_vote_threshold) &&
+                            (new_proposal_yes_votes_1 >= early_resolution_threshold ||
+                             proposal.no_votes >= early_resolution_threshold);
+let is_voting_closed_2 = is_voting_period_over || can_be_resolved_early_2;
+let proposal_state_successed_2 = is_voting_closed_2 && new_proposal_yes_votes_1 > proposal.no_votes &&
+                                 new_proposal_yes_votes_1 + proposal.no_votes >= proposal.min_vote_threshold;
+let new_proposal_no_votes_1 = proposal.no_votes + voting_power_1;
+let can_be_resolved_early_3 = option::spec_is_some(proposal.early_resolution_vote_threshold) &&
+                            (proposal.yes_votes >= early_resolution_threshold ||
+                             new_proposal_no_votes_1 >= early_resolution_threshold);
+let is_voting_closed_3 = is_voting_period_over || can_be_resolved_early_3;
+let proposal_state_successed_3 = is_voting_closed_3 && proposal.yes_votes > new_proposal_no_votes_1 &&
+                                 proposal.yes_votes + new_proposal_no_votes_1 >= proposal.min_vote_threshold;
+let post can_be_resolved_early = option::spec_is_some(proposal.early_resolution_vote_threshold) &&
+                            (post_proposal.yes_votes >= early_resolution_threshold ||
+                             post_proposal.no_votes >= early_resolution_threshold);
+let post is_voting_closed = is_voting_period_over || can_be_resolved_early;
+let post proposal_state_successed = is_voting_closed && post_proposal.yes_votes > post_proposal.no_votes &&
+                                 post_proposal.yes_votes + post_proposal.no_votes >= proposal.min_vote_threshold;
+let execution_hash = proposal.execution_hash;
+let post post_approved_hashes = global<ApprovedExecutionHashes>(@aptos_framework);
+aborts_if allow_validator_set_change &&
+    if (should_pass) {
+        proposal_state_successed_0 && !exists<ApprovedExecutionHashes>(@aptos_framework)
+    } else {
+        proposal_state_successed_1 && !exists<ApprovedExecutionHashes>(@aptos_framework)
+    };
+aborts_if !allow_validator_set_change &&
+    if (should_pass) {
+        proposal_state_successed_2 && !exists<ApprovedExecutionHashes>(@aptos_framework)
+    } else {
+        proposal_state_successed_3 && !exists<ApprovedExecutionHashes>(@aptos_framework)
+    };
+ensures proposal_state_successed ==> simple_map::spec_contains_key(post_approved_hashes.hashes, proposal_id) &&
+                                     simple_map::spec_get(post_approved_hashes.hashes, proposal_id) == execution_hash;
 

 
 
@@ -1587,7 +1638,35 @@ Address @aptos_framework must exist VotingRecords and GovernanceProposal.
 
 
 
-
pragma verify = false;
+
requires chain_status::is_operating();
+include AddApprovedScriptHash;
+

+
+
+
+
+
+
+
+
schema AddApprovedScriptHash {
+    proposal_id: u64;
+    aborts_if !exists<ApprovedExecutionHashes>(@aptos_framework);
+    aborts_if !exists<voting::VotingForum<GovernanceProposal>>(@aptos_framework);
+    let voting_forum = global<voting::VotingForum<GovernanceProposal>>(@aptos_framework);
+    let proposal = table::spec_get(voting_forum.proposals, proposal_id);
+    aborts_if !table::spec_contains(voting_forum.proposals, proposal_id);
+    let early_resolution_threshold = option::spec_borrow(proposal.early_resolution_vote_threshold);
+    aborts_if timestamp::now_seconds() <= proposal.expiration_secs &&
+        (option::spec_is_none(proposal.early_resolution_vote_threshold) ||
+        proposal.yes_votes < early_resolution_threshold && proposal.no_votes < early_resolution_threshold);
+    aborts_if (timestamp::now_seconds() > proposal.expiration_secs ||
+        option::spec_is_some(proposal.early_resolution_vote_threshold) && (proposal.yes_votes >= early_resolution_threshold ||
+                                                                           proposal.no_votes >= early_resolution_threshold)) &&
+        (proposal.yes_votes <= proposal.no_votes || proposal.yes_votes + proposal.no_votes < proposal.min_vote_threshold);
+    let post post_approved_hashes = global<ApprovedExecutionHashes>(@aptos_framework);
+    ensures simple_map::spec_contains_key(post_approved_hashes.hashes, proposal_id) &&
+        simple_map::spec_get(post_approved_hashes.hashes, proposal_id) == proposal.execution_hash;
+}
 

 
 
@@ -1603,9 +1682,8 @@ Address @aptos_framework must exist VotingRecords and GovernanceProposal.
 
 
 
-
pragma aborts_if_is_partial;
-requires chain_status::is_operating();
-aborts_if !exists<ApprovedExecutionHashes>(@aptos_framework);
+
requires chain_status::is_operating();
+include AddApprovedScriptHash;
 

 
 
@@ -1622,11 +1700,28 @@ Address @aptos_framework must exist VotingRecords and GovernanceProposal.
 Address @aptos_framework must exist ApprovedExecutionHashes and GovernanceProposal and GovernanceResponsbility.
 
 
-
pragma aborts_if_is_partial;
-requires chain_status::is_operating();
-aborts_if !exists<voting::VotingForum<GovernanceProposal>>(@aptos_framework);
+
requires chain_status::is_operating();
+include VotingIsProposalResolvableAbortsif;
+let voting_forum = global<voting::VotingForum<GovernanceProposal>>(@aptos_framework);
+let proposal = table::spec_get(voting_forum.proposals, proposal_id);
+let multi_step_key = utf8(voting::IS_MULTI_STEP_PROPOSAL_KEY);
+let has_multi_step_key = simple_map::spec_contains_key(proposal.metadata, multi_step_key);
+let is_multi_step_proposal = aptos_std::from_bcs::deserialize<bool>(simple_map::spec_get(proposal.metadata, multi_step_key));
+aborts_if has_multi_step_key && !aptos_std::from_bcs::deserializable<bool>(simple_map::spec_get(proposal.metadata, multi_step_key));
+aborts_if !string::spec_internal_check_utf8(voting::IS_MULTI_STEP_PROPOSAL_KEY);
+aborts_if has_multi_step_key && is_multi_step_proposal;
+let post post_voting_forum = global<voting::VotingForum<GovernanceProposal>>(@aptos_framework);
+let post post_proposal = table::spec_get(post_voting_forum.proposals, proposal_id);
+ensures post_proposal.is_resolved == true && post_proposal.resolution_time_secs == timestamp::now_seconds();
+aborts_if option::spec_is_none(proposal.execution_content);
 aborts_if !exists<ApprovedExecutionHashes>(@aptos_framework);
+let post post_approved_hashes = global<ApprovedExecutionHashes>(@aptos_framework).hashes;
+ensures !simple_map::spec_contains_key(post_approved_hashes, proposal_id);
 include GetSignerAbortsIf;
+let governance_responsibility = global<GovernanceResponsbility>(@aptos_framework);
+let signer_cap = simple_map::spec_get(governance_responsibility.signer_caps, signer_address);
+let addr = signer_cap.account;
+ensures signer::address_of(result) == addr;
 

 
 
@@ -1642,16 +1737,76 @@ Address @aptos_framework must exist ApprovedExecutionHashes and GovernancePropos
 
 
 
-
pragma aborts_if_is_partial;
-let voting_forum = borrow_global<voting::VotingForum<GovernanceProposal>>(@aptos_framework);
+
requires chain_status::is_operating();
+include VotingIsProposalResolvableAbortsif;
+let voting_forum = global<voting::VotingForum<GovernanceProposal>>(@aptos_framework);
 let proposal = table::spec_get(voting_forum.proposals, proposal_id);
-requires chain_status::is_operating();
-aborts_if !exists<voting::VotingForum<GovernanceProposal>>(@aptos_framework);
-aborts_if !exists<ApprovedExecutionHashes>(@aptos_framework);
-aborts_if !table::spec_contains(voting_forum.proposals,proposal_id);
-aborts_if !string::spec_internal_check_utf8(b"IS_MULTI_STEP_PROPOSAL_IN_EXECUTION");
-aborts_if aptos_framework::transaction_context::spec_get_script_hash() != proposal.execution_hash;
+let post post_voting_forum = global<voting::VotingForum<GovernanceProposal>>(@aptos_framework);
+let post post_proposal = table::spec_get(post_voting_forum.proposals, proposal_id);
+aborts_if !string::spec_internal_check_utf8(voting::IS_MULTI_STEP_PROPOSAL_IN_EXECUTION_KEY);
+let multi_step_in_execution_key = utf8(voting::IS_MULTI_STEP_PROPOSAL_IN_EXECUTION_KEY);
+let post is_multi_step_proposal_in_execution_value = simple_map::spec_get(post_proposal.metadata, multi_step_in_execution_key);
+ensures simple_map::spec_contains_key(proposal.metadata, multi_step_in_execution_key) ==>
+    is_multi_step_proposal_in_execution_value == std::bcs::serialize(true);
+aborts_if !string::spec_internal_check_utf8(voting::IS_MULTI_STEP_PROPOSAL_KEY);
+let multi_step_key = utf8(voting::IS_MULTI_STEP_PROPOSAL_KEY);
+aborts_if simple_map::spec_contains_key(proposal.metadata, multi_step_key) &&
+                    aptos_std::from_bcs::deserializable<bool>(simple_map::spec_get(proposal.metadata, multi_step_key));
+let is_multi_step = simple_map::spec_contains_key(proposal.metadata, multi_step_key) &&
+                    aptos_std::from_bcs::deserialize<bool>(simple_map::spec_get(proposal.metadata, multi_step_key));
+let next_execution_hash_is_empty = len(next_execution_hash) == 0;
+aborts_if !is_multi_step && !next_execution_hash_is_empty;
+aborts_if next_execution_hash_is_empty && is_multi_step && !simple_map::spec_contains_key(proposal.metadata, multi_step_in_execution_key);
+ensures next_execution_hash_is_empty ==> post_proposal.is_resolved == true && post_proposal.resolution_time_secs == timestamp::spec_now_seconds() &&
+    if (is_multi_step) {
+        is_multi_step_proposal_in_execution_value == std::bcs::serialize(false)
+    } else {
+        simple_map::spec_contains_key(proposal.metadata, multi_step_in_execution_key) ==>
+            is_multi_step_proposal_in_execution_value == std::bcs::serialize(true)
+    };
+ensures !next_execution_hash_is_empty ==> post_proposal.execution_hash == next_execution_hash &&
+    simple_map::spec_contains_key(proposal.metadata, multi_step_in_execution_key) ==>
+        is_multi_step_proposal_in_execution_value == std::bcs::serialize(true);
+aborts_if next_execution_hash_is_empty && !exists<ApprovedExecutionHashes>(@aptos_framework);
+let post post_approved_hashes = global<ApprovedExecutionHashes>(@aptos_framework).hashes;
+ensures next_execution_hash_is_empty ==> !simple_map::spec_contains_key(post_approved_hashes, proposal_id);
+ensures !next_execution_hash_is_empty ==>
+    simple_map::spec_get(post_approved_hashes, proposal_id) == next_execution_hash;
 include GetSignerAbortsIf;
+let governance_responsibility = global<GovernanceResponsbility>(@aptos_framework);
+let signer_cap = simple_map::spec_get(governance_responsibility.signer_caps, signer_address);
+let addr = signer_cap.account;
+ensures signer::address_of(result) == addr;
+

+
+
+
+
+
+
+
+
schema VotingIsProposalResolvableAbortsif {
+    proposal_id: u64;
+    aborts_if !exists<voting::VotingForum<GovernanceProposal>>(@aptos_framework);
+    let voting_forum = global<voting::VotingForum<GovernanceProposal>>(@aptos_framework);
+    let proposal = table::spec_get(voting_forum.proposals, proposal_id);
+    aborts_if !table::spec_contains(voting_forum.proposals, proposal_id);
+    let early_resolution_threshold = option::spec_borrow(proposal.early_resolution_vote_threshold);
+    let voting_period_over = timestamp::now_seconds() > proposal.expiration_secs;
+    let be_resolved_early = option::spec_is_some(proposal.early_resolution_vote_threshold) &&
+                                (proposal.yes_votes >= early_resolution_threshold ||
+                                 proposal.no_votes >= early_resolution_threshold);
+    let voting_closed = voting_period_over || be_resolved_early;
+    aborts_if voting_closed && (proposal.yes_votes <= proposal.no_votes || proposal.yes_votes + proposal.no_votes < proposal.min_vote_threshold);
+    aborts_if !voting_closed;
+    aborts_if proposal.is_resolved;
+    aborts_if !string::spec_internal_check_utf8(voting::RESOLVABLE_TIME_METADATA_KEY);
+    aborts_if !simple_map::spec_contains_key(proposal.metadata, utf8(voting::RESOLVABLE_TIME_METADATA_KEY));
+    let resolvable_time = aptos_std::from_bcs::deserialize<u64>(simple_map::spec_get(proposal.metadata, utf8(voting::RESOLVABLE_TIME_METADATA_KEY)));
+    aborts_if !aptos_std::from_bcs::deserializable<u64>(simple_map::spec_get(proposal.metadata, utf8(voting::RESOLVABLE_TIME_METADATA_KEY)));
+    aborts_if timestamp::now_seconds() <= resolvable_time;
+    aborts_if aptos_framework::transaction_context::spec_get_script_hash() != proposal.execution_hash;
+}
 

 
 
@@ -1690,14 +1845,13 @@ Address @aptos_framework must exist ApprovedExecutionHashes and GovernancePropos
 
 
 
-
pragma verify_duration_estimate = 120;
-aborts_if !system_addresses::is_aptos_framework_address(signer::address_of(aptos_framework));
+
aborts_if !system_addresses::is_aptos_framework_address(signer::address_of(aptos_framework));
 include transaction_fee::RequiresCollectedFeesPerValueLeqBlockAptosSupply;
-include staking_config::StakingRewardsConfigRequirement;
 requires chain_status::is_operating();
-requires timestamp::spec_now_microseconds() >= reconfiguration::last_reconfiguration_time();
 requires exists<stake::ValidatorFees>(@aptos_framework);
 requires exists<CoinInfo<AptosCoin>>(@aptos_framework);
+requires exists<staking_config::StakingRewardsConfig>(@aptos_framework);
+include staking_config::StakingRewardsConfigRequirement;
 

 
 
@@ -1737,15 +1891,35 @@ limit addition overflow.
 pool_address must exist in StakePool.
 
 
-
pragma aborts_if_is_partial;
+
include GetVotingPowerAbortsIf;
 let staking_config = global<staking_config::StakingConfig>(@aptos_framework);
-aborts_if !exists<staking_config::StakingConfig>(@aptos_framework);
 let allow_validator_set_change = staking_config.allow_validator_set_change;
-let stake_pool = global<stake::StakePool>(pool_address);
-aborts_if allow_validator_set_change && (stake_pool.active.value + stake_pool.pending_active.value + stake_pool.pending_inactive.value) > MAX_U64;
-aborts_if !exists<stake::StakePool>(pool_address);
-aborts_if !allow_validator_set_change && !exists<stake::ValidatorSet>(@aptos_framework);
-ensures allow_validator_set_change ==> result == stake_pool.active.value + stake_pool.pending_active.value + stake_pool.pending_inactive.value;
+let stake_pool_res = global<stake::StakePool>(pool_address);
+ensures allow_validator_set_change ==> result == stake_pool_res.active.value + stake_pool_res.pending_active.value + stake_pool_res.pending_inactive.value;
+ensures !allow_validator_set_change ==> if (stake::spec_is_current_epoch_validator(pool_address)) {
+    result == stake_pool_res.active.value + stake_pool_res.pending_inactive.value
+} else {
+    result == 0
+};
+

+
+
+
+
+
+
+
+
schema GetVotingPowerAbortsIf {
+    pool_address: address;
+    let staking_config = global<staking_config::StakingConfig>(@aptos_framework);
+    aborts_if !exists<staking_config::StakingConfig>(@aptos_framework);
+    let allow_validator_set_change = staking_config.allow_validator_set_change;
+    let stake_pool_res = global<stake::StakePool>(pool_address);
+    aborts_if allow_validator_set_change && (stake_pool_res.active.value + stake_pool_res.pending_active.value + stake_pool_res.pending_inactive.value) > MAX_U64;
+    aborts_if !exists<stake::StakePool>(pool_address);
+    aborts_if !allow_validator_set_change && !exists<stake::ValidatorSet>(@aptos_framework);
+    aborts_if !allow_validator_set_change && stake::spec_is_current_epoch_validator(pool_address) && stake_pool_res.active.value + stake_pool_res.pending_inactive.value > MAX_U64;
+}
 

 
 
@@ -1791,12 +1965,25 @@ pool_address must exist in StakePool.
 
 
 
-
aborts_if string::length(utf8(metadata_location)) > 256;
-aborts_if string::length(utf8(metadata_hash)) > 256;
-aborts_if !string::spec_internal_check_utf8(metadata_location);
-aborts_if !string::spec_internal_check_utf8(metadata_hash);
-aborts_if !string::spec_internal_check_utf8(METADATA_LOCATION_KEY);
-aborts_if !string::spec_internal_check_utf8(METADATA_HASH_KEY);
+
include CreateProposalMetadataAbortsIf;
+

+
+
+
+
+
+
+
+
schema CreateProposalMetadataAbortsIf {
+    metadata_location: vector<u8>;
+    metadata_hash: vector<u8>;
+    aborts_if string::length(utf8(metadata_location)) > 256;
+    aborts_if string::length(utf8(metadata_hash)) > 256;
+    aborts_if !string::spec_internal_check_utf8(metadata_location);
+    aborts_if !string::spec_internal_check_utf8(metadata_hash);
+    aborts_if !string::spec_internal_check_utf8(METADATA_LOCATION_KEY);
+    aborts_if !string::spec_internal_check_utf8(METADATA_HASH_KEY);
+}
 

 
 
diff --git a/aptos-move/framework/aptos-framework/sources/aptos_governance.spec.move b/aptos-move/framework/aptos-framework/sources/aptos_governance.spec.move
index a29c978406cf1..682a6df16ca12 100644
--- a/aptos-move/framework/aptos-framework/sources/aptos_governance.spec.move
+++ b/aptos-move/framework/aptos-framework/sources/aptos_governance.spec.move
@@ -112,8 +112,7 @@ spec aptos_framework::aptos_governance {
         metadata_hash: vector,
     ) {
         use aptos_framework::chain_status;
-        // TODO: Calls `create_proposal_v2`.
-        pragma aborts_if_is_partial;
+
         requires chain_status::is_operating();
         include CreateProposalAbortsIf;
     }
@@ -127,11 +126,7 @@ spec aptos_framework::aptos_governance {
         is_multi_step_proposal: bool,
     ) {
         use aptos_framework::chain_status;
-        // TODO: The variable `stake_balance` is the return value of the function `get_voting_power`.
-        // `get_voting_power` has already stated that it cannot be fully verified,
-        // so the value of `stake_balance` cannot be obtained in the spec,
-        // and the `aborts_if` of `stake_balancede` cannot be written.
-        pragma aborts_if_is_partial;
+
         requires chain_status::is_operating();
         include CreateProposalAbortsIf;
     }
@@ -148,19 +143,65 @@ spec aptos_framework::aptos_governance {
         metadata_location: vector;
         metadata_hash: vector;
 
-        let proposer_address = signer::address_of(proposer);
-        let governance_config = global(@aptos_framework);
-        let stake_pool_res = global(stake_pool);
-        aborts_if !exists(@aptos_framework);
-        aborts_if !exists(stake_pool);
-        aborts_if global(stake_pool).delegated_voter != proposer_address;
+        include VotingGetDelegatedVoterAbortsIf { sign: proposer };
         include AbortsIfNotGovernanceConfig;
-        let current_time = timestamp::now_seconds();
+
+        // verify get_voting_power(stake_pool)
+        include GetVotingPowerAbortsIf { pool_address: stake_pool };
+        let staking_config = global(@aptos_framework);
+        let allow_validator_set_change = staking_config.allow_validator_set_change;
+        let stake_pool_res = global(stake_pool);
+        // Three results of get_voting_power(stake_pool)
+        let stake_balance_0 = stake_pool_res.active.value + stake_pool_res.pending_active.value + stake_pool_res.pending_inactive.value;
+        let stake_balance_1 = stake_pool_res.active.value + stake_pool_res.pending_inactive.value;
+        let stake_balance_2 = 0;
+        let governance_config = global(@aptos_framework);
+        let required_proposer_stake = governance_config.required_proposer_stake;
+        // Comparison of the three results of get_voting_power(stake_pool) and required_proposer_stake
+        aborts_if allow_validator_set_change && stake_balance_0 < required_proposer_stake;
+        aborts_if !allow_validator_set_change && stake::spec_is_current_epoch_validator(stake_pool) && stake_balance_1 < required_proposer_stake;
+        aborts_if !allow_validator_set_change && !stake::spec_is_current_epoch_validator(stake_pool) && stake_balance_2 < required_proposer_stake;
+
+        aborts_if !exists(@aptos_framework);
+        let current_time = timestamp::spec_now_seconds();
         let proposal_expiration = current_time + governance_config.voting_duration_secs;
         aborts_if stake_pool_res.locked_until_secs < proposal_expiration;
+
+        // verify create_proposal_metadata
+        include CreateProposalMetadataAbortsIf;
+
+        let addr = aptos_std::type_info::type_of().account_address;
+        aborts_if !exists>(addr);
+        let maybe_supply = global>(addr).supply;
+        let supply = option::spec_borrow(maybe_supply);
+        let total_supply = aptos_framework::optional_aggregator::optional_aggregator_value(supply);
+        let early_resolution_vote_threshold_value = total_supply / 2 + 1;
+
+        // verify voting::create_proposal_v2
+        aborts_if option::spec_is_some(maybe_supply) && governance_config.min_voting_threshold > early_resolution_vote_threshold_value;
+        aborts_if len(execution_hash) <= 0;
+        aborts_if !exists>(@aptos_framework);
+        let voting_forum = global>(@aptos_framework);
+        let proposal_id = voting_forum.next_proposal_id;
+        aborts_if proposal_id + 1 > MAX_U64;
+        let post post_voting_forum = global>(@aptos_framework);
+        let post post_next_proposal_id = post_voting_forum.next_proposal_id;
+        ensures post_next_proposal_id == proposal_id + 1;
+        aborts_if !string::spec_internal_check_utf8(voting::IS_MULTI_STEP_PROPOSAL_KEY);
+        aborts_if !string::spec_internal_check_utf8(voting::IS_MULTI_STEP_PROPOSAL_IN_EXECUTION_KEY);
+        aborts_if table::spec_contains(voting_forum.proposals,proposal_id);
+        ensures table::spec_contains(post_voting_forum.proposals, proposal_id);
         aborts_if !exists(@aptos_framework);
-        let allow_validator_set_change = global(@aptos_framework).allow_validator_set_change;
-        aborts_if !allow_validator_set_change && !exists(@aptos_framework);
+    }
+
+    spec schema VotingGetDelegatedVoterAbortsIf {
+        stake_pool: address;
+        sign: signer;
+
+        let addr = signer::address_of(sign);
+        let stake_pool_res = global(stake_pool);
+        aborts_if !exists(stake_pool);
+        aborts_if stake_pool_res.delegated_voter != addr;
     }
 
     /// stake_pool must exist StakePool.
@@ -175,61 +216,202 @@ spec aptos_framework::aptos_governance {
         use aptos_framework::stake;
         use aptos_framework::chain_status;
 
-        // TODO: The variable `voting_power` is the return value of the function `get_voting_power`.
-        // `get_voting_power` has already stated that it cannot be completely verified,
-        // so the value of `voting_power` cannot be obtained in the spec,
-        // and the `aborts_if` of `voting_power` cannot be written.
-        pragma aborts_if_is_partial;
-
         requires chain_status::is_operating();
 
-        let voter_address = signer::address_of(voter);
-        let stake_pool_res = global(stake_pool);
-        aborts_if !exists(stake_pool);
-        aborts_if stake_pool_res.delegated_voter != voter_address;
+        include VotingGetDelegatedVoterAbortsIf { sign: voter };
+
         aborts_if !exists(@aptos_framework);
-        aborts_if !exists>(@aptos_framework);
+        let voting_records = global(@aptos_framework);
+        let record_key = RecordKey {
+            stake_pool,
+            proposal_id,
+        };
+        let post post_voting_records = global(@aptos_framework);
+        aborts_if table::spec_contains(voting_records.votes, record_key);
+        ensures table::spec_get(post_voting_records.votes, record_key) == true;
+
+        // verify get_voting_power(stake_pool)
+        include GetVotingPowerAbortsIf { pool_address: stake_pool };
         let allow_validator_set_change = global(@aptos_framework).allow_validator_set_change;
-        aborts_if !allow_validator_set_change && !exists(@aptos_framework);
+        let stake_pool_res = global(stake_pool);
+        // Two results of get_voting_power(stake_pool) and the third one is zero.
+        let voting_power_0 = stake_pool_res.active.value + stake_pool_res.pending_active.value + stake_pool_res.pending_inactive.value;
+        let voting_power_1 = stake_pool_res.active.value + stake_pool_res.pending_inactive.value;
+        // Each result is compared with zero, and the following three aborts_if statements represent each of the three results.
+        aborts_if allow_validator_set_change && voting_power_0 <= 0;
+        aborts_if !allow_validator_set_change && stake::spec_is_current_epoch_validator(stake_pool) && voting_power_1 <= 0;
+        aborts_if !allow_validator_set_change && !stake::spec_is_current_epoch_validator(stake_pool);
+
+        aborts_if !exists>(@aptos_framework);
         let voting_forum = global>(@aptos_framework);
         let proposal = table::spec_get(voting_forum.proposals, proposal_id);
+        aborts_if !table::spec_contains(voting_forum.proposals, proposal_id);
         let proposal_expiration = proposal.expiration_secs;
         let locked_until_secs = global(stake_pool).locked_until_secs;
         aborts_if proposal_expiration > locked_until_secs;
+
+        // verify voting::vote
+        aborts_if timestamp::now_seconds() > proposal_expiration;
+        aborts_if proposal.is_resolved;
+        aborts_if !string::spec_internal_check_utf8(voting::IS_MULTI_STEP_PROPOSAL_IN_EXECUTION_KEY);
+        let execution_key = utf8(voting::IS_MULTI_STEP_PROPOSAL_IN_EXECUTION_KEY);
+        aborts_if simple_map::spec_contains_key(proposal.metadata, execution_key) &&
+                  simple_map::spec_get(proposal.metadata, execution_key) != std::bcs::to_bytes(false);
+        // Since there are two possibilities for voting_power, the result of the vote is not only related to should_pass,
+        // but also to allow_validator_set_change which determines the voting_power
+        aborts_if allow_validator_set_change &&
+            if (should_pass) { proposal.yes_votes + voting_power_0 > MAX_U128 } else { proposal.no_votes + voting_power_0 > MAX_U128 };
+        aborts_if !allow_validator_set_change &&
+            if (should_pass) { proposal.yes_votes + voting_power_1 > MAX_U128 } else { proposal.no_votes + voting_power_1 > MAX_U128 };
+        let post post_voting_forum = global>(@aptos_framework);
+        let post post_proposal = table::spec_get(post_voting_forum.proposals, proposal_id);
+        ensures allow_validator_set_change ==>
+            if (should_pass) { post_proposal.yes_votes == proposal.yes_votes + voting_power_0 } else { post_proposal.no_votes == proposal.no_votes + voting_power_0 };
+        ensures !allow_validator_set_change ==>
+            if (should_pass) { post_proposal.yes_votes == proposal.yes_votes + voting_power_1 } else { post_proposal.no_votes == proposal.no_votes + voting_power_1 };
+        aborts_if !string::spec_internal_check_utf8(voting::RESOLVABLE_TIME_METADATA_KEY);
+        let key = utf8(voting::RESOLVABLE_TIME_METADATA_KEY);
+        ensures simple_map::spec_contains_key(post_proposal.metadata, key);
+        ensures simple_map::spec_get(post_proposal.metadata, key) == std::bcs::to_bytes(timestamp::now_seconds());
+
+        aborts_if !exists(@aptos_framework);
+
+        // verify voting::get_proposal_state
+        let early_resolution_threshold = option::spec_borrow(proposal.early_resolution_vote_threshold);
+        let is_voting_period_over = timestamp::now_seconds() > proposal_expiration;
+        // The success state depends on the number of votes, but since the number of votes is related to allow_validator_set_change and should_pass,
+        // we describe the success state in different cases.
+        // allow_validator_set_change && should_pass
+        let new_proposal_yes_votes_0 = proposal.yes_votes + voting_power_0;
+        let can_be_resolved_early_0 = option::spec_is_some(proposal.early_resolution_vote_threshold) &&
+                                    (new_proposal_yes_votes_0 >= early_resolution_threshold ||
+                                     proposal.no_votes >= early_resolution_threshold);
+        let is_voting_closed_0 = is_voting_period_over || can_be_resolved_early_0;
+        let proposal_state_successed_0 = is_voting_closed_0 && new_proposal_yes_votes_0 > proposal.no_votes &&
+                                         new_proposal_yes_votes_0 + proposal.no_votes >= proposal.min_vote_threshold;
+        // allow_validator_set_change && !should_pass
+        let new_proposal_no_votes_0 = proposal.no_votes + voting_power_0;
+        let can_be_resolved_early_1 = option::spec_is_some(proposal.early_resolution_vote_threshold) &&
+                                    (proposal.yes_votes >= early_resolution_threshold ||
+                                     new_proposal_no_votes_0 >= early_resolution_threshold);
+        let is_voting_closed_1 = is_voting_period_over || can_be_resolved_early_1;
+        let proposal_state_successed_1 = is_voting_closed_1 && proposal.yes_votes > new_proposal_no_votes_0 &&
+                                         proposal.yes_votes + new_proposal_no_votes_0 >= proposal.min_vote_threshold;
+        // !allow_validator_set_change && should_pass
+        let new_proposal_yes_votes_1 = proposal.yes_votes + voting_power_1;
+        let can_be_resolved_early_2 = option::spec_is_some(proposal.early_resolution_vote_threshold) &&
+                                    (new_proposal_yes_votes_1 >= early_resolution_threshold ||
+                                     proposal.no_votes >= early_resolution_threshold);
+        let is_voting_closed_2 = is_voting_period_over || can_be_resolved_early_2;
+        let proposal_state_successed_2 = is_voting_closed_2 && new_proposal_yes_votes_1 > proposal.no_votes &&
+                                         new_proposal_yes_votes_1 + proposal.no_votes >= proposal.min_vote_threshold;
+        // !allow_validator_set_change && !should_pass
+        let new_proposal_no_votes_1 = proposal.no_votes + voting_power_1;
+        let can_be_resolved_early_3 = option::spec_is_some(proposal.early_resolution_vote_threshold) &&
+                                    (proposal.yes_votes >= early_resolution_threshold ||
+                                     new_proposal_no_votes_1 >= early_resolution_threshold);
+        let is_voting_closed_3 = is_voting_period_over || can_be_resolved_early_3;
+        let proposal_state_successed_3 = is_voting_closed_3 && proposal.yes_votes > new_proposal_no_votes_1 &&
+                                         proposal.yes_votes + new_proposal_no_votes_1 >= proposal.min_vote_threshold;
+        // post state
+        let post can_be_resolved_early = option::spec_is_some(proposal.early_resolution_vote_threshold) &&
+                                    (post_proposal.yes_votes >= early_resolution_threshold ||
+                                     post_proposal.no_votes >= early_resolution_threshold);
+        let post is_voting_closed = is_voting_period_over || can_be_resolved_early;
+        let post proposal_state_successed = is_voting_closed && post_proposal.yes_votes > post_proposal.no_votes &&
+                                         post_proposal.yes_votes + post_proposal.no_votes >= proposal.min_vote_threshold;
+        // verify add_approved_script_hash(proposal_id)
+        let execution_hash = proposal.execution_hash;
+        let post post_approved_hashes = global(@aptos_framework);
+
+        // Due to the complexity of the success state, the validation of 'borrow_global_mut(@aptos_framework);' is discussed in four cases.
+        aborts_if allow_validator_set_change &&
+            if (should_pass) {
+                proposal_state_successed_0 && !exists(@aptos_framework)
+            } else {
+                proposal_state_successed_1 && !exists(@aptos_framework)
+            };
+        aborts_if !allow_validator_set_change &&
+            if (should_pass) {
+                proposal_state_successed_2 && !exists(@aptos_framework)
+            } else {
+                proposal_state_successed_3 && !exists(@aptos_framework)
+            };
+        ensures proposal_state_successed ==> simple_map::spec_contains_key(post_approved_hashes.hashes, proposal_id) &&
+                                             simple_map::spec_get(post_approved_hashes.hashes, proposal_id) == execution_hash;
     }
 
     spec add_approved_script_hash(proposal_id: u64) {
         use aptos_framework::chain_status;
-        // TODO: The variable `proposal_state` is the return value of the function `voting::get_proposal_state`.
-        // The calling level of `voting::get_proposal_state` is very deep,
-        // so the value of `proposal_state` cannot be obtained in the spec,
-        // and the `aborts_if` of `proposal_state` cannot be written.
-        // Can't cover all aborts_if conditions
-        pragma aborts_if_is_partial;
 
         requires chain_status::is_operating();
-        aborts_if !exists(@aptos_framework);
+        include AddApprovedScriptHash;
     }
 
     spec add_approved_script_hash_script(proposal_id: u64) {
-        // TODO: Calls `add_approved_script_hash`.
-        // Can't cover all aborts_if conditions
-        pragma verify = false;
+        use aptos_framework::chain_status;
+
+        requires chain_status::is_operating();
+        include AddApprovedScriptHash;
+    }
+
+    spec schema AddApprovedScriptHash {
+        proposal_id: u64;
+        aborts_if !exists(@aptos_framework);
+
+        aborts_if !exists>(@aptos_framework);
+        let voting_forum = global>(@aptos_framework);
+        let proposal = table::spec_get(voting_forum.proposals, proposal_id);
+        aborts_if !table::spec_contains(voting_forum.proposals, proposal_id);
+        let early_resolution_threshold = option::spec_borrow(proposal.early_resolution_vote_threshold);
+        aborts_if timestamp::now_seconds() <= proposal.expiration_secs &&
+            (option::spec_is_none(proposal.early_resolution_vote_threshold) ||
+            proposal.yes_votes < early_resolution_threshold && proposal.no_votes < early_resolution_threshold);
+        aborts_if (timestamp::now_seconds() > proposal.expiration_secs ||
+            option::spec_is_some(proposal.early_resolution_vote_threshold) && (proposal.yes_votes >= early_resolution_threshold ||
+                                                                               proposal.no_votes >= early_resolution_threshold)) &&
+            (proposal.yes_votes <= proposal.no_votes || proposal.yes_votes + proposal.no_votes < proposal.min_vote_threshold);
+
+        let post post_approved_hashes = global(@aptos_framework);
+        ensures simple_map::spec_contains_key(post_approved_hashes.hashes, proposal_id) &&
+            simple_map::spec_get(post_approved_hashes.hashes, proposal_id) == proposal.execution_hash;
     }
 
     /// Address @aptos_framework must exist ApprovedExecutionHashes and GovernanceProposal and GovernanceResponsbility.
     spec resolve(proposal_id: u64, signer_address: address): signer {
         use aptos_framework::chain_status;
-        // TODO: Executing the prove command gives an error that the target file is in `from_bcs::from_bytes`,
-        // and the call level of the function `resolve` is too deep to obtain the parameter `bytes` of spec `from_bytes`,
-        // so verification cannot be performed.
-        // Can't cover all aborts_if conditions
-        pragma aborts_if_is_partial;
 
         requires chain_status::is_operating();
-        aborts_if !exists>(@aptos_framework);
+
+        // verify voting::resolve
+        include VotingIsProposalResolvableAbortsif;
+
+        let voting_forum = global>(@aptos_framework);
+        let proposal = table::spec_get(voting_forum.proposals, proposal_id);
+
+        let multi_step_key = utf8(voting::IS_MULTI_STEP_PROPOSAL_KEY);
+        let has_multi_step_key = simple_map::spec_contains_key(proposal.metadata, multi_step_key);
+        let is_multi_step_proposal = aptos_std::from_bcs::deserialize(simple_map::spec_get(proposal.metadata, multi_step_key));
+        aborts_if has_multi_step_key && !aptos_std::from_bcs::deserializable(simple_map::spec_get(proposal.metadata, multi_step_key));
+        aborts_if !string::spec_internal_check_utf8(voting::IS_MULTI_STEP_PROPOSAL_KEY);
+        aborts_if has_multi_step_key && is_multi_step_proposal;
+
+        let post post_voting_forum = global>(@aptos_framework);
+        let post post_proposal = table::spec_get(post_voting_forum.proposals, proposal_id);
+        ensures post_proposal.is_resolved == true && post_proposal.resolution_time_secs == timestamp::now_seconds();
+        aborts_if option::spec_is_none(proposal.execution_content);
+
+        // verify remove_approved_hash
         aborts_if !exists(@aptos_framework);
+        let post post_approved_hashes = global(@aptos_framework).hashes;
+        ensures !simple_map::spec_contains_key(post_approved_hashes, proposal_id);
+
+        // verify get_signer
         include GetSignerAbortsIf;
+        let governance_responsibility = global(@aptos_framework);
+        let signer_cap = simple_map::spec_get(governance_responsibility.signer_caps, signer_address);
+        let addr = signer_cap.account;
+        ensures signer::address_of(result) == addr;
     }
 
     /// Address @aptos_framework must exist ApprovedExecutionHashes and GovernanceProposal.
@@ -248,18 +430,15 @@ spec aptos_framework::aptos_governance {
         use aptos_framework::coin::CoinInfo;
         use aptos_framework::aptos_coin::AptosCoin;
         use aptos_framework::transaction_fee;
-        use aptos_framework::staking_config;
-
-        pragma verify_duration_estimate = 120; // TODO: set because of timeout (property proved)
 
         aborts_if !system_addresses::is_aptos_framework_address(signer::address_of(aptos_framework));
 
         include transaction_fee::RequiresCollectedFeesPerValueLeqBlockAptosSupply;
-        include staking_config::StakingRewardsConfigRequirement;
         requires chain_status::is_operating();
-        requires timestamp::spec_now_microseconds() >= reconfiguration::last_reconfiguration_time();
         requires exists(@aptos_framework);
         requires exists>(@aptos_framework);
+        requires exists(@aptos_framework);
+        include staking_config::StakingRewardsConfigRequirement;
     }
 
     /// Signer address must be @core_resources.
@@ -275,21 +454,31 @@ spec aptos_framework::aptos_governance {
     /// limit addition overflow.
     /// pool_address must exist in StakePool.
     spec get_voting_power(pool_address: address): u64 {
-        // TODO: `stake::get_current_epoch_voting_power` is called in the function,
-        // the call level is very deep, and `stake::get_stake` has multiple return values,
-        // and multiple return values cannot be obtained in the spec,
-        // so the overflow aborts_if of active + pending_active + pending_inactive cannot be written.
-        pragma aborts_if_is_partial;
+        include GetVotingPowerAbortsIf;
+
+        let staking_config = global(@aptos_framework);
+        let allow_validator_set_change = staking_config.allow_validator_set_change;
+        let stake_pool_res = global(pool_address);
+
+        ensures allow_validator_set_change ==> result == stake_pool_res.active.value + stake_pool_res.pending_active.value + stake_pool_res.pending_inactive.value;
+        ensures !allow_validator_set_change ==> if (stake::spec_is_current_epoch_validator(pool_address)) {
+            result == stake_pool_res.active.value + stake_pool_res.pending_inactive.value
+        } else {
+            result == 0
+        };
+    }
+
+    spec schema     GetVotingPowerAbortsIf {
+        pool_address: address;
 
         let staking_config = global(@aptos_framework);
         aborts_if !exists(@aptos_framework);
         let allow_validator_set_change = staking_config.allow_validator_set_change;
-        let stake_pool = global(pool_address);
-        aborts_if allow_validator_set_change && (stake_pool.active.value + stake_pool.pending_active.value + stake_pool.pending_inactive.value) > MAX_U64;
+        let stake_pool_res = global(pool_address);
+        aborts_if allow_validator_set_change && (stake_pool_res.active.value + stake_pool_res.pending_active.value + stake_pool_res.pending_inactive.value) > MAX_U64;
         aborts_if !exists(pool_address);
         aborts_if !allow_validator_set_change && !exists(@aptos_framework);
-
-        ensures allow_validator_set_change ==> result == stake_pool.active.value + stake_pool.pending_active.value + stake_pool.pending_inactive.value;
+        aborts_if !allow_validator_set_change && stake::spec_is_current_epoch_validator(pool_address) && stake_pool_res.active.value + stake_pool_res.pending_inactive.value > MAX_U64;
     }
 
     spec get_signer(signer_address: address): signer {
@@ -305,6 +494,13 @@ spec aptos_framework::aptos_governance {
     }
 
     spec create_proposal_metadata(metadata_location: vector, metadata_hash: vector): SimpleMap> {
+        include CreateProposalMetadataAbortsIf;
+    }
+
+    spec schema CreateProposalMetadataAbortsIf {
+        metadata_location: vector;
+        metadata_hash: vector;
+
         aborts_if string::length(utf8(metadata_location)) > 256;
         aborts_if string::length(utf8(metadata_hash)) > 256;
         aborts_if !string::spec_internal_check_utf8(metadata_location);
@@ -325,20 +521,81 @@ spec aptos_framework::aptos_governance {
 
     spec resolve_multi_step_proposal(proposal_id: u64, signer_address: address, next_execution_hash: vector): signer {
         use aptos_framework::chain_status;
+        requires chain_status::is_operating();
 
-        // TODO: Executing the prove command gives an error that the target file is in `voting::is_proposal_resolvable`,
-        // the level is too deep, it is difficult to obtain the value of `proposal_state`,
-        // so it cannot be verified.
-        // Can't cover all aborts_if conditions
-        pragma aborts_if_is_partial;
-        let voting_forum = borrow_global>(@aptos_framework);
+        // verify voting::resolve_proposal_v2
+        include VotingIsProposalResolvableAbortsif;
+
+        let voting_forum = global>(@aptos_framework);
         let proposal = table::spec_get(voting_forum.proposals, proposal_id);
-        requires chain_status::is_operating();
+        let post post_voting_forum = global>(@aptos_framework);
+        let post post_proposal = table::spec_get(post_voting_forum.proposals, proposal_id);
+
+        aborts_if !string::spec_internal_check_utf8(voting::IS_MULTI_STEP_PROPOSAL_IN_EXECUTION_KEY);
+        let multi_step_in_execution_key = utf8(voting::IS_MULTI_STEP_PROPOSAL_IN_EXECUTION_KEY);
+        let post is_multi_step_proposal_in_execution_value = simple_map::spec_get(post_proposal.metadata, multi_step_in_execution_key);
+        ensures simple_map::spec_contains_key(proposal.metadata, multi_step_in_execution_key) ==>
+            is_multi_step_proposal_in_execution_value == std::bcs::serialize(true);
+
+        aborts_if !string::spec_internal_check_utf8(voting::IS_MULTI_STEP_PROPOSAL_KEY);
+        let multi_step_key = utf8(voting::IS_MULTI_STEP_PROPOSAL_KEY);
+        aborts_if simple_map::spec_contains_key(proposal.metadata, multi_step_key) &&
+                            aptos_std::from_bcs::deserializable(simple_map::spec_get(proposal.metadata, multi_step_key));
+        let is_multi_step = simple_map::spec_contains_key(proposal.metadata, multi_step_key) &&
+                            aptos_std::from_bcs::deserialize(simple_map::spec_get(proposal.metadata, multi_step_key));
+        let next_execution_hash_is_empty = len(next_execution_hash) == 0;
+        aborts_if !is_multi_step && !next_execution_hash_is_empty;
+        aborts_if next_execution_hash_is_empty && is_multi_step && !simple_map::spec_contains_key(proposal.metadata, multi_step_in_execution_key); // ?
+        ensures next_execution_hash_is_empty ==> post_proposal.is_resolved == true && post_proposal.resolution_time_secs == timestamp::spec_now_seconds() &&
+            if (is_multi_step) {
+                is_multi_step_proposal_in_execution_value == std::bcs::serialize(false)
+            } else {
+                simple_map::spec_contains_key(proposal.metadata, multi_step_in_execution_key) ==>
+                    is_multi_step_proposal_in_execution_value == std::bcs::serialize(true)
+            };
+        ensures !next_execution_hash_is_empty ==> post_proposal.execution_hash == next_execution_hash &&
+            simple_map::spec_contains_key(proposal.metadata, multi_step_in_execution_key) ==>
+                is_multi_step_proposal_in_execution_value == std::bcs::serialize(true);
+
+        // verify remove_approved_hash
+        aborts_if next_execution_hash_is_empty && !exists(@aptos_framework);
+        let post post_approved_hashes = global(@aptos_framework).hashes;
+        ensures next_execution_hash_is_empty ==> !simple_map::spec_contains_key(post_approved_hashes, proposal_id);
+        ensures !next_execution_hash_is_empty ==>
+            simple_map::spec_get(post_approved_hashes, proposal_id) == next_execution_hash;
+
+        // verify get_signer
+        include GetSignerAbortsIf;
+        let governance_responsibility = global(@aptos_framework);
+        let signer_cap = simple_map::spec_get(governance_responsibility.signer_caps, signer_address);
+        let addr = signer_cap.account;
+        ensures signer::address_of(result) == addr;
+    }
+
+    spec schema VotingIsProposalResolvableAbortsif {
+        proposal_id: u64;
+
         aborts_if !exists>(@aptos_framework);
-        aborts_if !exists(@aptos_framework);
-        aborts_if !table::spec_contains(voting_forum.proposals,proposal_id);
-        aborts_if !string::spec_internal_check_utf8(b"IS_MULTI_STEP_PROPOSAL_IN_EXECUTION");
+        let voting_forum = global>(@aptos_framework);
+        let proposal = table::spec_get(voting_forum.proposals, proposal_id);
+        aborts_if !table::spec_contains(voting_forum.proposals, proposal_id);
+        let early_resolution_threshold = option::spec_borrow(proposal.early_resolution_vote_threshold);
+        let voting_period_over = timestamp::now_seconds() > proposal.expiration_secs;
+        let be_resolved_early = option::spec_is_some(proposal.early_resolution_vote_threshold) &&
+                                    (proposal.yes_votes >= early_resolution_threshold ||
+                                     proposal.no_votes >= early_resolution_threshold);
+        let voting_closed = voting_period_over || be_resolved_early;
+        // If Voting Failed
+        aborts_if voting_closed && (proposal.yes_votes <= proposal.no_votes || proposal.yes_votes + proposal.no_votes < proposal.min_vote_threshold);
+        // If Voting Pending
+        aborts_if !voting_closed;
+
+        aborts_if proposal.is_resolved;
+        aborts_if !string::spec_internal_check_utf8(voting::RESOLVABLE_TIME_METADATA_KEY);
+        aborts_if !simple_map::spec_contains_key(proposal.metadata, utf8(voting::RESOLVABLE_TIME_METADATA_KEY));
+        let resolvable_time = aptos_std::from_bcs::deserialize(simple_map::spec_get(proposal.metadata, utf8(voting::RESOLVABLE_TIME_METADATA_KEY)));
+        aborts_if !aptos_std::from_bcs::deserializable(simple_map::spec_get(proposal.metadata, utf8(voting::RESOLVABLE_TIME_METADATA_KEY)));
+        aborts_if timestamp::now_seconds() <= resolvable_time;
         aborts_if aptos_framework::transaction_context::spec_get_script_hash() != proposal.execution_hash;
-        include GetSignerAbortsIf;
     }
 }

From 4fc5447c41acb3e2df968409d48a1197ea915b71 Mon Sep 17 00:00:00 2001
From: Christian Sahar <125399153+saharct@users.noreply.github.com>
Date: Fri, 16 Jun 2023 02:14:11 -0700
Subject: [PATCH 188/200] Remove outdated information about view functions and
 add a CLI usage example (#8682)

* Remove --bytecode-version requirement

* Remove the "view functions aren't supported" statement

* Add an example of a view function request via CLI
---
 developer-docs-site/docs/integration/aptos-apis.md | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/developer-docs-site/docs/integration/aptos-apis.md b/developer-docs-site/docs/integration/aptos-apis.md
index 8e241b1b0bf74..3280a3e4fd187 100644
--- a/developer-docs-site/docs/integration/aptos-apis.md
+++ b/developer-docs-site/docs/integration/aptos-apis.md
@@ -55,9 +55,17 @@ The view function operates like the [Aptos Simulation API](../guides/system-inte
 A function does not have to be immutable to be tagged as `#[view]`, but if the function is mutable it will not result in state mutation when called from the API.
 If you want to tag a mutable function as `#[view]`, consider making it private so that it cannot be maliciously called during runtime.
 
-In order to use the View functions, you need to pass `--bytecode-version 6` to the [Aptos CLI](../tools/install-cli/index.md) when publishing the module.
+In order to use the View functions, you need to [publish the module](../move/move-on-aptos/cli.md#publishing-a-move-package-with-a-named-address) through the [Aptos CLI](../tools/install-cli/index.md).
 
-> Note: Calling View functions is not yet supported by the Aptos CLI.
+In the Aptos CLI, a view function request would look like this:
+```
+aptos move view --function-id devnet::message::get_message --profile devnet --args address:devnet                   
+{
+  "Result": [
+    "View functions rock!"
+  ]
+}
+```
 
 In the TypeScript SDK, a view function request would look like this:
 ```

From a8491dec8ec25a654f9212c64cffc8c96235f6fe Mon Sep 17 00:00:00 2001
From: Christian Sahar <125399153+saharct@users.noreply.github.com>
Date: Fri, 16 Jun 2023 02:19:06 -0700
Subject: [PATCH 189/200] Add missing commands to the command-specific help
 examples (#8681)

---
 .../tools/aptos-cli-tool/use-aptos-cli.md     | 55 +++++++++++++++++--
 1 file changed, 50 insertions(+), 5 deletions(-)

diff --git a/developer-docs-site/docs/tools/aptos-cli-tool/use-aptos-cli.md b/developer-docs-site/docs/tools/aptos-cli-tool/use-aptos-cli.md
index 948247c485cf1..3af3a1d97c6ff 100644
--- a/developer-docs-site/docs/tools/aptos-cli-tool/use-aptos-cli.md
+++ b/developer-docs-site/docs/tools/aptos-cli-tool/use-aptos-cli.md
@@ -49,10 +49,22 @@ OPTIONS:
     -V, --version    Print version information
 
 SUBCOMMANDS:
+    build-publish-payload
+            Build a publication transaction payload and store it in a JSON output file
     clean
             Cleans derived artifacts of a package
     compile
-            Compiles a package and returns the [`ModuleId`]s
+            Compiles a package and returns the associated ModuleIds
+    compile-script
+            Compiles a Move script into bytecode
+    coverage
+            Computes coverage for a package
+    create-resource-account-and-publish-package
+            Publishes the modules in a Move package to the Aptos blockchain under a resource account
+    disassemble
+            Disassemble the Move bytecode pointed to
+    document
+            Documents a Move package
     download
             Downloads a package and stores it in a directory named after the package
     help
@@ -60,17 +72,23 @@ SUBCOMMANDS:
     init
             Creates a new Move package at the given location
     list
-            Lists information about packages and modules on-chain
+            Lists information about packages and modules on-chain for an account
     prove
-            Proves the Move package
+            Proves a Move package
     publish
             Publishes the modules in a Move package to the Aptos blockchain
     run
             Run a Move function
+    run-script
+            Run a Move script
     test
             Runs Move unit tests for a package
     transactional-test
             Run Move transactional tests
+    verify-package
+            Downloads a package and verifies the bytecode
+    view
+            Run a view function
 ```
 ### Sub-command help
 
@@ -82,15 +100,30 @@ USAGE:
     aptos move compile [OPTIONS]
 
 OPTIONS:
+        --bytecode-version 
+            Specify the version of the bytecode the compiler is going to emit
+
     -h, --help
             Print help information
 
+        --included-artifacts 
+            Artifacts to be generated when building the package
+
+            Which artifacts to include in the package. This can be one of `none`, `sparse`, and
+            `all`. `none` is the most compact form and does not allow to reconstruct a source
+            package from chain; `sparse` is the minimal set of artifacts needed to reconstruct a
+            source package; `all` includes all available artifacts. The choice of included artifacts
+            heavily influences the size and therefore gas cost of publishing: `none` is the size of
+            bytecode alone; `sparse` is roughly 2 times as much; and `all` 3-4 as much.
+
+            [default: sparse]
+
         --named-addresses 
             Named addresses for the move binary
 
-            Example: alice=0x1234,bob=0x5678
+            Example: alice=0x1234, bob=0x5678
 
-            Note: This will fail if there are duplicates in the Move.toml file remove those first. Also make sure there's no space in between named addresses if more than one is provided.
+            Note: This will fail if there are duplicates in the Move.toml file remove those first.
 
             [default: ]
 
@@ -102,6 +135,18 @@ OPTIONS:
         --package-dir 
             Path to a move package (the folder with a Move.toml file)
 
+        --save-metadata
+            Save the package metadata in the package's build directory
+
+            If set, package metadata should be generated and stored in the package's build
+            directory. This metadata can be used to construct a transaction to publish a package.
+
+        --skip-fetch-latest-git-deps
+            Skip pulling the latest git dependencies
+
+            If you don't have a network connection, the compiler may fail due to no ability to pull
+            git dependencies.  This will allow overriding this for local development.
+
     -V, --version
             Print version information
 ```

From 729a4198c1934a8f688e494e816a1b843e96103e Mon Sep 17 00:00:00 2001
From: Balaji Arun 
Date: Fri, 16 Jun 2023 08:03:32 -0700
Subject: [PATCH 190/200] [forge][multiregion] Ability to run GCP multiregion
 tests on PR (#8618)

---
 .github/workflows/docker-build-test.yaml      |  24 ++++
 .../helm/aptos-node/templates/_helpers.tpl    |   2 +
 terraform/helm/aptos-node/values.yaml         |   2 +-
 .../forge-test-runner-template.fixture        | 107 ++++++++++--------
 testsuite/fixtures/testMain.fixture           |   2 +
 testsuite/forge-cli/src/main.rs               |   3 +
 testsuite/forge-test-runner-template.yaml     | 107 ++++++++++--------
 testsuite/forge.py                            |  31 +++--
 .../forge/src/backend/k8s/cluster_helper.rs   |  23 +++-
 testsuite/forge/src/backend/k8s/fullnode.rs   |  14 ++-
 testsuite/forge/src/backend/k8s/swarm.rs      |  12 ++
 testsuite/forge_test.py                       |  84 +++++++++++++-
 testsuite/test_framework/cluster.py           |   7 +-
 13 files changed, 308 insertions(+), 110 deletions(-)

diff --git a/.github/workflows/docker-build-test.yaml b/.github/workflows/docker-build-test.yaml
index 4ad334e77d7f1..1f97b20f7152a 100644
--- a/.github/workflows/docker-build-test.yaml
+++ b/.github/workflows/docker-build-test.yaml
@@ -330,3 +330,27 @@ jobs:
       FORGE_RUNNER_DURATION_SECS: 300
       COMMENT_HEADER: forge-consensus-only-perf-test
       FORGE_NAMESPACE: forge-consensus-only-perf-test-${{ needs.determine-docker-build-metadata.outputs.targetCacheId }}
+
+  # Run forge multiregion test. This test uses the multiregion forge cluster that deploys pods in three GCP regions.
+  forge-multiregion-test:
+    needs:
+      - permission-check
+      - determine-docker-build-metadata
+      - rust-images
+      - rust-images-indexer
+      - rust-images-failpoints
+      - rust-images-performance
+      - rust-images-consensus-only-perf-test
+    if: |
+      !failure() && !cancelled() && needs.permission-check.result == 'success' &&
+      contains(github.event.pull_request.labels.*.name, 'CICD:run-multiregion-test')
+    uses: aptos-labs/aptos-core/.github/workflows/workflow-run-forge.yaml@main
+    secrets: inherit
+    with:
+      GIT_SHA: ${{ needs.determine-docker-build-metadata.outputs.gitSha }}
+      FORGE_TEST_SUITE: multiregion_benchmark_test
+      IMAGE_TAG: ${{ needs.determine-docker-build-metadata.outputs.gitSha }}
+      FORGE_RUNNER_DURATION_SECS: 300
+      COMMENT_HEADER: forge-multiregion-test 
+      FORGE_NAMESPACE: forge-multiregion-test-${{ needs.determine-docker-build-metadata.outputs.targetCacheId }}
+      FORGE_CLUSTER_NAME: forge-multiregion
diff --git a/terraform/helm/aptos-node/templates/_helpers.tpl b/terraform/helm/aptos-node/templates/_helpers.tpl
index f805d33b0e49b..bda9d558f6223 100644
--- a/terraform/helm/aptos-node/templates/_helpers.tpl
+++ b/terraform/helm/aptos-node/templates/_helpers.tpl
@@ -50,6 +50,8 @@ app.kubernetes.io/managed-by: {{ .Release.Service }}
 Multicluster labels. `multiclusterLabels` takes in a tuple of context and index as arguments.
 It should be invoked as `aptos-validator.multiclusterLabels (tuple $ $i)` where $i is the index
 of the statefulset.
+
+The logic below assigns a target cluster to each statefulset replica in a round-robin fashion.
 */}}
 {{- define "aptos-validator.multiclusterLabels" -}}
 {{- $ctx := index $ 0 -}}
diff --git a/terraform/helm/aptos-node/values.yaml b/terraform/helm/aptos-node/values.yaml
index 1dda86b09216e..bd7fe2ab43641 100644
--- a/terraform/helm/aptos-node/values.yaml
+++ b/terraform/helm/aptos-node/values.yaml
@@ -17,7 +17,7 @@ numFullnodeGroups: 1
 # -- Options for multicluster mode. This is *experimental only*.
 multicluster:
   enabled: false
-  targetClusters: ["cluster1", "cluster2", "cluster3"]
+  targetClusters: ["forge-multiregion-1", "forge-multiregion-2", "forge-multiregion-3"]
 
 # -- Specify validator and fullnode NodeConfigs via named ConfigMaps, rather than the generated ones from this chart.
 overrideNodeConfig: false
diff --git a/testsuite/fixtures/forge-test-runner-template.fixture b/testsuite/fixtures/forge-test-runner-template.fixture
index 0bc4c019e890a..f65f8d53d1c22 100644
--- a/testsuite/fixtures/forge-test-runner-template.fixture
+++ b/testsuite/fixtures/forge-test-runner-template.fixture
@@ -4,64 +4,75 @@ metadata:
   name: forge-potato-1659078000-asdf
   labels:
     app.kubernetes.io/name: forge
+    app.kubernetes.io/part-of: forge-test-runner
     forge-namespace: forge-potato
     forge-image-tag: forge_asdf
 spec:
   restartPolicy: Never
   serviceAccountName: forge
   containers:
-  - name: main
-    image: 123.dkr.ecr.banana-east-1.amazonaws.com/aptos/forge:forge_asdf
-    imagePullPolicy: Always
-    command:
-    - /bin/bash
-    - -c
-    - |
-      ulimit -n 1048576
-      forge --suite banana --duration-secs 123 --num-validators 10 --num-validator-fullnodes 20 --forge-cli-arg test k8s-swarm --image-tag asdf --upgrade-image-tag upgrade_asdf --namespace forge-potato --test-arg
-    resources:
-      limits:
-        cpu: 15.5
-        memory: 26Gi
-      requests:
-        cpu: 15
-        memory: 26Gi
-    env:
-    - name: FORGE_TRIGGERED_BY
-      value: github-actions
-    - name: PROMETHEUS_URL
-      valueFrom:
-        secretKeyRef:
-          name: prometheus-read-only
-          key: url
-          optional: true
-    - name: PROMETHEUS_TOKEN
-      valueFrom:
-        secretKeyRef:
-          name: prometheus-read-only
-          key: token
-          optional: true
-    - name: RUST_BACKTRACE
-      value: "1"
-    # - name: RUST_LOG
-    #   value: debug
+    - name: main
+      image: 123.dkr.ecr.banana-east-1.amazonaws.com/aptos/forge:forge_asdf
+      imagePullPolicy: Always
+      command:
+        - /bin/bash
+        - -c
+        - |
+          ulimit -n 1048576
+          forge --suite banana --duration-secs 123 --num-validators 10 --num-validator-fullnodes 20 --forge-cli-arg test k8s-swarm --image-tag asdf --upgrade-image-tag upgrade_asdf --namespace forge-potato --test-arg
+      resources:
+        limits:
+          cpu: 15.5
+          memory: 26Gi
+        requests:
+          cpu: 15
+          memory: 26Gi
+      env:
+        - name: FORGE_TRIGGERED_BY
+          value: github-actions
+        - name: PROMETHEUS_URL
+          valueFrom:
+            secretKeyRef:
+              name: prometheus-read-only
+              key: url
+              optional: true
+        - name: PROMETHEUS_TOKEN
+          valueFrom:
+            secretKeyRef:
+              name: prometheus-read-only
+              key: token
+              optional: true
+        - name: RUST_BACKTRACE
+          value: "1"
+        - name: KUBECONFIG
+          value: /etc/multiregion-kubeconfig/kubeconfig
+      # - name: RUST_LOG
+      #   value: debug
+      volumeMounts:
+        - name: multiregion-kubeconfig
+          readOnly: true
+          mountPath: /etc/multiregion-kubeconfig
   affinity:
     # avoid scheduling with other forge or validator/fullnode pods
     podAntiAffinity:
       requiredDuringSchedulingIgnoredDuringExecution:
-      - labelSelector:
-          matchExpressions:
-          - key: app.kubernetes.io/name
-            operator: In
-            values: ["validator", "fullnode", "forge"]
-          - key: run
-            operator: Exists
-        topologyKey: "kubernetes.io/hostname"
+        - labelSelector:
+            matchExpressions:
+              - key: app.kubernetes.io/name
+                operator: In
+                values: ["validator", "fullnode", "forge"]
+              - key: run
+                operator: Exists
+          topologyKey: "kubernetes.io/hostname"
   # schedule on a k8s worker node in the "validators" nodegroup
   # to access more compute
-  nodeSelector:
-    eks.amazonaws.com/nodegroup: validators
+  nodeSelector: eks.amazonaws.com/nodegroup: validators
   tolerations:
-  - effect: NoExecute
-    key: aptos.org/nodepool
-    value: validators
+    - effect: NoExecute
+      key: aptos.org/nodepool
+      value: validators
+  volumes:
+    - name: multiregion-kubeconfig
+      secret:
+        secretName: multiregion-kubeconfig
+        optional: true
diff --git a/testsuite/fixtures/testMain.fixture b/testsuite/fixtures/testMain.fixture
index 0fd5f0bcbc28e..44e1fa949cd63 100644
--- a/testsuite/fixtures/testMain.fixture
+++ b/testsuite/fixtures/testMain.fixture
@@ -15,6 +15,8 @@ Checking if image exists in GCP: aptos/forge:banana
 * [Test runner output](None/None/actions/runs/None)
 * Test run is land-blocking
 === End temp-pre-comment ===
+Deleting forge pod for namespace forge-perry-1659078000
+Deleting forge pod for namespace forge-perry-1659078000
 === Start temp-report ===
 Forge test runner terminated:
 Trailing Log Lines:
diff --git a/testsuite/forge-cli/src/main.rs b/testsuite/forge-cli/src/main.rs
index 12b688a9f0a74..2e5f7659c1187 100644
--- a/testsuite/forge-cli/src/main.rs
+++ b/testsuite/forge-cli/src/main.rs
@@ -1802,6 +1802,9 @@ fn mainnet_like_simulation_test() -> ForgeConfig {
         )
 }
 
+/// This test runs a network test in a real multi-region setup. It configures
+/// genesis and node helm values to enable certain configurations needed to run in
+/// the multiregion forge cluster.
 fn multiregion_benchmark_test() -> ForgeConfig {
     ForgeConfig::default()
         .with_initial_validator_count(NonZeroUsize::new(20).unwrap())
diff --git a/testsuite/forge-test-runner-template.yaml b/testsuite/forge-test-runner-template.yaml
index 373bdad43557b..1ea06e59661f2 100644
--- a/testsuite/forge-test-runner-template.yaml
+++ b/testsuite/forge-test-runner-template.yaml
@@ -4,64 +4,75 @@ metadata:
   name: {FORGE_POD_NAME}
   labels:
     app.kubernetes.io/name: forge
+    app.kubernetes.io/part-of: forge-test-runner
     forge-namespace: {FORGE_NAMESPACE}
     forge-image-tag: {FORGE_IMAGE_TAG}
 spec:
   restartPolicy: Never
   serviceAccountName: forge
   containers:
-  - name: main
-    image: {FORGE_IMAGE}
-    imagePullPolicy: Always
-    command:
-    - /bin/bash
-    - -c
-    - |
-      ulimit -n 1048576
-      {FORGE_ARGS}
-    resources:
-      limits:
-        cpu: 15.5
-        memory: 26Gi
-      requests:
-        cpu: 15
-        memory: 26Gi
-    env:
-    - name: FORGE_TRIGGERED_BY
-      value: {FORGE_TRIGGERED_BY}
-    - name: PROMETHEUS_URL
-      valueFrom:
-        secretKeyRef:
-          name: prometheus-read-only
-          key: url
-          optional: true
-    - name: PROMETHEUS_TOKEN
-      valueFrom:
-        secretKeyRef:
-          name: prometheus-read-only
-          key: token
-          optional: true
-    - name: RUST_BACKTRACE
-      value: "1"
-    # - name: RUST_LOG
-    #   value: debug
+    - name: main
+      image: {FORGE_IMAGE}
+      imagePullPolicy: Always
+      command:
+        - /bin/bash
+        - -c
+        - |
+          ulimit -n 1048576
+          {FORGE_ARGS}
+      resources:
+        limits:
+          cpu: 15.5
+          memory: 26Gi
+        requests:
+          cpu: 15
+          memory: 26Gi
+      env:
+        - name: FORGE_TRIGGERED_BY
+          value: {FORGE_TRIGGERED_BY}
+        - name: PROMETHEUS_URL
+          valueFrom:
+            secretKeyRef:
+              name: prometheus-read-only
+              key: url
+              optional: true
+        - name: PROMETHEUS_TOKEN
+          valueFrom:
+            secretKeyRef:
+              name: prometheus-read-only
+              key: token
+              optional: true
+        - name: RUST_BACKTRACE
+          value: "1"
+        - name: KUBECONFIG
+          value: {KUBECONFIG}
+      # - name: RUST_LOG
+      #   value: debug
+      volumeMounts:
+        - name: multiregion-kubeconfig
+          readOnly: true
+          mountPath: {MULTIREGION_KUBECONFIG_DIR}
   affinity:
     # avoid scheduling with other forge or validator/fullnode pods
     podAntiAffinity:
       requiredDuringSchedulingIgnoredDuringExecution:
-      - labelSelector:
-          matchExpressions:
-          - key: app.kubernetes.io/name
-            operator: In
-            values: ["validator", "fullnode", "forge"]
-          - key: run
-            operator: Exists
-        topologyKey: "kubernetes.io/hostname"
+        - labelSelector:
+            matchExpressions:
+              - key: app.kubernetes.io/name
+                operator: In
+                values: ["validator", "fullnode", "forge"]
+              - key: run
+                operator: Exists
+          topologyKey: "kubernetes.io/hostname"
   # schedule on a k8s worker node in the "validators" nodegroup
   # to access more compute
-  nodeSelector:
-    {VALIDATOR_NODE_SELECTOR}
+  nodeSelector: {VALIDATOR_NODE_SELECTOR}
   tolerations:
-  - effect: NoExecute
-    key: aptos.org/nodepool
-    value: validators
+    - effect: NoExecute
+      key: aptos.org/nodepool
+      value: validators
+  volumes:
+    - name: multiregion-kubeconfig
+      secret:
+        secretName: multiregion-kubeconfig
+        optional: true
diff --git a/testsuite/forge.py b/testsuite/forge.py
index d9ef684b12cdb..17ddf81701c58 100644
--- a/testsuite/forge.py
+++ b/testsuite/forge.py
@@ -57,6 +57,8 @@
 
 FORGE_TEST_RUNNER_TEMPLATE_PATH = "forge-test-runner-template.yaml"
 
+MULTIREGION_KUBECONFIG_DIR = "/etc/multiregion-kubeconfig"
+MULTIREGION_KUBECONFIG_PATH = f"{MULTIREGION_KUBECONFIG_DIR}/kubeconfig"
 GAR_REPO_NAME = "us-west1-docker.pkg.dev/aptos-global/aptos-internal"
 
 
@@ -634,16 +636,15 @@ def run(self, context: ForgeContext) -> ForgeResult:
 
 
 class K8sForgeRunner(ForgeRunner):
-    def run(self, context: ForgeContext) -> ForgeResult:
-        forge_pod_name = sanitize_forge_resource_name(
-            f"{context.forge_namespace}-{context.time.epoch()}-{context.image_tag}"
-        )
+    def delete_forge_runner_pod(self, context: ForgeContext):
+        log.info(f"Deleting forge pod for namespace {context.forge_namespace}")
         assert context.forge_cluster.kubeconf is not None, "kubeconf is required"
         context.shell.run(
             [
                 "kubectl",
                 "--kubeconfig",
                 context.forge_cluster.kubeconf,
+                *context.forge_cluster.kubectl_create_context_arg,
                 "delete",
                 "pod",
                 "-n",
@@ -667,6 +668,16 @@ def run(self, context: ForgeContext) -> ForgeResult:
                 f"forge-namespace={context.forge_namespace}",
             ]
         )
+
+    def run(self, context: ForgeContext) -> ForgeResult:
+        forge_pod_name = sanitize_forge_resource_name(
+            f"{context.forge_namespace}-{context.time.epoch()}-{context.image_tag}",
+            max_length=52 if context.forge_cluster.is_multiregion else 63,
+        )
+        assert context.forge_cluster.kubeconf is not None, "kubeconf is required"
+
+        self.delete_forge_runner_pod(context)
+
         if context.filesystem.exists(FORGE_TEST_RUNNER_TEMPLATE_PATH):
             template = context.filesystem.read(FORGE_TEST_RUNNER_TEMPLATE_PATH)
         else:
@@ -701,6 +712,8 @@ def run(self, context: ForgeContext) -> ForgeResult:
             FORGE_ARGS=" ".join(context.forge_args),
             FORGE_TRIGGERED_BY=forge_triggered_by,
             VALIDATOR_NODE_SELECTOR=validator_node_selector,
+            KUBECONFIG=MULTIREGION_KUBECONFIG_PATH,
+            MULTIREGION_KUBECONFIG_DIR=MULTIREGION_KUBECONFIG_DIR,
         )
 
         with ForgeResult.with_context(context) as forge_result:
@@ -711,6 +724,7 @@ def run(self, context: ForgeContext) -> ForgeResult:
                     "kubectl",
                     "--kubeconfig",
                     context.forge_cluster.kubeconf,
+                    *context.forge_cluster.kubectl_create_context_arg,
                     "apply",
                     "-n",
                     "default",
@@ -797,6 +811,9 @@ def run(self, context: ForgeContext) -> ForgeResult:
 
             forge_result.set_state(state)
 
+        # cleanup the pod manually
+        self.delete_forge_runner_pod(context)
+
         return forge_result
 
 
@@ -958,11 +975,10 @@ def image_exists(
         raise Exception(f"Unknown cloud repo type: {cloud}")
 
 
-def sanitize_forge_resource_name(forge_resource: str) -> str:
+def sanitize_forge_resource_name(forge_resource: str, max_length: int = 63) -> str:
     """
     Sanitize the intended forge resource name to be a valid k8s resource name
     """
-    max_length = 63
     sanitized_namespace = ""
     for i, c in enumerate(forge_resource):
         if i >= max_length:
@@ -1324,13 +1340,14 @@ def test(
     else:
         cloud_enum = Cloud.GCP
 
-    if forge_cluster_name == "multiregion":
+    if forge_cluster_name == "forge-multiregion":
         log.info("Using multiregion cluster")
         forge_cluster = ForgeCluster(
             name=forge_cluster_name,
             cloud=Cloud.GCP,
             region="multiregion",
             kubeconf=context.filesystem.mkstemp(),
+            is_multiregion=True,
         )
     else:
         log.info(
diff --git a/testsuite/forge/src/backend/k8s/cluster_helper.rs b/testsuite/forge/src/backend/k8s/cluster_helper.rs
index f101a9e0cf391..662aa5e115f70 100644
--- a/testsuite/forge/src/backend/k8s/cluster_helper.rs
+++ b/testsuite/forge/src/backend/k8s/cluster_helper.rs
@@ -23,7 +23,7 @@ use k8s_openapi::api::{
 use kube::{
     api::{Api, DeleteParams, ListParams, ObjectMeta, Patch, PatchParams, PostParams},
     client::Client as K8sClient,
-    config::Kubeconfig,
+    config::{KubeConfigOptions, Kubeconfig},
     Config, Error as KubeError, ResourceExt,
 };
 use rand::Rng;
@@ -717,10 +717,27 @@ pub async fn collect_running_nodes(
     Ok((validators, fullnodes))
 }
 
+/// Returns a [Config] object reading the KUBECONFIG environment variable or infering from the
+/// environment. Differently from [`Config::infer()`], this will look at the
+/// `KUBECONFIG` env var first, and only then infer from the environment.
+async fn make_kube_client_config() -> Result {
+    match Config::from_kubeconfig(&KubeConfigOptions::default()).await {
+        Ok(config) => Ok(config),
+        Err(kubeconfig_err) => {
+            Config::infer()
+                .await
+                .map_err(|infer_err|
+                    anyhow::anyhow!("Unable to construct Config. Failed to infer config {:?}. Failed to read KUBECONFIG {:?}", infer_err, kubeconfig_err)
+                )
+        }
+    }
+}
+
 pub async fn create_k8s_client() -> Result {
-    let mut config = Config::infer().await?;
+    let mut config = make_kube_client_config().await?;
+
     let cluster_name = Kubeconfig::read()
-        .map(|k| k.current_context.unwrap())
+        .map(|k| k.current_context.unwrap_or_default())
         .unwrap_or_else(|_| config.cluster_url.to_string());
 
     config.accept_invalid_certs = true;
diff --git a/testsuite/forge/src/backend/k8s/fullnode.rs b/testsuite/forge/src/backend/k8s/fullnode.rs
index 32dc566bce4b9..371cb60807b57 100644
--- a/testsuite/forge/src/backend/k8s/fullnode.rs
+++ b/testsuite/forge/src/backend/k8s/fullnode.rs
@@ -441,7 +441,7 @@ pub async fn install_public_fullnode<'a>(
     info!("Wrote fullnode k8s specs to path: {:?}", &tmp_dir);
 
     // create the StatefulSet
-    stateful_set_api
+    let sts = stateful_set_api
         .create(&PostParams::default(), &fullnode_stateful_set)
         .await?;
     let fullnode_stateful_set_str = serde_yaml::to_string(&fullnode_stateful_set)?;
@@ -466,6 +466,18 @@ pub async fn install_public_fullnode<'a>(
 
     let full_service_name = format!("{}.{}.svc", service_name, &namespace); // this is the full name that includes the namespace
 
+    // Append the cluster name if its a multi-cluster deployment
+    let full_service_name = if let Some(target_cluster_name) = sts
+        .metadata
+        .labels
+        .as_ref()
+        .and_then(|labels| labels.get("multicluster/targetcluster"))
+    {
+        format!("{}.{}", &full_service_name, &target_cluster_name)
+    } else {
+        full_service_name
+    };
+
     let ret_node = K8sNode {
         name: fullnode_name.clone(),
         stateful_set_name: fullnode_stateful_set
diff --git a/testsuite/forge/src/backend/k8s/swarm.rs b/testsuite/forge/src/backend/k8s/swarm.rs
index 580b4bea9f1f6..1d0dde75f10a5 100644
--- a/testsuite/forge/src/backend/k8s/swarm.rs
+++ b/testsuite/forge/src/backend/k8s/swarm.rs
@@ -497,6 +497,18 @@ fn get_k8s_node_from_stateful_set(
         service_name = format!("{}.{}.svc", &service_name, &namespace);
     }
 
+    // Append the cluster name if its a multi-cluster deployment
+    let service_name = if let Some(target_cluster_name) = sts
+        .metadata
+        .labels
+        .as_ref()
+        .and_then(|labels| labels.get("multicluster/targetcluster"))
+    {
+        format!("{}.{}", &service_name, &target_cluster_name)
+    } else {
+        service_name
+    };
+
     // If HAProxy is enabled, use the port on its Service. Otherwise use the port on the validator Service
     let mut rest_api_port = if enable_haproxy {
         REST_API_HAPROXY_SERVICE_PORT
diff --git a/testsuite/forge_test.py b/testsuite/forge_test.py
index ff3a2fcfc5e36..6932149ebd36b 100644
--- a/testsuite/forge_test.py
+++ b/testsuite/forge_test.py
@@ -119,6 +119,7 @@ def fake_context(
     processes=None,
     time=None,
     mode=None,
+    multiregion=False,
 ) -> ForgeContext:
     return ForgeContext(
         shell=shell if shell else FakeShell(),
@@ -147,7 +148,9 @@ def fake_context(
         image_tag="asdf",
         upgrade_image_tag="upgrade_asdf",
         forge_namespace="forge-potato",
-        forge_cluster=ForgeCluster(name="tomato", kubeconf="kubeconf"),
+        forge_cluster=ForgeCluster(
+            name="tomato", kubeconf="kubeconf", is_multiregion=multiregion
+        ),
         forge_test_suite="banana",
         forge_blocking=True,
         github_actions="false",
@@ -241,6 +244,14 @@ def testK8sRunner(self) -> None:
                     "kubectl --kubeconfig kubeconf get pods -n forge-potato",
                     RunResult(0, b"Pods"),
                 ),
+                FakeCommand(
+                    "kubectl --kubeconfig kubeconf delete pod -n default -l forge-namespace=forge-potato --force",
+                    RunResult(0, b""),
+                ),
+                FakeCommand(
+                    "kubectl --kubeconfig kubeconf wait -n default --for=delete pod -l forge-namespace=forge-potato",
+                    RunResult(0, b""),
+                ),
             ]
         )
         forge_yaml = get_cwd() / "forge-test-runner-template.yaml"
@@ -262,6 +273,67 @@ def testK8sRunner(self) -> None:
         filesystem.assert_reads(self)
         self.assertEqual(result.state, ForgeState.PASS, result.output)
 
+    def testK8sRunnerWithMultiregionCluster(self) -> None:
+        self.maxDiff = None
+        shell = SpyShell(
+            [
+                FakeCommand(
+                    "kubectl --kubeconfig kubeconf --context=karmada-apiserver delete pod -n default -l forge-namespace=forge-potato --force",
+                    RunResult(0, b""),
+                ),
+                FakeCommand(
+                    "kubectl --kubeconfig kubeconf wait -n default --for=delete pod -l forge-namespace=forge-potato",
+                    RunResult(0, b""),
+                ),
+                FakeCommand(
+                    "kubectl --kubeconfig kubeconf --context=karmada-apiserver apply -n default -f temp1",
+                    RunResult(0, b""),
+                ),
+                FakeCommand(
+                    "kubectl --kubeconfig kubeconf wait -n default --timeout=5m --for=condition=Ready pod/forge-potato-1659078000-asdf",
+                    RunResult(0, b""),
+                ),
+                FakeCommand(
+                    "kubectl --kubeconfig kubeconf logs -n default -f forge-potato-1659078000-asdf",
+                    RunResult(0, b""),
+                ),
+                FakeCommand(
+                    "kubectl --kubeconfig kubeconf get pod -n default forge-potato-1659078000-asdf -o jsonpath='{.status.phase}'",
+                    RunResult(0, b"Succeeded"),
+                ),
+                FakeCommand(
+                    "kubectl --kubeconfig kubeconf get pods -n forge-potato",
+                    RunResult(0, b"Pods"),
+                ),
+                FakeCommand(
+                    "kubectl --kubeconfig kubeconf --context=karmada-apiserver delete pod -n default -l forge-namespace=forge-potato --force",
+                    RunResult(0, b""),
+                ),
+                FakeCommand(
+                    "kubectl --kubeconfig kubeconf wait -n default --for=delete pod -l forge-namespace=forge-potato",
+                    RunResult(0, b""),
+                ),
+            ]
+        )
+        forge_yaml = get_cwd() / "forge-test-runner-template.yaml"
+        template_fixture = get_fixture_path("forge-test-runner-template.fixture")
+        filesystem = SpyFilesystem(
+            {
+                "temp1": template_fixture.read_bytes(),
+            },
+            {
+                "forge-test-runner-template.yaml": FILE_NOT_FOUND,
+                "testsuite/forge-test-runner-template.yaml": forge_yaml.read_bytes(),
+            },
+        )
+        context = fake_context(shell, filesystem, mode="k8s", multiregion=True)
+        runner = K8sForgeRunner()
+        result = runner.run(context)
+        shell.assert_commands(self)
+        filesystem.assert_writes(self)
+        filesystem.assert_reads(self)
+        self.assertEqual(result.state, ForgeState.PASS, result.output)
+
 
 class TestFindRecentImage(unittest.TestCase):
     def testFindRecentImage(self) -> None:
@@ -629,6 +701,16 @@ def testMain(self) -> None:
                     "kubectl --kubeconfig temp1 get pods -n forge-perry-1659078000",
                     RunResult(0, b""),
                 ),
+                FakeCommand(
+                    "kubectl --kubeconfig temp1 delete pod -n default -l forge-namespace=forge-perry-1659078000 "
+                    "--force",
+                    RunResult(0, b""),
+                ),
+                FakeCommand(
+                    "kubectl --kubeconfig temp1 wait -n default --for=delete pod -l "
+                    "forge-namespace=forge-perry-1659078000",
+                    RunResult(0, b""),
+                ),
             ]
         )
         filesystem = SpyFilesystem(
diff --git a/testsuite/test_framework/cluster.py b/testsuite/test_framework/cluster.py
index 9cfa266f8e180..e7e8ac7bc7db8 100644
--- a/testsuite/test_framework/cluster.py
+++ b/testsuite/test_framework/cluster.py
@@ -52,6 +52,7 @@ class ForgeCluster:
     cloud: Cloud = Cloud.AWS
     region: Optional[str] = "us-west-2"
     kubeconf: Optional[str] = None
+    is_multiregion: bool = False
 
     def __repr__(self) -> str:
         return f"{self.cloud}/{self.region}/{self.name}"
@@ -60,6 +61,10 @@ def set_kubeconf(self, kubeconf: str) -> ForgeCluster:
         self.kubeconf = kubeconf
         return self
 
+    @property
+    def kubectl_create_context_arg(self) -> List[str]:
+        return ["--context=karmada-apiserver"] if self.is_multiregion else []
+
     async def write(self, shell: Shell) -> None:
         assert self.kubeconf is not None, "kubeconf must be set"
         await self.write_cluster_config(shell, self.name, self.kubeconf)
@@ -148,7 +153,7 @@ def assert_auth(self, shell: Shell) -> None:
     async def write_cluster_config(
         self, shell: Shell, cluster_name: str, temp: str
     ) -> None:
-        if cluster_name == "multiregion":
+        if self.is_multiregion:
             cmd = [
                 "gcloud",
                 "secrets",

From 181a3fd9b2ae14131e8dfb575505a90e35be6c91 Mon Sep 17 00:00:00 2001
From: Balaji Arun 
Date: Fri, 16 Jun 2023 09:46:58 -0700
Subject: [PATCH 191/200] [GHA] Use spot VM for executor-performance (#8677)

* [GHA] Use spot VM for executor-performance

* test

* duplicate spot runner

* point workflow to main
---
 .github/workflows/execution-performance.yaml   | 10 +++++++++-
 .../workflow-run-execution-performance.yaml    | 18 +++++++++++++++---
 2 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/execution-performance.yaml b/.github/workflows/execution-performance.yaml
index 67216ee58e3f6..970839dca8eec 100644
--- a/.github/workflows/execution-performance.yaml
+++ b/.github/workflows/execution-performance.yaml
@@ -7,4 +7,12 @@ jobs:
     uses: aptos-labs/aptos-core/.github/workflows/workflow-run-execution-performance.yaml@main
     secrets: inherit
     with:
-      GIT_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
\ No newline at end of file
+      GIT_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+      RUNNER_NAME: executor-benchmark-runner
+
+  spot-runner-execution-performance:
+    uses: aptos-labs/aptos-core/.github/workflows/workflow-run-execution-performance.yaml@main
+    secrets: inherit
+    with:
+      GIT_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+      RUNNER_NAME: spot-runner
\ No newline at end of file
diff --git a/.github/workflows/workflow-run-execution-performance.yaml b/.github/workflows/workflow-run-execution-performance.yaml
index 4e28733022147..fcb5c6f8ffb89 100644
--- a/.github/workflows/workflow-run-execution-performance.yaml
+++ b/.github/workflows/workflow-run-execution-performance.yaml
@@ -8,6 +8,10 @@ on:
         required: true
         type: string
         description: The git SHA1 to test.
+      RUNNER_NAME:
+        required: false
+        default: executor-benchmark-runner 
+        type: string
   # This allows the workflow to be triggered manually from the Github UI or CLI
   # NOTE: because the "number" type is not supported, we default to 720 minute timeout
   workflow_dispatch:
@@ -16,11 +20,19 @@ on:
         required: true
         type: string
         description: The git SHA1 to test.
+      RUNNER_NAME:
+        required: false
+        default: executor-benchmark-runner 
+        type: choice
+        options:
+        - spot-runner
+        - executor-benchmark-runner
+        description: The name of the runner to use for the test.
 
 jobs:
   sequential-execution-performance:
     timeout-minutes: 30
-    runs-on: executor-benchmark-runner
+    runs-on: ${{ inputs.RUNNER_NAME }}
     steps:
       - uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 # pin@v3
         with:
@@ -36,7 +48,7 @@ jobs:
 
   parallel-execution-performance:
     timeout-minutes: 60
-    runs-on: executor-benchmark-runner
+    runs-on: ${{ inputs.RUNNER_NAME }}
     steps:
       - uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 # pin@v3
         with:
@@ -52,7 +64,7 @@ jobs:
 
   single-node-performance:
     timeout-minutes: 60
-    runs-on: executor-benchmark-runner
+    runs-on: ${{ inputs.RUNNER_NAME }}
     steps:
       - uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 # pin@v3
         with:

From bea5520c277d8e57982798a36c6b60c5aa8bee00 Mon Sep 17 00:00:00 2001
From: "Brian R. Murphy" <132495859+brmataptos@users.noreply.github.com>
Date: Fri, 16 Jun 2023 10:53:51 -0700
Subject: [PATCH 192/200] Add docgen support for attributes (e.g., #[view])
 (Issue #7932) (#8636)

* Fix https://github.com/aptos-labs/aptos-core/issues/7932

Docgen should output attributes (#7932).

Output attributes (e.g., #[view] or #[resource_group(scope = global)])
from docgen for move code.  Currently only handles attibutes on
Function, Script/Module, and Struct/Resource.

Note that attributes are allowed on some other syntactic objects
(address scope, use statement, const definition, spec), but how to
format these usefully in docgen is unclear.  for these in docgen is
unclear.

Also fix an unrelated bug discovered when adapting
attribute_placement.move as a test of docgen: previously, only a
single Module/Script per input file would be output in docgen.

* Update move library docs with new docgen.

---------

Co-authored-by: Brian R. Murphy 
---
 .../framework/aptos-framework/doc/account.md  |  33 ++-
 .../aptos-framework/doc/aptos_account.md      |   6 +-
 .../aptos-framework/doc/aptos_governance.md   |  24 +-
 .../framework/aptos-framework/doc/block.md    |  12 +-
 .../framework/aptos-framework/doc/chain_id.md |   6 +-
 .../aptos-framework/doc/chain_status.md       |   6 +-
 .../framework/aptos-framework/doc/coin.md     |  51 ++--
 .../aptos-framework/doc/delegation_pool.md    |  33 ++-
 .../aptos-framework/doc/fungible_asset.md     |  39 ++-
 .../framework/aptos-framework/doc/genesis.md  |   6 +-
 .../aptos-framework/doc/multisig_account.md   |  36 ++-
 .../framework/aptos-framework/doc/object.md   |   6 +-
 .../doc/primary_fungible_store.md             |  18 +-
 .../framework/aptos-framework/doc/stake.md    |  36 ++-
 .../aptos-framework/doc/staking_contract.md   |  42 ++-
 .../aptos-framework/doc/timestamp.md          |   6 +-
 .../framework/aptos-framework/doc/vesting.md  |  84 ++++--
 .../framework/aptos-framework/doc/voting.md   |  66 +++--
 .../framework/aptos-stdlib/doc/math128.md     |   3 +-
 .../framework/aptos-stdlib/doc/math64.md      |   3 +-
 .../framework/aptos-stdlib/doc/math_fixed.md  |   3 +-
 .../aptos-stdlib/doc/math_fixed64.md          |   3 +-
 .../aptos-stdlib/doc/string_utils.md          |   3 +-
 .../framework/aptos-stdlib/doc/type_info.md   |   9 +-
 .../aptos-token-objects/doc/aptos_token.md    |  24 +-
 .../aptos-token-objects/doc/collection.md     |  24 +-
 .../aptos-token-objects/doc/property_map.md   |   3 +-
 .../aptos-token-objects/doc/royalty.md        |   3 +-
 .../aptos-token-objects/doc/token.md          |  24 +-
 aptos-move/framework/aptos-token/doc/token.md |   6 +-
 .../framework/move-stdlib/doc/vector.md       |  24 +-
 .../move-prover/move-docgen/src/docgen.rs     | 112 +++++++-
 .../tests/sources/attribute_placement.move    |  53 ++++
 .../attribute_placement.spec_inline.md        | 236 ++++++++++++++++
 ...attribute_placement.spec_inline_no_fold.md | 209 ++++++++++++++
 .../attribute_placement.spec_separate.md      | 255 ++++++++++++++++++
 third_party/move/move-stdlib/docs/vector.md   |  24 +-
 .../simple_build_with_docs/args.exp           |   4 +-
 38 files changed, 1299 insertions(+), 236 deletions(-)
 create mode 100644 third_party/move/move-prover/move-docgen/tests/sources/attribute_placement.move
 create mode 100644 third_party/move/move-prover/move-docgen/tests/sources/attribute_placement.spec_inline.md
 create mode 100644 third_party/move/move-prover/move-docgen/tests/sources/attribute_placement.spec_inline_no_fold.md
 create mode 100644 third_party/move/move-prover/move-docgen/tests/sources/attribute_placement.spec_separate.md

diff --git a/aptos-move/framework/aptos-framework/doc/account.md b/aptos-move/framework/aptos-framework/doc/account.md
index fb6fc9b70a4d2..e196457309bd9 100644
--- a/aptos-move/framework/aptos-framework/doc/account.md
+++ b/aptos-move/framework/aptos-framework/doc/account.md
@@ -936,7 +936,8 @@ is returned. This way, the caller of this function can publish additional resour
 
 
 
-
public fun exists_at(addr: address): bool
+
#[view]
+public fun exists_at(addr: address): bool
 

 
 
@@ -960,7 +961,8 @@ is returned. This way, the caller of this function can publish additional resour
 
 
 
-
public fun get_guid_next_creation_num(addr: address): u64
+
#[view]
+public fun get_guid_next_creation_num(addr: address): u64
 

 
 
@@ -984,7 +986,8 @@ is returned. This way, the caller of this function can publish additional resour
 
 
 
-
public fun get_sequence_number(addr: address): u64
+
#[view]
+public fun get_sequence_number(addr: address): u64
 

 
 
@@ -1039,7 +1042,8 @@ is returned. This way, the caller of this function can publish additional resour
 
 
 
-
public fun get_authentication_key(addr: address): vector<u8>
+
#[view]
+public fun get_authentication_key(addr: address): vector<u8>
 

 
 
@@ -1425,7 +1429,8 @@ to the account owner's signer capability).
 Returns true if the account at account_addr has a signer capability offer.
 
 
-
public fun is_signer_capability_offered(account_addr: address): bool
+
#[view]
+public fun is_signer_capability_offered(account_addr: address): bool
 

 
 
@@ -1451,7 +1456,8 @@ Returns true if the account at account_addr has a signer capability
 Returns the address of the account that has a signer capability offer from the account at account_addr.
 
 
-
public fun get_signer_capability_offer_for(account_addr: address): address
+
#[view]
+public fun get_signer_capability_offer_for(account_addr: address): address
 

 
 
@@ -2076,7 +2082,8 @@ The Account does not exist under the new address before creating the account.
 ### Function `get_guid_next_creation_num`
 
 
-
public fun get_guid_next_creation_num(addr: address): u64
+
#[view]
+public fun get_guid_next_creation_num(addr: address): u64
 

 
 
@@ -2093,7 +2100,8 @@ The Account does not exist under the new address before creating the account.
 ### Function `get_sequence_number`
 
 
-
public fun get_sequence_number(addr: address): u64
+
#[view]
+public fun get_sequence_number(addr: address): u64
 

 
 
@@ -2133,7 +2141,8 @@ The sequence_number of the Account is up to MAX_U64.
 ### Function `get_authentication_key`
 
 
-
public fun get_authentication_key(addr: address): vector<u8>
+
#[view]
+public fun get_authentication_key(addr: address): vector<u8>
 

 
 
@@ -2427,7 +2436,8 @@ The authentication scheme is ED25519_SCHEME and MULTI_ED25519_SCHEME.
 ### Function `is_signer_capability_offered`
 
 
-
public fun is_signer_capability_offered(account_addr: address): bool
+
#[view]
+public fun is_signer_capability_offered(account_addr: address): bool
 

 
 
@@ -2443,7 +2453,8 @@ The authentication scheme is ED25519_SCHEME and MULTI_ED25519_SCHEME.
 ### Function `get_signer_capability_offer_for`
 
 
-
public fun get_signer_capability_offer_for(account_addr: address): address
+
#[view]
+public fun get_signer_capability_offer_for(account_addr: address): address
 

 
 
diff --git a/aptos-move/framework/aptos-framework/doc/aptos_account.md b/aptos-move/framework/aptos-framework/doc/aptos_account.md
index 80fc8816f34f9..f77fdac11e573 100644
--- a/aptos-move/framework/aptos-framework/doc/aptos_account.md
+++ b/aptos-move/framework/aptos-framework/doc/aptos_account.md
@@ -462,7 +462,8 @@ receive.
 By default, this returns true if an account has not explicitly set whether the can receive direct transfers.
 
 
-
public fun can_receive_direct_coin_transfers(account: address): bool
+
#[view]
+public fun can_receive_direct_coin_transfers(account: address): bool
 

 
 
@@ -813,7 +814,8 @@ Check if the AptosCoin under the address existed.
 ### Function `can_receive_direct_coin_transfers`
 
 
-
public fun can_receive_direct_coin_transfers(account: address): bool
+
#[view]
+public fun can_receive_direct_coin_transfers(account: address): bool
 

 
 
diff --git a/aptos-move/framework/aptos-framework/doc/aptos_governance.md b/aptos-move/framework/aptos-framework/doc/aptos_governance.md
index 94ec6f5ae0ed0..c19ff2462a55e 100644
--- a/aptos-move/framework/aptos-framework/doc/aptos_governance.md
+++ b/aptos-move/framework/aptos-framework/doc/aptos_governance.md
@@ -707,7 +707,8 @@ AptosGovernance.
 
 
 
-
public fun get_voting_duration_secs(): u64
+
#[view]
+public fun get_voting_duration_secs(): u64
 

 
 
@@ -731,7 +732,8 @@ AptosGovernance.
 
 
 
-
public fun get_min_voting_threshold(): u128
+
#[view]
+public fun get_min_voting_threshold(): u128
 

 
 
@@ -755,7 +757,8 @@ AptosGovernance.
 
 
 
-
public fun get_required_proposer_stake(): u64
+
#[view]
+public fun get_required_proposer_stake(): u64
 

 
 
@@ -1289,7 +1292,8 @@ Return a signer for making changes to 0x1 as part of on-chain governance proposa
 
 
 
-
public fun initialize_for_verification(aptos_framework: &signer, min_voting_threshold: u128, required_proposer_stake: u64, voting_duration_secs: u64)
+
#[verify_only]
+public fun initialize_for_verification(aptos_framework: &signer, min_voting_threshold: u128, required_proposer_stake: u64, voting_duration_secs: u64)
 

 
 
@@ -1432,7 +1436,8 @@ Address @aptos_framework must exist GovernanceConfig and GovernanceEvents.
 ### Function `get_voting_duration_secs`
 
 
-
public fun get_voting_duration_secs(): u64
+
#[view]
+public fun get_voting_duration_secs(): u64
 

 
 
@@ -1448,7 +1453,8 @@ Address @aptos_framework must exist GovernanceConfig and GovernanceEvents.
 ### Function `get_min_voting_threshold`
 
 
-
public fun get_min_voting_threshold(): u128
+
#[view]
+public fun get_min_voting_threshold(): u128
 

 
 
@@ -1464,7 +1470,8 @@ Address @aptos_framework must exist GovernanceConfig and GovernanceEvents.
 ### Function `get_required_proposer_stake`
 
 
-
public fun get_required_proposer_stake(): u64
+
#[view]
+public fun get_required_proposer_stake(): u64
 

 
 
@@ -1993,7 +2000,8 @@ pool_address must exist in StakePool.
 ### Function `initialize_for_verification`
 
 
-
public fun initialize_for_verification(aptos_framework: &signer, min_voting_threshold: u128, required_proposer_stake: u64, voting_duration_secs: u64)
+
#[verify_only]
+public fun initialize_for_verification(aptos_framework: &signer, min_voting_threshold: u128, required_proposer_stake: u64, voting_duration_secs: u64)
 

 
 
diff --git a/aptos-move/framework/aptos-framework/doc/block.md b/aptos-move/framework/aptos-framework/doc/block.md
index fd19a25fc2763..5ed52b69e46a1 100644
--- a/aptos-move/framework/aptos-framework/doc/block.md
+++ b/aptos-move/framework/aptos-framework/doc/block.md
@@ -320,7 +320,8 @@ Can only be called as part of the Aptos governance proposal process established
 Return epoch interval in seconds.
 
 
-
public fun get_epoch_interval_secs(): u64
+
#[view]
+public fun get_epoch_interval_secs(): u64
 

 
 
@@ -425,7 +426,8 @@ The runtime always runs this before executing the transactions in a block.
 Get the current block height
 
 
-
public fun get_current_block_height(): u64
+
#[view]
+public fun get_current_block_height(): u64
 

 
 
@@ -667,7 +669,8 @@ The BlockResource existed under the @aptos_framework.
 ### Function `get_epoch_interval_secs`
 
 
-
public fun get_epoch_interval_secs(): u64
+
#[view]
+public fun get_epoch_interval_secs(): u64
 

 
 
@@ -710,7 +713,8 @@ The BlockResource existed under the @aptos_framework.
 ### Function `get_current_block_height`
 
 
-
public fun get_current_block_height(): u64
+
#[view]
+public fun get_current_block_height(): u64
 

 
 
diff --git a/aptos-move/framework/aptos-framework/doc/chain_id.md b/aptos-move/framework/aptos-framework/doc/chain_id.md
index 797c714576d7f..3cd22f09abc3f 100644
--- a/aptos-move/framework/aptos-framework/doc/chain_id.md
+++ b/aptos-move/framework/aptos-framework/doc/chain_id.md
@@ -82,7 +82,8 @@ Publish the chain ID id of this instance under the SystemAddresses
 Return the chain ID of this instance.
 
 
-
public fun get(): u8
+
#[view]
+public fun get(): u8
 

 
 
@@ -135,7 +136,8 @@ Return the chain ID of this instance.
 ### Function `get`
 
 
-
public fun get(): u8
+
#[view]
+public fun get(): u8
 

 
 
diff --git a/aptos-move/framework/aptos-framework/doc/chain_status.md b/aptos-move/framework/aptos-framework/doc/chain_status.md
index 46219dbe67bdd..4b91cf10f580a 100644
--- a/aptos-move/framework/aptos-framework/doc/chain_status.md
+++ b/aptos-move/framework/aptos-framework/doc/chain_status.md
@@ -114,7 +114,8 @@ Marks that genesis has finished.
 Helper function to determine if Aptos is in genesis state.
 
 
-
public fun is_genesis(): bool
+
#[view]
+public fun is_genesis(): bool
 

 
 
@@ -141,7 +142,8 @@ the same as !is_gene
 Testing is_operating() is more frequent than is_genesis().
 
 
-
public fun is_operating(): bool
+
#[view]
+public fun is_operating(): bool
 

 
 
diff --git a/aptos-move/framework/aptos-framework/doc/coin.md b/aptos-move/framework/aptos-framework/doc/coin.md
index 1dc3bd18f4d2b..7edc1cf7b7261 100644
--- a/aptos-move/framework/aptos-framework/doc/coin.md
+++ b/aptos-move/framework/aptos-framework/doc/coin.md
@@ -907,7 +907,8 @@ A helper function that returns the address of CoinType.
 Returns the balance of owner for provided CoinType.
 
 
-
public fun balance<CoinType>(owner: address): u64
+
#[view]
+public fun balance<CoinType>(owner: address): u64
 

 
 
@@ -936,7 +937,8 @@ Returns the balance of owner for provided CoinType.
 Returns true if the type CoinType is an initialized coin.
 
 
-
public fun is_coin_initialized<CoinType>(): bool
+
#[view]
+public fun is_coin_initialized<CoinType>(): bool
 

 
 
@@ -961,7 +963,8 @@ Returns true if the type CoinType is an initial
 Returns true if account_addr is registered to receive CoinType.
 
 
-
public fun is_account_registered<CoinType>(account_addr: address): bool
+
#[view]
+public fun is_account_registered<CoinType>(account_addr: address): bool
 

 
 
@@ -986,7 +989,8 @@ Returns true if account_addr is registered to r
 Returns the name of the coin.
 
 
-
public fun name<CoinType>(): string::String
+
#[view]
+public fun name<CoinType>(): string::String
 

 
 
@@ -1011,7 +1015,8 @@ Returns the name of the coin.
 Returns the symbol of the coin, usually a shorter version of the name.
 
 
-
public fun symbol<CoinType>(): string::String
+
#[view]
+public fun symbol<CoinType>(): string::String
 

 
 
@@ -1038,7 +1043,8 @@ For example, if decimals equals 2, a balance of 
 be displayed to a user as 5.05 (505 / 10 ** 2).
 
 
-
public fun decimals<CoinType>(): u8
+
#[view]
+public fun decimals<CoinType>(): u8
 

 
 
@@ -1063,7 +1069,8 @@ be displayed to a user as 5.05 (505 / 10 ** 2).
 Returns the amount of coin in existence.
 
 
-
public fun supply<CoinType>(): option::Option<u128>
+
#[view]
+public fun supply<CoinType>(): option::Option<u128>
 

 
 
@@ -1313,7 +1320,8 @@ Extracts the entire amount from the passed-in c
 Freeze a CoinStore to prevent transfers
 
 
-
public entry fun freeze_coin_store<CoinType>(account_addr: address, _freeze_cap: &coin::FreezeCapability<CoinType>)
+
#[legacy_entry_fun]
+public entry fun freeze_coin_store<CoinType>(account_addr: address, _freeze_cap: &coin::FreezeCapability<CoinType>)
 

 
 
@@ -1342,7 +1350,8 @@ Freeze a CoinStore to prevent transfers
 Unfreeze a CoinStore to allow transfers
 
 
-
public entry fun unfreeze_coin_store<CoinType>(account_addr: address, _freeze_cap: &coin::FreezeCapability<CoinType>)
+
#[legacy_entry_fun]
+public entry fun unfreeze_coin_store<CoinType>(account_addr: address, _freeze_cap: &coin::FreezeCapability<CoinType>)
 

 
 
@@ -2113,7 +2122,8 @@ Get address by reflection.
 ### Function `balance`
 
 
-
public fun balance<CoinType>(owner: address): u64
+
#[view]
+public fun balance<CoinType>(owner: address): u64
 

 
 
@@ -2130,7 +2140,8 @@ Get address by reflection.
 ### Function `is_coin_initialized`
 
 
-
public fun is_coin_initialized<CoinType>(): bool
+
#[view]
+public fun is_coin_initialized<CoinType>(): bool
 

 
 
@@ -2188,7 +2199,8 @@ Get address by reflection.
 ### Function `name`
 
 
-
public fun name<CoinType>(): string::String
+
#[view]
+public fun name<CoinType>(): string::String
 

 
 
@@ -2204,7 +2216,8 @@ Get address by reflection.
 ### Function `symbol`
 
 
-
public fun symbol<CoinType>(): string::String
+
#[view]
+public fun symbol<CoinType>(): string::String
 

 
 
@@ -2220,7 +2233,8 @@ Get address by reflection.
 ### Function `decimals`
 
 
-
public fun decimals<CoinType>(): u8
+
#[view]
+public fun decimals<CoinType>(): u8
 

 
 
@@ -2236,7 +2250,8 @@ Get address by reflection.
 ### Function `supply`
 
 
-
public fun supply<CoinType>(): option::Option<u128>
+
#[view]
+public fun supply<CoinType>(): option::Option<u128>
 

 
 
@@ -2403,7 +2418,8 @@ The value of zero_coin must be 0.
 ### Function `freeze_coin_store`
 
 
-
public entry fun freeze_coin_store<CoinType>(account_addr: address, _freeze_cap: &coin::FreezeCapability<CoinType>)
+
#[legacy_entry_fun]
+public entry fun freeze_coin_store<CoinType>(account_addr: address, _freeze_cap: &coin::FreezeCapability<CoinType>)
 

 
 
@@ -2423,7 +2439,8 @@ The value of zero_coin must be 0.
 ### Function `unfreeze_coin_store`
 
 
-
public entry fun unfreeze_coin_store<CoinType>(account_addr: address, _freeze_cap: &coin::FreezeCapability<CoinType>)
+
#[legacy_entry_fun]
+public entry fun unfreeze_coin_store<CoinType>(account_addr: address, _freeze_cap: &coin::FreezeCapability<CoinType>)
 

 
 
diff --git a/aptos-move/framework/aptos-framework/doc/delegation_pool.md b/aptos-move/framework/aptos-framework/doc/delegation_pool.md
index 205790b4df7e8..b969232722c7f 100644
--- a/aptos-move/framework/aptos-framework/doc/delegation_pool.md
+++ b/aptos-move/framework/aptos-framework/doc/delegation_pool.md
@@ -738,7 +738,8 @@ Scaling factor of shares pools used within the delegation pool
 Return whether supplied address addr is owner of a delegation pool.
 
 
-
public fun owner_cap_exists(addr: address): bool
+
#[view]
+public fun owner_cap_exists(addr: address): bool
 

 
 
@@ -763,7 +764,8 @@ Return whether supplied address addr is owner of a delegation pool.
 Return address of the delegation pool owned by owner or fail if there is none.
 
 
-
public fun get_owned_pool_address(owner: address): address
+
#[view]
+public fun get_owned_pool_address(owner: address): address
 

 
 
@@ -789,7 +791,8 @@ Return address of the delegation pool owned by owner or fail if the
 Return whether a delegation pool exists at supplied address addr.
 
 
-
public fun delegation_pool_exists(addr: address): bool
+
#[view]
+public fun delegation_pool_exists(addr: address): bool
 

 
 
@@ -814,7 +817,8 @@ Return whether a delegation pool exists at supplied address addr.
 Return the index of current observed lockup cycle on delegation pool pool_address.
 
 
-
public fun observed_lockup_cycle(pool_address: address): u64
+
#[view]
+public fun observed_lockup_cycle(pool_address: address): u64
 

 
 
@@ -840,7 +844,8 @@ Return the index of current observed lockup cycle on delegation pool pool_
 Return the operator commission percentage set on the delegation pool pool_address.
 
 
-
public fun operator_commission_percentage(pool_address: address): u64
+
#[view]
+public fun operator_commission_percentage(pool_address: address): u64
 

 
 
@@ -866,7 +871,8 @@ Return the operator commission percentage set on the delegation pool pool_
 Return the number of delegators owning active stake within pool_address.
 
 
-
public fun shareholders_count_active_pool(pool_address: address): u64
+
#[view]
+public fun shareholders_count_active_pool(pool_address: address): u64
 

 
 
@@ -893,7 +899,8 @@ Return the stake amounts on pool_address in the different states:
 (active,inactive,pending_active,pending_inactive)
 
 
-
public fun get_delegation_pool_stake(pool_address: address): (u64, u64, u64, u64)
+
#[view]
+public fun get_delegation_pool_stake(pool_address: address): (u64, u64, u64, u64)
 

 
 
@@ -920,7 +927,8 @@ Return whether the given delegator has any withdrawable stake. If they recently
 some stake and the stake pool's lockup cycle has not ended, their coins are not withdrawable yet.
 
 
-
public fun get_pending_withdrawal(pool_address: address, delegator_address: address): (bool, u64)
+
#[view]
+public fun get_pending_withdrawal(pool_address: address, delegator_address: address): (bool, u64)
 

 
 
@@ -979,7 +987,8 @@ Return total stake owned by delegator_address within delegation poo
 in each of its individual states: (active,inactive,pending_inactive)
 
 
-
public fun get_stake(pool_address: address, delegator_address: address): (u64, u64, u64)
+
#[view]
+public fun get_stake(pool_address: address, delegator_address: address): (u64, u64, u64)
 

 
 
@@ -1060,7 +1069,8 @@ for the rewards the remaining stake would have earned if active:
 extracted-fee = (amount - extracted-fee) * reward-rate% * (100% - operator-commission%)
 
 
-
public fun get_add_stake_fee(pool_address: address, amount: u64): u64
+
#[view]
+public fun get_add_stake_fee(pool_address: address, amount: u64): u64
 

 
 
@@ -1097,7 +1107,8 @@ the delegation pool, implicitly its stake pool, in the special case
 the validator had gone inactive before its lockup expired.
 
 
-
public fun can_withdraw_pending_inactive(pool_address: address): bool
+
#[view]
+public fun can_withdraw_pending_inactive(pool_address: address): bool
 

 
 
diff --git a/aptos-move/framework/aptos-framework/doc/fungible_asset.md b/aptos-move/framework/aptos-framework/doc/fungible_asset.md
index 4116601a5ac6f..55018f1719eb8 100644
--- a/aptos-move/framework/aptos-framework/doc/fungible_asset.md
+++ b/aptos-move/framework/aptos-framework/doc/fungible_asset.md
@@ -81,7 +81,8 @@ metadata object can be any object that equipped with Supply has key
+
#[resource_group_member(#[group = 0x1::object::ObjectGroup])]
+struct Supply has key
 

 
 
@@ -115,7 +116,8 @@ metadata object can be any object that equipped with Metadata has key
+
#[resource_group_member(#[group = 0x1::object::ObjectGroup])]
+struct Metadata has key
 

 
 
@@ -171,7 +173,8 @@ Metadata of a Fungible asset
 The store object that holds fungible assets of a specific type associated with an account.
 
 
-
struct FungibleStore has key
+
#[resource_group_member(#[group = 0x1::object::ObjectGroup])]
+struct FungibleStore has key
 

 
 
@@ -210,7 +213,8 @@ The store object that holds fungible assets of a specific type associated with a
 
 
 
-
struct FungibleAssetEvents has key
+
#[resource_group_member(#[group = 0x1::object::ObjectGroup])]
+struct FungibleAssetEvents has key
 

 
 
@@ -854,7 +858,8 @@ This can only be called at object creation time as constructor_ref is only avail
 Get the current supply from the metadata object.
 
 
-
public fun supply<T: key>(metadata: object::Object<T>): option::Option<u128>
+
#[view]
+public fun supply<T: key>(metadata: object::Object<T>): option::Option<u128>
 

 
 
@@ -885,7 +890,8 @@ Get the current supply from the metadata object.
 Get the maximum supply from the metadata object.
 
 
-
public fun maximum<T: key>(metadata: object::Object<T>): option::Option<u128>
+
#[view]
+public fun maximum<T: key>(metadata: object::Object<T>): option::Option<u128>
 

 
 
@@ -916,7 +922,8 @@ Get the maximum supply from the metadata object.
 Get the name of the fungible asset from the metadata object.
 
 
-
public fun name<T: key>(metadata: object::Object<T>): string::String
+
#[view]
+public fun name<T: key>(metadata: object::Object<T>): string::String
 

 
 
@@ -941,7 +948,8 @@ Get the name of the fungible asset from the metadata object.
 Get the symbol of the fungible asset from the metadata object.
 
 
-
public fun symbol<T: key>(metadata: object::Object<T>): string::String
+
#[view]
+public fun symbol<T: key>(metadata: object::Object<T>): string::String
 

 
 
@@ -966,7 +974,8 @@ Get the symbol of the fungible asset from the metadata object.
 Get the decimals from the metadata object.
 
 
-
public fun decimals<T: key>(metadata: object::Object<T>): u8
+
#[view]
+public fun decimals<T: key>(metadata: object::Object<T>): u8
 

 
 
@@ -991,7 +1000,8 @@ Get the decimals from the metadata object.
 Return whether the provided address has a store initialized.
 
 
-
public fun store_exists(store: address): bool
+
#[view]
+public fun store_exists(store: address): bool
 

 
 
@@ -1041,7 +1051,8 @@ Return the underlying metadata object
 Return the underlying metadata object.
 
 
-
public fun store_metadata<T: key>(store: object::Object<T>): object::Object<fungible_asset::Metadata>
+
#[view]
+public fun store_metadata<T: key>(store: object::Object<T>): object::Object<fungible_asset::Metadata>
 

 
 
@@ -1091,7 +1102,8 @@ Return the amount of a given fungible asset.
 Get the balance of a given store.
 
 
-
public fun balance<T: key>(store: object::Object<T>): u64
+
#[view]
+public fun balance<T: key>(store: object::Object<T>): u64
 

 
 
@@ -1122,7 +1134,8 @@ Return whether a store is frozen.
 If the store has not been created, we default to returning false so deposits can be sent to it.
 
 
-
public fun is_frozen<T: key>(store: object::Object<T>): bool
+
#[view]
+public fun is_frozen<T: key>(store: object::Object<T>): bool
 

 
 
diff --git a/aptos-move/framework/aptos-framework/doc/genesis.md b/aptos-move/framework/aptos-framework/doc/genesis.md
index 90607e0d4356b..38011baa60573 100644
--- a/aptos-move/framework/aptos-framework/doc/genesis.md
+++ b/aptos-move/framework/aptos-framework/doc/genesis.md
@@ -812,7 +812,8 @@ The last step of genesis.
 
 
 
-
fun initialize_for_verification(gas_schedule: vector<u8>, chain_id: u8, initial_version: u64, consensus_config: vector<u8>, execution_config: vector<u8>, epoch_interval_microsecs: u64, minimum_stake: u64, maximum_stake: u64, recurring_lockup_duration_secs: u64, allow_validator_set_change: bool, rewards_rate: u64, rewards_rate_denominator: u64, voting_power_increase_limit: u64, aptos_framework: &signer, min_voting_threshold: u128, required_proposer_stake: u64, voting_duration_secs: u64, accounts: vector<genesis::AccountMap>, employee_vesting_start: u64, employee_vesting_period_duration: u64, employees: vector<genesis::EmployeeAccountMap>, validators: vector<genesis::ValidatorConfigurationWithCommission>)
+
#[verify_only]
+fun initialize_for_verification(gas_schedule: vector<u8>, chain_id: u8, initial_version: u64, consensus_config: vector<u8>, execution_config: vector<u8>, epoch_interval_microsecs: u64, minimum_stake: u64, maximum_stake: u64, recurring_lockup_duration_secs: u64, allow_validator_set_change: bool, rewards_rate: u64, rewards_rate_denominator: u64, voting_power_increase_limit: u64, aptos_framework: &signer, min_voting_threshold: u128, required_proposer_stake: u64, voting_duration_secs: u64, accounts: vector<genesis::AccountMap>, employee_vesting_start: u64, employee_vesting_period_duration: u64, employees: vector<genesis::EmployeeAccountMap>, validators: vector<genesis::ValidatorConfigurationWithCommission>)
 

 
 
@@ -895,7 +896,8 @@ The last step of genesis.
 ### Function `initialize_for_verification`
 
 
-
fun initialize_for_verification(gas_schedule: vector<u8>, chain_id: u8, initial_version: u64, consensus_config: vector<u8>, execution_config: vector<u8>, epoch_interval_microsecs: u64, minimum_stake: u64, maximum_stake: u64, recurring_lockup_duration_secs: u64, allow_validator_set_change: bool, rewards_rate: u64, rewards_rate_denominator: u64, voting_power_increase_limit: u64, aptos_framework: &signer, min_voting_threshold: u128, required_proposer_stake: u64, voting_duration_secs: u64, accounts: vector<genesis::AccountMap>, employee_vesting_start: u64, employee_vesting_period_duration: u64, employees: vector<genesis::EmployeeAccountMap>, validators: vector<genesis::ValidatorConfigurationWithCommission>)
+
#[verify_only]
+fun initialize_for_verification(gas_schedule: vector<u8>, chain_id: u8, initial_version: u64, consensus_config: vector<u8>, execution_config: vector<u8>, epoch_interval_microsecs: u64, minimum_stake: u64, maximum_stake: u64, recurring_lockup_duration_secs: u64, allow_validator_set_change: bool, rewards_rate: u64, rewards_rate_denominator: u64, voting_power_increase_limit: u64, aptos_framework: &signer, min_voting_threshold: u128, required_proposer_stake: u64, voting_duration_secs: u64, accounts: vector<genesis::AccountMap>, employee_vesting_start: u64, employee_vesting_period_duration: u64, employees: vector<genesis::EmployeeAccountMap>, validators: vector<genesis::ValidatorConfigurationWithCommission>)
 

 
 
diff --git a/aptos-move/framework/aptos-framework/doc/multisig_account.md b/aptos-move/framework/aptos-framework/doc/multisig_account.md
index fdfc38d0d22c5..8d890f7668f64 100644
--- a/aptos-move/framework/aptos-framework/doc/multisig_account.md
+++ b/aptos-move/framework/aptos-framework/doc/multisig_account.md
@@ -926,7 +926,8 @@ Transaction with specified id cannot be found.
 Return the multisig account's metadata.
 
 
-
public fun metadata(multisig_account: address): simple_map::SimpleMap<string::String, vector<u8>>
+
#[view]
+public fun metadata(multisig_account: address): simple_map::SimpleMap<string::String, vector<u8>>
 

 
 
@@ -952,7 +953,8 @@ Return the number of signatures required to execute or execute-reject a transact
 multisig account.
 
 
-
public fun num_signatures_required(multisig_account: address): u64
+
#[view]
+public fun num_signatures_required(multisig_account: address): u64
 

 
 
@@ -977,7 +979,8 @@ multisig account.
 Return a vector of all of the provided multisig account's owners.
 
 
-
public fun owners(multisig_account: address): vector<address>
+
#[view]
+public fun owners(multisig_account: address): vector<address>
 

 
 
@@ -1002,7 +1005,8 @@ Return a vector of all of the provided multisig account's owners.
 Return the transaction with the given transaction id.
 
 
-
public fun get_transaction(multisig_account: address, sequence_number: u64): multisig_account::MultisigTransaction
+
#[view]
+public fun get_transaction(multisig_account: address, sequence_number: u64): multisig_account::MultisigTransaction
 

 
 
@@ -1035,7 +1039,8 @@ Return the transaction with the given transaction id.
 Return all pending transactions.
 
 
-
public fun get_pending_transactions(multisig_account: address): vector<multisig_account::MultisigTransaction>
+
#[view]
+public fun get_pending_transactions(multisig_account: address): vector<multisig_account::MultisigTransaction>
 

 
 
@@ -1068,7 +1073,8 @@ Return all pending transactions.
 Return the payload for the next transaction in the queue.
 
 
-
public fun get_next_transaction_payload(multisig_account: address, provided_payload: vector<u8>): vector<u8>
+
#[view]
+public fun get_next_transaction_payload(multisig_account: address, provided_payload: vector<u8>): vector<u8>
 

 
 
@@ -1102,7 +1108,8 @@ Return the payload for the next transaction in the queue.
 Return true if the transaction with given transaction id can be executed now.
 
 
-
public fun can_be_executed(multisig_account: address, sequence_number: u64): bool
+
#[view]
+public fun can_be_executed(multisig_account: address, sequence_number: u64): bool
 

 
 
@@ -1136,7 +1143,8 @@ Return true if the transaction with given transaction id can be executed now.
 Return true if the transaction with given transaction id can be officially rejected.
 
 
-
public fun can_be_rejected(multisig_account: address, sequence_number: u64): bool
+
#[view]
+public fun can_be_rejected(multisig_account: address, sequence_number: u64): bool
 

 
 
@@ -1170,7 +1178,8 @@ Return true if the transaction with given transaction id can be officially rejec
 Return the predicted address for the next multisig account if created from the given creator address.
 
 
-
public fun get_next_multisig_account_address(creator: address): address
+
#[view]
+public fun get_next_multisig_account_address(creator: address): address
 

 
 
@@ -1196,7 +1205,8 @@ Return the predicted address for the next multisig account if created from the g
 Return the id of the last transaction that was executed (successful or failed) or removed.
 
 
-
public fun last_resolved_sequence_number(multisig_account: address): u64
+
#[view]
+public fun last_resolved_sequence_number(multisig_account: address): u64
 

 
 
@@ -1222,7 +1232,8 @@ Return the id of the last transaction that was executed (successful or failed) o
 Return the id of the next transaction created.
 
 
-
public fun next_sequence_number(multisig_account: address): u64
+
#[view]
+public fun next_sequence_number(multisig_account: address): u64
 

 
 
@@ -1248,7 +1259,8 @@ Return the id of the next transaction created.
 Return a bool tuple indicating whether an owner has voted and if so, whether they voted yes or no.
 
 
-
public fun vote(multisig_account: address, sequence_number: u64, owner: address): (bool, bool)
+
#[view]
+public fun vote(multisig_account: address, sequence_number: u64, owner: address): (bool, bool)
 

 
 
diff --git a/aptos-move/framework/aptos-framework/doc/object.md b/aptos-move/framework/aptos-framework/doc/object.md
index 520ed1c935a9c..99ceda65c242d 100644
--- a/aptos-move/framework/aptos-framework/doc/object.md
+++ b/aptos-move/framework/aptos-framework/doc/object.md
@@ -99,7 +99,8 @@ make it so that a reference to a global object can be returned from a function.
 The core of the object model that defines ownership, transferability, and events.
 
 
-
struct ObjectCore has key
+
#[resource_group_member(#[group = 0x1::object::ObjectGroup])]
+struct ObjectCore has key
 

 
 
@@ -146,7 +147,8 @@ The core of the object model that defines ownership, transferability, and events
 A shared resource group for storing object resources together in storage.
 
 
-
struct ObjectGroup
+
#[resource_group(#[scope = global])]
+struct ObjectGroup
 

 
 
diff --git a/aptos-move/framework/aptos-framework/doc/primary_fungible_store.md b/aptos-move/framework/aptos-framework/doc/primary_fungible_store.md
index d7b91809831e3..b3666cc5065ee 100644
--- a/aptos-move/framework/aptos-framework/doc/primary_fungible_store.md
+++ b/aptos-move/framework/aptos-framework/doc/primary_fungible_store.md
@@ -51,7 +51,8 @@ stores for users with deterministic addresses so that users can easily deposit/w
 assets.
 
 
-
struct DeriveRefPod has key
+
#[resource_group_member(#[group = 0x1::object::ObjectGroup])]
+struct DeriveRefPod has key
 

 
 
@@ -195,7 +196,8 @@ Create a primary store object to hold fungible asset for the given address.
 Get the address of the primary store for the given account.
 
 
-
public fun primary_store_address<T: key>(owner: address, metadata: object::Object<T>): address
+
#[view]
+public fun primary_store_address<T: key>(owner: address, metadata: object::Object<T>): address
 

 
 
@@ -221,7 +223,8 @@ Get the address of the primary store for the given account.
 Get the primary store object for the given account.
 
 
-
public fun primary_store<T: key>(owner: address, metadata: object::Object<T>): object::Object<fungible_asset::FungibleStore>
+
#[view]
+public fun primary_store<T: key>(owner: address, metadata: object::Object<T>): object::Object<fungible_asset::FungibleStore>
 

 
 
@@ -247,7 +250,8 @@ Get the primary store object for the given account.
 Return whether the given account's primary store exists.
 
 
-
public fun primary_store_exists<T: key>(account: address, metadata: object::Object<T>): bool
+
#[view]
+public fun primary_store_exists<T: key>(account: address, metadata: object::Object<T>): bool
 

 
 
@@ -272,7 +276,8 @@ Return whether the given account's primary store exists.
 Get the balance of account's primary store.
 
 
-
public fun balance<T: key>(account: address, metadata: object::Object<T>): u64
+
#[view]
+public fun balance<T: key>(account: address, metadata: object::Object<T>): u64
 

 
 
@@ -301,7 +306,8 @@ Get the balance of account's p
 Return whether the given account's primary store is frozen.
 
 
-
public fun is_frozen<T: key>(account: address, metadata: object::Object<T>): bool
+
#[view]
+public fun is_frozen<T: key>(account: address, metadata: object::Object<T>): bool
 

 
 
diff --git a/aptos-move/framework/aptos-framework/doc/stake.md b/aptos-move/framework/aptos-framework/doc/stake.md
index e838e2f4d9a33..f829d2a58aceb 100644
--- a/aptos-move/framework/aptos-framework/doc/stake.md
+++ b/aptos-move/framework/aptos-framework/doc/stake.md
@@ -1373,7 +1373,8 @@ Return the lockup expiration of the stake pool at pool_address.
 This will throw an error if there's no stake pool at pool_address.
 
 
-
public fun get_lockup_secs(pool_address: address): u64
+
#[view]
+public fun get_lockup_secs(pool_address: address): u64
 

 
 
@@ -1400,7 +1401,8 @@ Return the remaining lockup of the stake pool at pool_address.
 This will throw an error if there's no stake pool at pool_address.
 
 
-
public fun get_remaining_lockup_secs(pool_address: address): u64
+
#[view]
+public fun get_remaining_lockup_secs(pool_address: address): u64
 

 
 
@@ -1432,7 +1434,8 @@ Return the different stake amounts for pool_address (whether the va
 The returned amounts are for (active, inactive, pending_active, pending_inactive) stake respectively.
 
 
-
public fun get_stake(pool_address: address): (u64, u64, u64, u64)
+
#[view]
+public fun get_stake(pool_address: address): (u64, u64, u64, u64)
 

 
 
@@ -1464,7 +1467,8 @@ The returned amounts are for (active, inactive, pending_active, pending_inactive
 Returns the validator's state.
 
 
-
public fun get_validator_state(pool_address: address): u64
+
#[view]
+public fun get_validator_state(pool_address: address): u64
 

 
 
@@ -1499,7 +1503,8 @@ Return the voting power of the validator in the current epoch.
 This is the same as the validator's total active and pending_inactive stake.
 
 
-
public fun get_current_epoch_voting_power(pool_address: address): u64
+
#[view]
+public fun get_current_epoch_voting_power(pool_address: address): u64
 

 
 
@@ -1533,7 +1538,8 @@ This is the same as the validator's total active and pending_inactive stake.
 Return the delegated voter of the validator at pool_address.
 
 
-
public fun get_delegated_voter(pool_address: address): address
+
#[view]
+public fun get_delegated_voter(pool_address: address): address
 

 
 
@@ -1559,7 +1565,8 @@ Return the delegated voter of the validator at pool_address.
 Return the operator of the validator at pool_address.
 
 
-
public fun get_operator(pool_address: address): address
+
#[view]
+public fun get_operator(pool_address: address): address
 

 
 
@@ -1610,7 +1617,8 @@ Return the pool address in owner_cap.
 Return the validator index for pool_address.
 
 
-
public fun get_validator_index(pool_address: address): u64
+
#[view]
+public fun get_validator_index(pool_address: address): u64
 

 
 
@@ -1636,7 +1644,8 @@ Return the validator index for pool_address.
 Return the number of successful and failed proposals for the proposal at the given validator index.
 
 
-
public fun get_current_epoch_proposal_counts(validator_index: u64): (u64, u64)
+
#[view]
+public fun get_current_epoch_proposal_counts(validator_index: u64): (u64, u64)
 

 
 
@@ -1663,7 +1672,8 @@ Return the number of successful and failed proposals for the proposal at the giv
 Return the validator's config.
 
 
-
public fun get_validator_config(pool_address: address): (vector<u8>, vector<u8>, vector<u8>)
+
#[view]
+public fun get_validator_config(pool_address: address): (vector<u8>, vector<u8>, vector<u8>)
 

 
 
@@ -1689,7 +1699,8 @@ Return the validator's config.
 
 
 
-
public fun stake_pool_exists(addr: address): bool
+
#[view]
+public fun stake_pool_exists(addr: address): bool
 

 
 
@@ -3695,7 +3706,8 @@ Returns validator's next epoch voting power, including pending_active, active, a
 ### Function `get_validator_state`
 
 
-
public fun get_validator_state(pool_address: address): u64
+
#[view]
+public fun get_validator_state(pool_address: address): u64
 

 
 
diff --git a/aptos-move/framework/aptos-framework/doc/staking_contract.md b/aptos-move/framework/aptos-framework/doc/staking_contract.md
index 3c64f4bf0fa1a..6b096895e48b8 100644
--- a/aptos-move/framework/aptos-framework/doc/staking_contract.md
+++ b/aptos-move/framework/aptos-framework/doc/staking_contract.md
@@ -123,7 +123,8 @@ pool.
 
 
 
-
struct StakingGroupContainer
+
#[resource_group(#[scope = module_])]
+struct StakingGroupContainer
 

 
 
@@ -333,7 +334,8 @@ pool.
 
 
 
-
struct StakingGroupUpdateCommissionEvent has key
+
#[resource_group_member(#[group = 0x1::staking_contract::StakingGroupContainer])]
+struct StakingGroupUpdateCommissionEvent has key
 

 
 
@@ -849,7 +851,8 @@ operator.
 This errors out the staking contract with the provided staker and operator doesn't exist.
 
 
-
public fun stake_pool_address(staker: address, operator: address): address
+
#[view]
+public fun stake_pool_address(staker: address, operator: address): address
 

 
 
@@ -879,7 +882,8 @@ for staking contract between the provided staker and operator.
 This errors out the staking contract with the provided staker and operator doesn't exist.
 
 
-
public fun last_recorded_principal(staker: address, operator: address): u64
+
#[view]
+public fun last_recorded_principal(staker: address, operator: address): u64
 

 
 
@@ -909,7 +913,8 @@ between the provided staker and operator.
 This errors out the staking contract with the provided staker and operator doesn't exist.
 
 
-
public fun commission_percentage(staker: address, operator: address): u64
+
#[view]
+public fun commission_percentage(staker: address, operator: address): u64
 

 
 
@@ -941,7 +946,8 @@ Return a tuple of three numbers:
 This errors out the staking contract with the provided staker and operator doesn't exist.
 
 
-
public fun staking_contract_amounts(staker: address, operator: address): (u64, u64, u64)
+
#[view]
+public fun staking_contract_amounts(staker: address, operator: address): (u64, u64, u64)
 

 
 
@@ -971,7 +977,8 @@ Return the number of pending distributions (e.g. commission, withdrawals from st
 This errors out the staking contract with the provided staker and operator doesn't exist.
 
 
-
public fun pending_distribution_counts(staker: address, operator: address): u64
+
#[view]
+public fun pending_distribution_counts(staker: address, operator: address): u64
 

 
 
@@ -998,7 +1005,8 @@ This errors out the staking contract with the provided staker and operator doesn
 Return true if the staking contract between the provided staker and operator exists.
 
 
-
public fun staking_contract_exists(staker: address, operator: address): bool
+
#[view]
+public fun staking_contract_exists(staker: address, operator: address): bool
 

 
 
@@ -1944,7 +1952,8 @@ Create a new staking_contracts resource.
 ### Function `stake_pool_address`
 
 
-
public fun stake_pool_address(staker: address, operator: address): address
+
#[view]
+public fun stake_pool_address(staker: address, operator: address): address
 

 
 
@@ -1960,7 +1969,8 @@ Create a new staking_contracts resource.
 ### Function `last_recorded_principal`
 
 
-
public fun last_recorded_principal(staker: address, operator: address): u64
+
#[view]
+public fun last_recorded_principal(staker: address, operator: address): u64
 

 
 
@@ -1977,7 +1987,8 @@ Staking_contract exists the stacker/operator pair.
 ### Function `commission_percentage`
 
 
-
public fun commission_percentage(staker: address, operator: address): u64
+
#[view]
+public fun commission_percentage(staker: address, operator: address): u64
 

 
 
@@ -1994,7 +2005,8 @@ Staking_contract exists the stacker/operator pair.
 ### Function `staking_contract_amounts`
 
 
-
public fun staking_contract_amounts(staker: address, operator: address): (u64, u64, u64)
+
#[view]
+public fun staking_contract_amounts(staker: address, operator: address): (u64, u64, u64)
 

 
 
@@ -2015,7 +2027,8 @@ Staking_contract exists the stacker/operator pair.
 ### Function `pending_distribution_counts`
 
 
-
public fun pending_distribution_counts(staker: address, operator: address): u64
+
#[view]
+public fun pending_distribution_counts(staker: address, operator: address): u64
 

 
 
@@ -2032,7 +2045,8 @@ Staking_contract exists the stacker/operator pair.
 ### Function `staking_contract_exists`
 
 
-
public fun staking_contract_exists(staker: address, operator: address): bool
+
#[view]
+public fun staking_contract_exists(staker: address, operator: address): bool
 

 
 
diff --git a/aptos-move/framework/aptos-framework/doc/timestamp.md b/aptos-move/framework/aptos-framework/doc/timestamp.md
index c00827692ed31..fe4b42000ded5 100644
--- a/aptos-move/framework/aptos-framework/doc/timestamp.md
+++ b/aptos-move/framework/aptos-framework/doc/timestamp.md
@@ -163,7 +163,8 @@ Updates the wall clock time by consensus. Requires VM privilege and will be invo
 Gets the current time in microseconds.
 
 
-
public fun now_microseconds(): u64
+
#[view]
+public fun now_microseconds(): u64
 

 
 
@@ -188,7 +189,8 @@ Gets the current time in microseconds.
 Gets the current time in seconds.
 
 
-
public fun now_seconds(): u64
+
#[view]
+public fun now_seconds(): u64
 

 
 
diff --git a/aptos-move/framework/aptos-framework/doc/vesting.md b/aptos-move/framework/aptos-framework/doc/vesting.md
index 50f672f7290ea..04eaa5b973c8a 100644
--- a/aptos-move/framework/aptos-framework/doc/vesting.md
+++ b/aptos-move/framework/aptos-framework/doc/vesting.md
@@ -1148,7 +1148,8 @@ Return the address of the underlying stake pool (separate resource account) of t
 This errors out if the vesting contract with the provided address doesn't exist.
 
 
-
public fun stake_pool_address(vesting_contract_address: address): address
+
#[view]
+public fun stake_pool_address(vesting_contract_address: address): address
 

 
 
@@ -1177,7 +1178,8 @@ Vesting will start at this time, and once a full period has passed, the first ve
 This errors out if the vesting contract with the provided address doesn't exist.
 
 
-
public fun vesting_start_secs(vesting_contract_address: address): u64
+
#[view]
+public fun vesting_start_secs(vesting_contract_address: address): u64
 

 
 
@@ -1206,7 +1208,8 @@ Each vest is released after one full period has started, starting from the speci
 This errors out if the vesting contract with the provided address doesn't exist.
 
 
-
public fun period_duration_secs(vesting_contract_address: address): u64
+
#[view]
+public fun period_duration_secs(vesting_contract_address: address): u64
 

 
 
@@ -1237,7 +1240,8 @@ according to the vesting schedule.
 This errors out if the vesting contract with the provided address doesn't exist.
 
 
-
public fun remaining_grant(vesting_contract_address: address): u64
+
#[view]
+public fun remaining_grant(vesting_contract_address: address): u64
 

 
 
@@ -1266,7 +1270,8 @@ This is the same as the shareholder address by default and only different if it'
 This errors out if the vesting contract with the provided address doesn't exist.
 
 
-
public fun beneficiary(vesting_contract_address: address, shareholder: address): address
+
#[view]
+public fun beneficiary(vesting_contract_address: address, shareholder: address): address
 

 
 
@@ -1294,7 +1299,8 @@ Return the percentage of accumulated rewards that is paid to the operator as com
 This errors out if the vesting contract with the provided address doesn't exist.
 
 
-
public fun operator_commission_percentage(vesting_contract_address: address): u64
+
#[view]
+public fun operator_commission_percentage(vesting_contract_address: address): u64
 

 
 
@@ -1320,7 +1326,8 @@ This errors out if the vesting contract with the provided address doesn't exist.
 Return all the vesting contracts a given address is an admin of.
 
 
-
public fun vesting_contracts(admin: address): vector<address>
+
#[view]
+public fun vesting_contracts(admin: address): vector<address>
 

 
 
@@ -1351,7 +1358,8 @@ Return the operator who runs the validator for the vesting contract.
 This errors out if the vesting contract with the provided address doesn't exist.
 
 
-
public fun operator(vesting_contract_address: address): address
+
#[view]
+public fun operator(vesting_contract_address: address): address
 

 
 
@@ -1380,7 +1388,8 @@ pool.
 This errors out if the vesting contract with the provided address doesn't exist.
 
 
-
public fun voter(vesting_contract_address: address): address
+
#[view]
+public fun voter(vesting_contract_address: address): address
 

 
 
@@ -1414,7 +1423,8 @@ So 268435456 = 0.0625.
 This errors out if the vesting contract with the provided address doesn't exist.
 
 
-
public fun vesting_schedule(vesting_contract_address: address): vesting::VestingSchedule
+
#[view]
+public fun vesting_schedule(vesting_contract_address: address): vesting::VestingSchedule
 

 
 
@@ -1443,7 +1453,8 @@ This excludes any unpaid commission that the operator has not collected.
 This errors out if the vesting contract with the provided address doesn't exist.
 
 
-
public fun total_accumulated_rewards(vesting_contract_address: address): u64
+
#[view]
+public fun total_accumulated_rewards(vesting_contract_address: address): u64
 

 
 
@@ -1476,7 +1487,8 @@ the beneficiary address instead of shareholder address.
 This errors out if the vesting contract with the provided address doesn't exist.
 
 
-
public fun accumulated_rewards(vesting_contract_address: address, shareholder_or_beneficiary: address): u64
+
#[view]
+public fun accumulated_rewards(vesting_contract_address: address, shareholder_or_beneficiary: address): u64
 

 
 
@@ -1508,7 +1520,8 @@ This errors out if the vesting contract with the provided address doesn't exist.
 Return the list of all shareholders in the vesting contract.
 
 
-
public fun shareholders(vesting_contract_address: address): vector<address>
+
#[view]
+public fun shareholders(vesting_contract_address: address): vector<address>
 

 
 
@@ -1540,7 +1553,8 @@ address is actually a shareholder address, just return the address back.
 This returns 0x0 if no shareholder is found for the given beneficiary / the address is not a shareholder itself.
 
 
-
public fun shareholder(vesting_contract_address: address, shareholder_or_beneficiary: address): address
+
#[view]
+public fun shareholder(vesting_contract_address: address, shareholder_or_beneficiary: address): address
 

 
 
@@ -2708,7 +2722,8 @@ This address should be deterministic for the same admin and vesting contract cre
 ### Function `stake_pool_address`
 
 
-
public fun stake_pool_address(vesting_contract_address: address): address
+
#[view]
+public fun stake_pool_address(vesting_contract_address: address): address
 

 
 
@@ -2724,7 +2739,8 @@ This address should be deterministic for the same admin and vesting contract cre
 ### Function `vesting_start_secs`
 
 
-
public fun vesting_start_secs(vesting_contract_address: address): u64
+
#[view]
+public fun vesting_start_secs(vesting_contract_address: address): u64
 

 
 
@@ -2740,7 +2756,8 @@ This address should be deterministic for the same admin and vesting contract cre
 ### Function `period_duration_secs`
 
 
-
public fun period_duration_secs(vesting_contract_address: address): u64
+
#[view]
+public fun period_duration_secs(vesting_contract_address: address): u64
 

 
 
@@ -2756,7 +2773,8 @@ This address should be deterministic for the same admin and vesting contract cre
 ### Function `remaining_grant`
 
 
-
public fun remaining_grant(vesting_contract_address: address): u64
+
#[view]
+public fun remaining_grant(vesting_contract_address: address): u64
 

 
 
@@ -2772,7 +2790,8 @@ This address should be deterministic for the same admin and vesting contract cre
 ### Function `beneficiary`
 
 
-
public fun beneficiary(vesting_contract_address: address, shareholder: address): address
+
#[view]
+public fun beneficiary(vesting_contract_address: address, shareholder: address): address
 

 
 
@@ -2788,7 +2807,8 @@ This address should be deterministic for the same admin and vesting contract cre
 ### Function `operator_commission_percentage`
 
 
-
public fun operator_commission_percentage(vesting_contract_address: address): u64
+
#[view]
+public fun operator_commission_percentage(vesting_contract_address: address): u64
 

 
 
@@ -2804,7 +2824,8 @@ This address should be deterministic for the same admin and vesting contract cre
 ### Function `vesting_contracts`
 
 
-
public fun vesting_contracts(admin: address): vector<address>
+
#[view]
+public fun vesting_contracts(admin: address): vector<address>
 

 
 
@@ -2820,7 +2841,8 @@ This address should be deterministic for the same admin and vesting contract cre
 ### Function `operator`
 
 
-
public fun operator(vesting_contract_address: address): address
+
#[view]
+public fun operator(vesting_contract_address: address): address
 

 
 
@@ -2836,7 +2858,8 @@ This address should be deterministic for the same admin and vesting contract cre
 ### Function `voter`
 
 
-
public fun voter(vesting_contract_address: address): address
+
#[view]
+public fun voter(vesting_contract_address: address): address
 

 
 
@@ -2852,7 +2875,8 @@ This address should be deterministic for the same admin and vesting contract cre
 ### Function `vesting_schedule`
 
 
-
public fun vesting_schedule(vesting_contract_address: address): vesting::VestingSchedule
+
#[view]
+public fun vesting_schedule(vesting_contract_address: address): vesting::VestingSchedule
 

 
 
@@ -2868,7 +2892,8 @@ This address should be deterministic for the same admin and vesting contract cre
 ### Function `total_accumulated_rewards`
 
 
-
public fun total_accumulated_rewards(vesting_contract_address: address): u64
+
#[view]
+public fun total_accumulated_rewards(vesting_contract_address: address): u64
 

 
 
@@ -2904,7 +2929,8 @@ This address should be deterministic for the same admin and vesting contract cre
 ### Function `accumulated_rewards`
 
 
-
public fun accumulated_rewards(vesting_contract_address: address, shareholder_or_beneficiary: address): u64
+
#[view]
+public fun accumulated_rewards(vesting_contract_address: address, shareholder_or_beneficiary: address): u64
 

 
 
@@ -2920,7 +2946,8 @@ This address should be deterministic for the same admin and vesting contract cre
 ### Function `shareholders`
 
 
-
public fun shareholders(vesting_contract_address: address): vector<address>
+
#[view]
+public fun shareholders(vesting_contract_address: address): vector<address>
 

 
 
@@ -2936,7 +2963,8 @@ This address should be deterministic for the same admin and vesting contract cre
 ### Function `shareholder`
 
 
-
public fun shareholder(vesting_contract_address: address, shareholder_or_beneficiary: address): address
+
#[view]
+public fun shareholder(vesting_contract_address: address, shareholder_or_beneficiary: address): address
 

 
 
diff --git a/aptos-move/framework/aptos-framework/doc/voting.md b/aptos-move/framework/aptos-framework/doc/voting.md
index ef1e50db8fae7..ca96fe6ae555a 100644
--- a/aptos-move/framework/aptos-framework/doc/voting.md
+++ b/aptos-move/framework/aptos-framework/doc/voting.md
@@ -1106,7 +1106,8 @@ there are more yes votes than no. If either of these conditions is not met, this
 Return the next unassigned proposal id
 
 
-
public fun next_proposal_id<ProposalType: store>(voting_forum_address: address): u64
+
#[view]
+public fun next_proposal_id<ProposalType: store>(voting_forum_address: address): u64
 

 
 
@@ -1131,7 +1132,8 @@ Return the next unassigned proposal id
 
 
 
-
public fun is_voting_closed<ProposalType: store>(voting_forum_address: address, proposal_id: u64): bool
+
#[view]
+public fun is_voting_closed<ProposalType: store>(voting_forum_address: address, proposal_id: u64): bool
 

 
 
@@ -1193,7 +1195,8 @@ Return the state of the proposal with given id.
 @return Proposal state as an enum value.
 
 
-
public fun get_proposal_state<ProposalType: store>(voting_forum_address: address, proposal_id: u64): u64
+
#[view]
+public fun get_proposal_state<ProposalType: store>(voting_forum_address: address, proposal_id: u64): u64
 

 
 
@@ -1234,7 +1237,8 @@ Return the state of the proposal with given id.
 Return the proposal's creation time.
 
 
-
public fun get_proposal_creation_secs<ProposalType: store>(voting_forum_address: address, proposal_id: u64): u64
+
#[view]
+public fun get_proposal_creation_secs<ProposalType: store>(voting_forum_address: address, proposal_id: u64): u64
 

 
 
@@ -1264,7 +1268,8 @@ Return the proposal's creation time.
 Return the proposal's expiration time.
 
 
-
public fun get_proposal_expiration_secs<ProposalType: store>(voting_forum_address: address, proposal_id: u64): u64
+
#[view]
+public fun get_proposal_expiration_secs<ProposalType: store>(voting_forum_address: address, proposal_id: u64): u64
 

 
 
@@ -1294,7 +1299,8 @@ Return the proposal's expiration time.
 Return the proposal's execution hash.
 
 
-
public fun get_execution_hash<ProposalType: store>(voting_forum_address: address, proposal_id: u64): vector<u8>
+
#[view]
+public fun get_execution_hash<ProposalType: store>(voting_forum_address: address, proposal_id: u64): vector<u8>
 

 
 
@@ -1324,7 +1330,8 @@ Return the proposal's execution hash.
 Return the proposal's minimum vote threshold
 
 
-
public fun get_min_vote_threshold<ProposalType: store>(voting_forum_address: address, proposal_id: u64): u128
+
#[view]
+public fun get_min_vote_threshold<ProposalType: store>(voting_forum_address: address, proposal_id: u64): u128
 

 
 
@@ -1354,7 +1361,8 @@ Return the proposal's minimum vote threshold
 Return the proposal's early resolution minimum vote threshold (optionally set)
 
 
-
public fun get_early_resolution_vote_threshold<ProposalType: store>(voting_forum_address: address, proposal_id: u64): option::Option<u128>
+
#[view]
+public fun get_early_resolution_vote_threshold<ProposalType: store>(voting_forum_address: address, proposal_id: u64): option::Option<u128>
 

 
 
@@ -1384,7 +1392,8 @@ Return the proposal's early resolution minimum vote threshold (optionally set)
 Return the proposal's current vote count (yes_votes, no_votes)
 
 
-
public fun get_votes<ProposalType: store>(voting_forum_address: address, proposal_id: u64): (u128, u128)
+
#[view]
+public fun get_votes<ProposalType: store>(voting_forum_address: address, proposal_id: u64): (u128, u128)
 

 
 
@@ -1414,7 +1423,8 @@ Return the proposal's current vote count (yes_votes, no_votes)
 Return true if the governance proposal has already been resolved.
 
 
-
public fun is_resolved<ProposalType: store>(voting_forum_address: address, proposal_id: u64): bool
+
#[view]
+public fun is_resolved<ProposalType: store>(voting_forum_address: address, proposal_id: u64): bool
 

 
 
@@ -1444,7 +1454,8 @@ Return true if the governance proposal has already been resolved.
 Return true if the multi-step governance proposal is in execution.
 
 
-
public fun is_multi_step_proposal_in_execution<ProposalType: store>(voting_forum_address: address, proposal_id: u64): bool
+
#[view]
+public fun is_multi_step_proposal_in_execution<ProposalType: store>(voting_forum_address: address, proposal_id: u64): bool
 

 
 
@@ -1697,7 +1708,8 @@ Return true if the voting period of the given proposal has already ended.
 ### Function `next_proposal_id`
 
 
-
public fun next_proposal_id<ProposalType: store>(voting_forum_address: address): u64
+
#[view]
+public fun next_proposal_id<ProposalType: store>(voting_forum_address: address): u64
 

 
 
@@ -1713,7 +1725,8 @@ Return true if the voting period of the given proposal has already ended.
 ### Function `is_voting_closed`
 
 
-
public fun is_voting_closed<ProposalType: store>(voting_forum_address: address, proposal_id: u64): bool
+
#[view]
+public fun is_voting_closed<ProposalType: store>(voting_forum_address: address, proposal_id: u64): bool
 

 
 
@@ -1758,7 +1771,8 @@ Return true if the voting period of the given proposal has already ended.
 ### Function `get_proposal_state`
 
 
-
public fun get_proposal_state<ProposalType: store>(voting_forum_address: address, proposal_id: u64): u64
+
#[view]
+public fun get_proposal_state<ProposalType: store>(voting_forum_address: address, proposal_id: u64): u64
 

 
 
@@ -1790,7 +1804,8 @@ Return true if the voting period of the given proposal has already ended.
 ### Function `get_proposal_creation_secs`
 
 
-
public fun get_proposal_creation_secs<ProposalType: store>(voting_forum_address: address, proposal_id: u64): u64
+
#[view]
+public fun get_proposal_creation_secs<ProposalType: store>(voting_forum_address: address, proposal_id: u64): u64
 

 
 
@@ -1806,7 +1821,8 @@ Return true if the voting period of the given proposal has already ended.
 ### Function `get_proposal_expiration_secs`
 
 
-
public fun get_proposal_expiration_secs<ProposalType: store>(voting_forum_address: address, proposal_id: u64): u64
+
#[view]
+public fun get_proposal_expiration_secs<ProposalType: store>(voting_forum_address: address, proposal_id: u64): u64
 

 
 
@@ -1822,7 +1838,8 @@ Return true if the voting period of the given proposal has already ended.
 ### Function `get_execution_hash`
 
 
-
public fun get_execution_hash<ProposalType: store>(voting_forum_address: address, proposal_id: u64): vector<u8>
+
#[view]
+public fun get_execution_hash<ProposalType: store>(voting_forum_address: address, proposal_id: u64): vector<u8>
 

 
 
@@ -1838,7 +1855,8 @@ Return true if the voting period of the given proposal has already ended.
 ### Function `get_min_vote_threshold`
 
 
-
public fun get_min_vote_threshold<ProposalType: store>(voting_forum_address: address, proposal_id: u64): u128
+
#[view]
+public fun get_min_vote_threshold<ProposalType: store>(voting_forum_address: address, proposal_id: u64): u128
 

 
 
@@ -1854,7 +1872,8 @@ Return true if the voting period of the given proposal has already ended.
 ### Function `get_early_resolution_vote_threshold`
 
 
-
public fun get_early_resolution_vote_threshold<ProposalType: store>(voting_forum_address: address, proposal_id: u64): option::Option<u128>
+
#[view]
+public fun get_early_resolution_vote_threshold<ProposalType: store>(voting_forum_address: address, proposal_id: u64): option::Option<u128>
 

 
 
@@ -1870,7 +1889,8 @@ Return true if the voting period of the given proposal has already ended.
 ### Function `get_votes`
 
 
-
public fun get_votes<ProposalType: store>(voting_forum_address: address, proposal_id: u64): (u128, u128)
+
#[view]
+public fun get_votes<ProposalType: store>(voting_forum_address: address, proposal_id: u64): (u128, u128)
 

 
 
@@ -1886,7 +1906,8 @@ Return true if the voting period of the given proposal has already ended.
 ### Function `is_resolved`
 
 
-
public fun is_resolved<ProposalType: store>(voting_forum_address: address, proposal_id: u64): bool
+
#[view]
+public fun is_resolved<ProposalType: store>(voting_forum_address: address, proposal_id: u64): bool
 

 
 
@@ -1917,7 +1938,8 @@ Return true if the voting period of the given proposal has already ended.
 ### Function `is_multi_step_proposal_in_execution`
 
 
-
public fun is_multi_step_proposal_in_execution<ProposalType: store>(voting_forum_address: address, proposal_id: u64): bool
+
#[view]
+public fun is_multi_step_proposal_in_execution<ProposalType: store>(voting_forum_address: address, proposal_id: u64): bool
 

 
 
diff --git a/aptos-move/framework/aptos-stdlib/doc/math128.md b/aptos-move/framework/aptos-stdlib/doc/math128.md
index 14734913c9480..d6a83377c3331 100644
--- a/aptos-move/framework/aptos-stdlib/doc/math128.md
+++ b/aptos-move/framework/aptos-stdlib/doc/math128.md
@@ -421,7 +421,8 @@ For functions that approximate a value it's useful to test a value is close
 to the most correct value up to last digit
 
 
-
fun assert_approx_the_same(x: u128, y: u128, precission: u128)
+
#[testonly]
+fun assert_approx_the_same(x: u128, y: u128, precission: u128)
 

 
 
diff --git a/aptos-move/framework/aptos-stdlib/doc/math64.md b/aptos-move/framework/aptos-stdlib/doc/math64.md
index 2cc3dafb66e28..3e8d628be3318 100644
--- a/aptos-move/framework/aptos-stdlib/doc/math64.md
+++ b/aptos-move/framework/aptos-stdlib/doc/math64.md
@@ -376,7 +376,8 @@ For functions that approximate a value it's useful to test a value is close
 to the most correct value up to last digit
 
 
-
fun assert_approx_the_same(x: u128, y: u128, precission: u64)
+
#[testonly]
+fun assert_approx_the_same(x: u128, y: u128, precission: u64)
 

 
 
diff --git a/aptos-move/framework/aptos-stdlib/doc/math_fixed.md b/aptos-move/framework/aptos-stdlib/doc/math_fixed.md
index 3b877662f9f71..2fc1bb6fe70dc 100644
--- a/aptos-move/framework/aptos-stdlib/doc/math_fixed.md
+++ b/aptos-move/framework/aptos-stdlib/doc/math_fixed.md
@@ -304,7 +304,8 @@ For functions that approximate a value it's useful to test a value is close
 to the most correct value up to last digit
 
 
-
fun assert_approx_the_same(x: u128, y: u128, precission: u128)
+
#[testonly]
+fun assert_approx_the_same(x: u128, y: u128, precission: u128)
 

 
 
diff --git a/aptos-move/framework/aptos-stdlib/doc/math_fixed64.md b/aptos-move/framework/aptos-stdlib/doc/math_fixed64.md
index 7a250af288eb7..cd972b7019ca1 100644
--- a/aptos-move/framework/aptos-stdlib/doc/math_fixed64.md
+++ b/aptos-move/framework/aptos-stdlib/doc/math_fixed64.md
@@ -299,7 +299,8 @@ For functions that approximate a value it's useful to test a value is close
 to the most correct value up to last digit
 
 
-
fun assert_approx_the_same(x: u256, y: u256, precission: u128)
+
#[testonly]
+fun assert_approx_the_same(x: u256, y: u256, precission: u128)
 

 
 
diff --git a/aptos-move/framework/aptos-stdlib/doc/string_utils.md b/aptos-move/framework/aptos-stdlib/doc/string_utils.md
index 60f2459b6d70e..7c79233721f4e 100644
--- a/aptos-move/framework/aptos-stdlib/doc/string_utils.md
+++ b/aptos-move/framework/aptos-stdlib/doc/string_utils.md
@@ -102,7 +102,8 @@ A module for formatting move values as strings.
 
 
 
-
struct FakeCons<T, N> has copy, drop, store
+
#[testonly]
+struct FakeCons<T, N> has copy, drop, store
 

 
 
diff --git a/aptos-move/framework/aptos-stdlib/doc/type_info.md b/aptos-move/framework/aptos-stdlib/doc/type_info.md
index 1846162aa4491..85fad0a2decb3 100644
--- a/aptos-move/framework/aptos-stdlib/doc/type_info.md
+++ b/aptos-move/framework/aptos-stdlib/doc/type_info.md
@@ -293,7 +293,8 @@ analysis of vector size dynamism.
 
 
 
-
fun verify_type_of()
+
#[verify_only]
+fun verify_type_of()
 

 
 
@@ -325,7 +326,8 @@ analysis of vector size dynamism.
 
 
 
-
fun verify_type_of_generic<T>()
+
#[verify_only]
+fun verify_type_of_generic<T>()
 

 
 
@@ -427,7 +429,8 @@ analysis of vector size dynamism.
 ### Function `verify_type_of_generic`
 
 
-
fun verify_type_of_generic<T>()
+
#[verify_only]
+fun verify_type_of_generic<T>()
 

 
 
diff --git a/aptos-move/framework/aptos-token-objects/doc/aptos_token.md b/aptos-move/framework/aptos-token-objects/doc/aptos_token.md
index 8e483e065f638..54c8cc83e58fc 100644
--- a/aptos-move/framework/aptos-token-objects/doc/aptos_token.md
+++ b/aptos-move/framework/aptos-token-objects/doc/aptos_token.md
@@ -77,7 +77,8 @@ The key features are:
 Storage state for managing the no-code Collection.
 
 
-
struct AptosCollection has key
+
#[resource_group_member(#[group = 0x1::object::ObjectGroup])]
+struct AptosCollection has key
 

 
 
@@ -159,7 +160,8 @@ Storage state for managing the no-code Collection.
 Storage state for managing the no-code Token.
 
 
-
struct AptosToken has key
+
#[resource_group_member(#[group = 0x1::object::ObjectGroup])]
+struct AptosToken has key
 

 
 
@@ -553,7 +555,8 @@ With an existing collection, directly mint a soul bound token into the recipient
 
 
 
-
public fun are_properties_mutable<T: key>(token: object::Object<T>): bool
+
#[view]
+public fun are_properties_mutable<T: key>(token: object::Object<T>): bool
 

 
 
@@ -578,7 +581,8 @@ With an existing collection, directly mint a soul bound token into the recipient
 
 
 
-
public fun is_burnable<T: key>(token: object::Object<T>): bool
+
#[view]
+public fun is_burnable<T: key>(token: object::Object<T>): bool
 

 
 
@@ -602,7 +606,8 @@ With an existing collection, directly mint a soul bound token into the recipient
 
 
 
-
public fun is_freezable_by_creator<T: key>(token: object::Object<T>): bool
+
#[view]
+public fun is_freezable_by_creator<T: key>(token: object::Object<T>): bool
 

 
 
@@ -626,7 +631,8 @@ With an existing collection, directly mint a soul bound token into the recipient
 
 
 
-
public fun is_mutable_description<T: key>(token: object::Object<T>): bool
+
#[view]
+public fun is_mutable_description<T: key>(token: object::Object<T>): bool
 

 
 
@@ -650,7 +656,8 @@ With an existing collection, directly mint a soul bound token into the recipient
 
 
 
-
public fun is_mutable_name<T: key>(token: object::Object<T>): bool
+
#[view]
+public fun is_mutable_name<T: key>(token: object::Object<T>): bool
 

 
 
@@ -674,7 +681,8 @@ With an existing collection, directly mint a soul bound token into the recipient
 
 
 
-
public fun is_mutable_uri<T: key>(token: object::Object<T>): bool
+
#[view]
+public fun is_mutable_uri<T: key>(token: object::Object<T>): bool
 

 
 
diff --git a/aptos-move/framework/aptos-token-objects/doc/collection.md b/aptos-move/framework/aptos-token-objects/doc/collection.md
index 4eefe2c264bef..ae8c944277e44 100644
--- a/aptos-move/framework/aptos-token-objects/doc/collection.md
+++ b/aptos-move/framework/aptos-token-objects/doc/collection.md
@@ -70,7 +70,8 @@ require adding the field original_name.
 Represents the common fields for a collection.
 
 
-
struct Collection has key
+
#[resource_group_member(#[group = 0x1::object::ObjectGroup])]
+struct Collection has key
 

 
 
@@ -181,7 +182,8 @@ Fixed supply tracker, this is useful for ensuring that a limited number of token
 and adding events and supply tracking to a collection.
 
 
-
struct FixedSupply has key
+
#[resource_group_member(#[group = 0x1::object::ObjectGroup])]
+struct FixedSupply has key
 

 
 
@@ -233,7 +235,8 @@ and adding events and supply tracking to a collection.
 Unlimited supply tracker, this is useful for adding events and supply tracking to a collection.
 
 
-
struct UnlimitedSupply has key
+
#[resource_group_member(#[group = 0x1::object::ObjectGroup])]
+struct UnlimitedSupply has key
 

 
 
@@ -887,7 +890,8 @@ Creates a MutatorRef, which gates the ability to mutate any fields that support
 Provides the count of the current selection if supply tracking is used
 
 
-
public fun count<T: key>(collection: object::Object<T>): option::Option<u64>
+
#[view]
+public fun count<T: key>(collection: object::Object<T>): option::Option<u64>
 

 
 
@@ -922,7 +926,8 @@ Provides the count of the current selection if supply tracking is used
 
 
 
-
public fun creator<T: key>(collection: object::Object<T>): address
+
#[view]
+public fun creator<T: key>(collection: object::Object<T>): address
 

 
 
@@ -946,7 +951,8 @@ Provides the count of the current selection if supply tracking is used
 
 
 
-
public fun description<T: key>(collection: object::Object<T>): string::String
+
#[view]
+public fun description<T: key>(collection: object::Object<T>): string::String
 

 
 
@@ -970,7 +976,8 @@ Provides the count of the current selection if supply tracking is used
 
 
 
-
public fun name<T: key>(collection: object::Object<T>): string::String
+
#[view]
+public fun name<T: key>(collection: object::Object<T>): string::String
 

 
 
@@ -994,7 +1001,8 @@ Provides the count of the current selection if supply tracking is used
 
 
 
-
public fun uri<T: key>(collection: object::Object<T>): string::String
+
#[view]
+public fun uri<T: key>(collection: object::Object<T>): string::String
 

 
 
diff --git a/aptos-move/framework/aptos-token-objects/doc/property_map.md b/aptos-move/framework/aptos-token-objects/doc/property_map.md
index 8775910804e79..15f7a895a3d35 100644
--- a/aptos-move/framework/aptos-token-objects/doc/property_map.md
+++ b/aptos-move/framework/aptos-token-objects/doc/property_map.md
@@ -64,7 +64,8 @@ A Map for typed key to value mapping, the contract using it
 should keep track of what keys are what types, and parse them accordingly.
 
 
-
struct PropertyMap has drop, key
+
#[resource_group_member(#[group = 0x1::object::ObjectGroup])]
+struct PropertyMap has drop, key
 

 
 
diff --git a/aptos-move/framework/aptos-token-objects/doc/royalty.md b/aptos-move/framework/aptos-token-objects/doc/royalty.md
index 9e2351b452464..68635764b9621 100644
--- a/aptos-move/framework/aptos-token-objects/doc/royalty.md
+++ b/aptos-move/framework/aptos-token-objects/doc/royalty.md
@@ -40,7 +40,8 @@ Royalties are optional for a collection.  Royalty percentage is calculated
 by (numerator / denominator) * 100%
 
 
-
struct Royalty has copy, drop, key
+
#[resource_group_member(#[group = 0x1::object::ObjectGroup])]
+struct Royalty has copy, drop, key
 

 
 
diff --git a/aptos-move/framework/aptos-token-objects/doc/token.md b/aptos-move/framework/aptos-token-objects/doc/token.md
index fe6671a10a364..0b23237681a04 100644
--- a/aptos-move/framework/aptos-token-objects/doc/token.md
+++ b/aptos-move/framework/aptos-token-objects/doc/token.md
@@ -58,7 +58,8 @@ token are:
 Represents the common fields to all tokens.
 
 
-
struct Token has key
+
#[resource_group_member(#[group = 0x1::object::ObjectGroup])]
+struct Token has key
 

 
 
@@ -612,7 +613,8 @@ Extracts the tokens address from a BurnRef.
 
 
 
-
public fun creator<T: key>(token: object::Object<T>): address
+
#[view]
+public fun creator<T: key>(token: object::Object<T>): address
 

 
 
@@ -636,7 +638,8 @@ Extracts the tokens address from a BurnRef.
 
 
 
-
public fun collection_name<T: key>(token: object::Object<T>): string::String
+
#[view]
+public fun collection_name<T: key>(token: object::Object<T>): string::String
 

 
 
@@ -660,7 +663,8 @@ Extracts the tokens address from a BurnRef.
 
 
 
-
public fun collection_object<T: key>(token: object::Object<T>): object::Object<collection::Collection>
+
#[view]
+public fun collection_object<T: key>(token: object::Object<T>): object::Object<collection::Collection>
 

 
 
@@ -684,7 +688,8 @@ Extracts the tokens address from a BurnRef.
 
 
 
-
public fun description<T: key>(token: object::Object<T>): string::String
+
#[view]
+public fun description<T: key>(token: object::Object<T>): string::String
 

 
 
@@ -708,7 +713,8 @@ Extracts the tokens address from a BurnRef.
 
 
 
-
public fun name<T: key>(token: object::Object<T>): string::String
+
#[view]
+public fun name<T: key>(token: object::Object<T>): string::String
 

 
 
@@ -732,7 +738,8 @@ Extracts the tokens address from a BurnRef.
 
 
 
-
public fun uri<T: key>(token: object::Object<T>): string::String
+
#[view]
+public fun uri<T: key>(token: object::Object<T>): string::String
 

 
 
@@ -756,7 +763,8 @@ Extracts the tokens address from a BurnRef.
 
 
 
-
public fun royalty<T: key>(token: object::Object<T>): option::Option<royalty::Royalty>
+
#[view]
+public fun royalty<T: key>(token: object::Object<T>): option::Option<royalty::Royalty>
 

 
 
diff --git a/aptos-move/framework/aptos-token/doc/token.md b/aptos-move/framework/aptos-token/doc/token.md
index 3c1435ad9faa1..f4c11b8ad1dbc 100644
--- a/aptos-move/framework/aptos-token/doc/token.md
+++ b/aptos-move/framework/aptos-token/doc/token.md
@@ -4150,7 +4150,8 @@ return if the tokendata's default properties is mutable with a token mutability
 return the collection mutation setting
 
 
-
public fun get_collection_mutability_config(creator: address, collection_name: string::String): token::CollectionMutabilityConfig
+
#[view]
+public fun get_collection_mutability_config(creator: address, collection_name: string::String): token::CollectionMutabilityConfig
 

 
 
@@ -5958,7 +5959,8 @@ The length of name should less than MAX_NFT_NAME_LENGTH
 ### Function `get_collection_mutability_config`
 
 
-
public fun get_collection_mutability_config(creator: address, collection_name: string::String): token::CollectionMutabilityConfig
+
#[view]
+public fun get_collection_mutability_config(creator: address, collection_name: string::String): token::CollectionMutabilityConfig
 

 
 
diff --git a/aptos-move/framework/move-stdlib/doc/vector.md b/aptos-move/framework/move-stdlib/doc/vector.md
index 7b4578232be25..3c6ffb2f20df4 100644
--- a/aptos-move/framework/move-stdlib/doc/vector.md
+++ b/aptos-move/framework/move-stdlib/doc/vector.md
@@ -128,7 +128,8 @@ The length of the vectors are not equal.
 Create an empty vector.
 
 
-
public fun empty<Element>(): vector<Element>
+
#[bytecode_instruction]
+public fun empty<Element>(): vector<Element>
 

 
 
@@ -151,7 +152,8 @@ Create an empty vector.
 Return the length of the vector.
 
 
-
public fun length<Element>(v: &vector<Element>): u64
+
#[bytecode_instruction]
+public fun length<Element>(v: &vector<Element>): u64
 

 
 
@@ -175,7 +177,8 @@ Acquire an immutable reference to the ith element of the vector i is out of bounds.
 
 
-
public fun borrow<Element>(v: &vector<Element>, i: u64): &Element
+
#[bytecode_instruction]
+public fun borrow<Element>(v: &vector<Element>, i: u64): &Element
 

 
 
@@ -198,7 +201,8 @@ Aborts if i is out of bounds.
 Add element e to the end of the vector v.
 
 
-
public fun push_back<Element>(v: &mut vector<Element>, e: Element)
+
#[bytecode_instruction]
+public fun push_back<Element>(v: &mut vector<Element>, e: Element)
 

 
 
@@ -222,7 +226,8 @@ Return a mutable reference to the ith element in the vector v
 Aborts if i is out of bounds.
 
 
-
public fun borrow_mut<Element>(v: &mut vector<Element>, i: u64): &mut Element
+
#[bytecode_instruction]
+public fun borrow_mut<Element>(v: &mut vector<Element>, i: u64): &mut Element
 

 
 
@@ -246,7 +251,8 @@ Pop an element from the end of vector v.
 Aborts if v is empty.
 
 
-
public fun pop_back<Element>(v: &mut vector<Element>): Element
+
#[bytecode_instruction]
+public fun pop_back<Element>(v: &mut vector<Element>): Element
 

 
 
@@ -270,7 +276,8 @@ Destroy the vector v.
 Aborts if v is not empty.
 
 
-
public fun destroy_empty<Element>(v: vector<Element>)
+
#[bytecode_instruction]
+public fun destroy_empty<Element>(v: vector<Element>)
 

 
 
@@ -294,7 +301,8 @@ Swaps the elements at the ith and jth indices in the v
 Aborts if i or j is out of bounds.
 
 
-
public fun swap<Element>(v: &mut vector<Element>, i: u64, j: u64)
+
#[bytecode_instruction]
+public fun swap<Element>(v: &mut vector<Element>, i: u64, j: u64)
 

 
 
diff --git a/third_party/move/move-prover/move-docgen/src/docgen.rs b/third_party/move/move-prover/move-docgen/src/docgen.rs
index f030f1fc58942..b0d1bbc014500 100644
--- a/third_party/move/move-prover/move-docgen/src/docgen.rs
+++ b/third_party/move/move-prover/move-docgen/src/docgen.rs
@@ -9,7 +9,7 @@ use log::{debug, info, warn};
 use move_compiler::parser::keywords::{BUILTINS, CONTEXTUAL_KEYWORDS, KEYWORDS};
 use move_core_types::account_address::AccountAddress;
 use move_model::{
-    ast::{Address, ModuleName, SpecBlockInfo, SpecBlockTarget},
+    ast::{Address, Attribute, AttributeValue, ModuleName, SpecBlockInfo, SpecBlockTarget},
     code_writer::{CodeWriter, CodeWriterLabel},
     emit, emitln,
     model::{
@@ -123,8 +123,8 @@ pub struct Docgen<'env> {
     /// Mapping from module id to the set of schemas defined in this module.
     /// We currently do not have this information in the environment.
     declared_schemas: BTreeMap>,
-    /// A list of file names and output generated for those files.
-    output: Vec<(String, String)>,
+    /// A map of file names to output generated for each file.
+    output: BTreeMap,
     /// Map from module id to information about this module.
     infos: BTreeMap,
     /// Current code writer.
@@ -237,7 +237,15 @@ impl<'env> Docgen<'env> {
             if !info.is_included && m.is_target() {
                 self.gen_module(&m, &info);
                 let path = self.make_file_in_out_dir(&info.target_file);
-                self.output.push((path, self.writer.extract_result()));
+                match self.output.get_mut(&path) {
+                    Some(out) => {
+                        out.push_str("\n\n");
+                        out.push_str(&self.writer.extract_result());
+                    },
+                    None => {
+                        self.output.insert(path, self.writer.extract_result());
+                    },
+                }
             }
         }
 
@@ -250,7 +258,7 @@ impl<'env> Docgen<'env> {
             {
                 let trimmed_content = content.trim();
                 if !trimmed_content.is_empty() {
-                    for (_, out) in self.output.iter_mut() {
+                    for out in self.output.values_mut() {
                         out.push_str("\n\n");
                         out.push_str(trimmed_content);
                         out.push('\n');
@@ -265,6 +273,9 @@ impl<'env> Docgen<'env> {
         }
 
         self.output
+            .iter()
+            .map(|(a, b)| (a.clone(), b.clone()))
+            .collect()
     }
 
     /// Compute the schemas declared in all modules. This information is currently not directly
@@ -372,10 +383,10 @@ impl<'env> Docgen<'env> {
         }
 
         // Add result to output.
-        self.output.push((
+        self.output.insert(
             self.make_file_in_out_dir(output_file_name),
             self.writer.extract_result(),
-        ));
+        );
     }
 
     /// Compute ModuleInfo for all modules, considering root template content.
@@ -477,7 +488,7 @@ impl<'env> Docgen<'env> {
         }
     }
 
-    /// Make a file name in the output directory.
+    /// Makes a file name in the output directory.
     fn make_file_in_out_dir(&self, name: &str) -> String {
         if self.options.compile_relative_to_output_dir {
             name.to_string()
@@ -488,7 +499,7 @@ impl<'env> Docgen<'env> {
         }
     }
 
-    /// Make path relative to other path.
+    /// Makes path relative to other path.
     fn path_relative_to(&self, path: &Path, to: &Path) -> PathBuf {
         if path.is_absolute() || to.is_absolute() {
             path.to_path_buf()
@@ -501,6 +512,68 @@ impl<'env> Docgen<'env> {
         }
     }
 
+    /// Gets a readable version of an attribute.
+    fn gen_attribute(&self, attribute: &Attribute) -> String {
+        let annotation_body: String = match attribute {
+            Attribute::Apply(_node_id, symbol, attribute_vector) => {
+                let symbol_string = self.name_string(*symbol).to_string();
+                if attribute_vector.is_empty() {
+                    symbol_string
+                } else {
+                    let value_string = self.gen_attributes(attribute_vector).iter().join(", ");
+                    format!("{}({})", symbol_string, value_string)
+                }
+            },
+            Attribute::Assign(_node_id, symbol, attribute_value) => {
+                let symbol_string = self.name_string(*symbol).to_string();
+                match attribute_value {
+                    AttributeValue::Value(_node_id, value) => {
+                        let value_string = self.env.display(value);
+                        format!("{} = {}", symbol_string, value_string)
+                    },
+                    AttributeValue::Name(_node_id, module_name_option, symbol2) => {
+                        let symbol2_name = self.name_string(*symbol2).to_string();
+                        let module_prefix = match module_name_option {
+                            None => "".to_string(),
+                            Some(ref module_name) => {
+                                format!("{}::", module_name.display_full(self.env))
+                            },
+                        };
+                        format!("{} = {}{}", symbol_string, module_prefix, symbol2_name)
+                    },
+                }
+            },
+        };
+        annotation_body
+    }
+
+    /// Returns attributes as vector of Strings like #[attr].
+    fn gen_attributes(&self, attributes: &[Attribute]) -> Vec {
+        if !attributes.is_empty() {
+            attributes
+                .iter()
+                .map(|attr| format!("#[{}]", self.gen_attribute(attr)))
+                .collect::>()
+        } else {
+            vec![]
+        }
+    }
+
+    /// Emits a labelled md-formatted attributes list if attributes_slice is non-empty.
+    fn emit_attributes_list(&self, attributes_slice: &[Attribute]) {
+        // Any attributes
+        let attributes = self
+            .gen_attributes(attributes_slice)
+            .iter()
+            .map(|attr| format!("\n    - `{}`", attr))
+            .join("");
+        if !attributes.is_empty() {
+            emit!(self.writer, "\n\n- Attributes:");
+            emit!(self.writer, &attributes);
+            emit!(self.writer, "\n\n");
+        }
+    }
+
     /// Generates documentation for a module. The result is written into the current code
     /// writer. Writer and other state is initialized if this module is standalone.
     fn gen_module(&mut self, module_env: &ModuleEnv<'env>, info: &ModuleInfo) {
@@ -536,6 +609,9 @@ impl<'env> Docgen<'env> {
 
         self.increment_section_nest();
 
+        // Emit a list of attributes if non-empty.
+        self.emit_attributes_list(module_env.get_attributes());
+
         // Document module overview.
         self.doc_text(module_env.get_doc());
 
@@ -973,11 +1049,17 @@ impl<'env> Docgen<'env> {
         let name = self.name_string(struct_env.get_name());
         let type_params = self.type_parameter_list_display(struct_env.get_type_parameters());
         let ability_tokens = self.ability_tokens(struct_env.get_abilities());
+        let attributes_string = self
+            .gen_attributes(struct_env.get_attributes())
+            .iter()
+            .map(|attr| format!("{}\n", attr))
+            .join("");
         if ability_tokens.is_empty() {
-            format!("struct {}{}", name, type_params)
+            format!("{}struct {}{}", attributes_string, name, type_params)
         } else {
             format!(
-                "struct {}{} has {}",
+                "{}struct {}{} has {}",
+                attributes_string,
                 name,
                 type_params,
                 ability_tokens.join(", ")
@@ -1080,8 +1162,14 @@ impl<'env> Docgen<'env> {
         } else {
             "".to_owned()
         };
+        let attributes_string = self
+            .gen_attributes(func_env.get_attributes())
+            .iter()
+            .map(|attr| format!("{}\n", attr))
+            .join("");
         format!(
-            "{}{}fun {}{}({}){}",
+            "{}{}{}fun {}{}({}){}",
+            attributes_string,
             func_env.visibility_str(),
             entry_str,
             name,
diff --git a/third_party/move/move-prover/move-docgen/tests/sources/attribute_placement.move b/third_party/move/move-prover/move-docgen/tests/sources/attribute_placement.move
new file mode 100644
index 0000000000000..ed23d6ad79df5
--- /dev/null
+++ b/third_party/move/move-prover/move-docgen/tests/sources/attribute_placement.move
@@ -0,0 +1,53 @@
+#[attr1]
+address 0x42 {
+#[attr2]
+#[attr7]
+module M {
+    #[attr3]
+    use 0x42::N;
+
+    #[attr4]
+    struct S {}
+
+    #[attr4b]
+    #[resource_group(scope = global)]
+    struct T {}
+
+    #[attr2]
+    #[attr5]
+    const C: u64 = 0;
+
+    #[attr6]
+    #[resource_group_member(group = std::string::String)]
+    public fun foo() { N::bar() }
+
+    #[attr7]
+    spec foo {}
+}
+}
+
+#[attr8]
+module 0x42::N {
+    #[attr9]
+    friend 0x42::M;
+
+    #[attr10]
+    public fun bar() {}
+}
+
+#[attr11]
+script {
+    #[attr12]
+    use 0x42::M;
+
+    #[attr13]
+    const C: u64 = 0;
+
+    #[attr14]
+    fun main() {
+        M::foo();
+    }
+
+    #[attr15]
+    spec main { }
+}
diff --git a/third_party/move/move-prover/move-docgen/tests/sources/attribute_placement.spec_inline.md b/third_party/move/move-prover/move-docgen/tests/sources/attribute_placement.spec_inline.md
new file mode 100644
index 0000000000000..8483491112ac1
--- /dev/null
+++ b/third_party/move/move-prover/move-docgen/tests/sources/attribute_placement.spec_inline.md
@@ -0,0 +1,236 @@
+
+
+
+# Module `0x42::N`
+
+
+
+- Attributes:
+    - `#[attr8]`
+
+
+
+-  [Function `bar`](#0x42_N_bar)
+
+
+

+
+
+
+
+
+## Function `bar`
+
+
+
+
#[attr10]
+public fun bar()
+

+
+
+
+

+Implementation
+
+
+
public fun bar() {}
+

+
+
+
+

+
+
+
+
+
+# Module `0x42::M`
+
+
+
+- Attributes:
+    - `#[attr2]`
+    - `#[attr7]`
+
+
+
+-  [Struct `S`](#0x42_M_S)
+-  [Struct `T`](#0x42_M_T)
+-  [Constants](#@Constants_0)
+-  [Function `foo`](#0x42_M_foo)
+
+
+
use 0x42::N;
+

+
+
+
+
+
+## Struct `S`
+
+
+
+
#[attr4]
+struct S
+

+
+
+
+

+Fields
+
+
+

+

+dummy_field: bool
+

+

+
+

+

+
+
+

+
+
+
+## Struct `T`
+
+
+
+
#[attr4b]
+#[resource_group(#[scope = global])]
+struct T
+

+
+
+
+

+Fields
+
+
+

+

+dummy_field: bool
+

+

+
+

+

+
+
+

+
+
+
+## Constants
+
+
+
+
+
+
+
const C: u64 = 0;
+

+
+
+
+
+
+## Function `foo`
+
+
+
+
#[attr6]
+#[resource_group_member(#[group = 0x1::string::String])]
+public fun foo()
+

+
+
+
+

+Implementation
+
+
+
public fun foo() { N::bar() }
+

+
+
+
+

+
+

+Specification
+
+
+
+

+
+
+
+
+
+# Module `0x1::main`
+
+
+
+- Attributes:
+    - `#[attr11]`
+
+
+
+-  [Constants](#@Constants_0)
+-  [Function `main`](#0x1_main_main)
+
+
+
use 0x42::M;
+

+
+
+
+
+
+## Constants
+
+
+
+
+
+
+
const C: u64 = 0;
+

+
+
+
+
+
+## Function `main`
+
+
+
+
#[attr14]
+fun main()
+

+
+
+
+

+Implementation
+
+
+
fun main() {
+    M::foo();
+}
+

+
+
+
+

+
+

+Specification
+
+
+
+

diff --git a/third_party/move/move-prover/move-docgen/tests/sources/attribute_placement.spec_inline_no_fold.md b/third_party/move/move-prover/move-docgen/tests/sources/attribute_placement.spec_inline_no_fold.md
new file mode 100644
index 0000000000000..ccc3e9c24e0bb
--- /dev/null
+++ b/third_party/move/move-prover/move-docgen/tests/sources/attribute_placement.spec_inline_no_fold.md
@@ -0,0 +1,209 @@
+
+
+
+# Module `0x42::N`
+
+
+
+- Attributes:
+    - `#[attr8]`
+
+
+
+-  [Function `bar`](#0x42_N_bar)
+
+
+

+
+
+
+
+
+## Function `bar`
+
+
+
+
#[attr10]
+public fun bar()
+

+
+
+
+##### Implementation
+
+
+
public fun bar() {}
+

+
+
+
+
+
+# Module `0x42::M`
+
+
+
+- Attributes:
+    - `#[attr2]`
+    - `#[attr7]`
+
+
+
+-  [Struct `S`](#0x42_M_S)
+-  [Struct `T`](#0x42_M_T)
+-  [Constants](#@Constants_0)
+-  [Function `foo`](#0x42_M_foo)
+
+
+
use 0x42::N;
+

+
+
+
+
+
+## Struct `S`
+
+
+
+
#[attr4]
+struct S
+

+
+
+
+##### Fields
+
+
+

+

+dummy_field: bool
+

+

+
+

+

+
+
+
+
+## Struct `T`
+
+
+
+
#[attr4b]
+#[resource_group(#[scope = global])]
+struct T
+

+
+
+
+##### Fields
+
+
+

+

+dummy_field: bool
+

+

+
+

+

+
+
+
+
+## Constants
+
+
+
+
+
+
+
const C: u64 = 0;
+

+
+
+
+
+
+## Function `foo`
+
+
+
+
#[attr6]
+#[resource_group_member(#[group = 0x1::string::String])]
+public fun foo()
+

+
+
+
+##### Implementation
+
+
+
public fun foo() { N::bar() }
+

+
+
+
+##### Specification
+
+
+
+
+
+# Module `0x1::main`
+
+
+
+- Attributes:
+    - `#[attr11]`
+
+
+
+-  [Constants](#@Constants_0)
+-  [Function `main`](#0x1_main_main)
+
+
+
use 0x42::M;
+

+
+
+
+
+
+## Constants
+
+
+
+
+
+
+
const C: u64 = 0;
+

+
+
+
+
+
+## Function `main`
+
+
+
+
#[attr14]
+fun main()
+

+
+
+
+##### Implementation
+
+
+
fun main() {
+    M::foo();
+}
+

+
+
+
+##### Specification
diff --git a/third_party/move/move-prover/move-docgen/tests/sources/attribute_placement.spec_separate.md b/third_party/move/move-prover/move-docgen/tests/sources/attribute_placement.spec_separate.md
new file mode 100644
index 0000000000000..03e7bb08144ed
--- /dev/null
+++ b/third_party/move/move-prover/move-docgen/tests/sources/attribute_placement.spec_separate.md
@@ -0,0 +1,255 @@
+
+
+
+# Module `0x42::N`
+
+
+
+- Attributes:
+    - `#[attr8]`
+
+
+
+-  [Function `bar`](#0x42_N_bar)
+
+
+

+
+
+
+
+
+## Function `bar`
+
+
+
+
#[attr10]
+public fun bar()
+

+
+
+
+

+Implementation
+
+
+
public fun bar() {}
+

+
+
+
+

+
+
+
+
+
+# Module `0x42::M`
+
+
+
+- Attributes:
+    - `#[attr2]`
+    - `#[attr7]`
+
+
+
+-  [Struct `S`](#0x42_M_S)
+-  [Struct `T`](#0x42_M_T)
+-  [Constants](#@Constants_0)
+-  [Function `foo`](#0x42_M_foo)
+-  [Specification](#@Specification_1)
+    -  [Function `foo`](#@Specification_1_foo)
+
+
+
use 0x42::N;
+

+
+
+
+
+
+## Struct `S`
+
+
+
+
#[attr4]
+struct S
+

+
+
+
+

+Fields
+
+
+

+

+dummy_field: bool
+

+

+
+

+

+
+
+

+
+
+
+## Struct `T`
+
+
+
+
#[attr4b]
+#[resource_group(#[scope = global])]
+struct T
+

+
+
+
+

+Fields
+
+
+

+

+dummy_field: bool
+

+

+
+

+

+
+
+

+
+
+
+## Constants
+
+
+
+
+
+
+
const C: u64 = 0;
+

+
+
+
+
+
+## Function `foo`
+
+
+
+
#[attr6]
+#[resource_group_member(#[group = 0x1::string::String])]
+public fun foo()
+

+
+
+
+

+Implementation
+
+
+
public fun foo() { N::bar() }
+

+
+
+
+

+
+
+
+## Specification
+
+
+
+
+### Function `foo`
+
+
+
#[attr6]
+#[resource_group_member(#[group = 0x1::string::String])]
+public fun foo()
+

+
+
+
+
+
+# Module `0x1::main`
+
+
+
+- Attributes:
+    - `#[attr11]`
+
+
+
+-  [Constants](#@Constants_0)
+-  [Function `main`](#0x1_main_main)
+-  [Specification](#@Specification_1)
+    -  [Function `main`](#@Specification_1_main)
+
+
+
use 0x42::M;
+

+
+
+
+
+
+## Constants
+
+
+
+
+
+
+
const C: u64 = 0;
+

+
+
+
+
+
+## Function `main`
+
+
+
+
#[attr14]
+fun main()
+

+
+
+
+

+Implementation
+
+
+
fun main() {
+    M::foo();
+}
+

+
+
+
+

+
+
+
+## Specification
+
+
+
+
+### Function `main`
+
+
+
#[attr14]
+fun main()
+

diff --git a/third_party/move/move-stdlib/docs/vector.md b/third_party/move/move-stdlib/docs/vector.md
index 6e03ecb1efa00..f175170a18286 100644
--- a/third_party/move/move-stdlib/docs/vector.md
+++ b/third_party/move/move-stdlib/docs/vector.md
@@ -68,7 +68,8 @@ The index into the vector is out of bounds
 Create an empty vector.
 
 
-
public fun empty<Element>(): vector<Element>
+
#[bytecode_instruction]
+public fun empty<Element>(): vector<Element>
 

 
 
@@ -91,7 +92,8 @@ Create an empty vector.
 Return the length of the vector.
 
 
-
public fun length<Element>(v: &vector<Element>): u64
+
#[bytecode_instruction]
+public fun length<Element>(v: &vector<Element>): u64
 

 
 
@@ -115,7 +117,8 @@ Acquire an immutable reference to the ith element of the vector i is out of bounds.
 
 
-
public fun borrow<Element>(v: &vector<Element>, i: u64): &Element
+
#[bytecode_instruction]
+public fun borrow<Element>(v: &vector<Element>, i: u64): &Element
 

 
 
@@ -138,7 +141,8 @@ Aborts if i is out of bounds.
 Add element e to the end of the vector v.
 
 
-
public fun push_back<Element>(v: &mut vector<Element>, e: Element)
+
#[bytecode_instruction]
+public fun push_back<Element>(v: &mut vector<Element>, e: Element)
 

 
 
@@ -162,7 +166,8 @@ Return a mutable reference to the ith element in the vector v
 Aborts if i is out of bounds.
 
 
-
public fun borrow_mut<Element>(v: &mut vector<Element>, i: u64): &mut Element
+
#[bytecode_instruction]
+public fun borrow_mut<Element>(v: &mut vector<Element>, i: u64): &mut Element
 

 
 
@@ -186,7 +191,8 @@ Pop an element from the end of vector v.
 Aborts if v is empty.
 
 
-
public fun pop_back<Element>(v: &mut vector<Element>): Element
+
#[bytecode_instruction]
+public fun pop_back<Element>(v: &mut vector<Element>): Element
 

 
 
@@ -210,7 +216,8 @@ Destroy the vector v.
 Aborts if v is not empty.
 
 
-
public fun destroy_empty<Element>(v: vector<Element>)
+
#[bytecode_instruction]
+public fun destroy_empty<Element>(v: vector<Element>)
 

 
 
@@ -234,7 +241,8 @@ Swaps the elements at the ith and jth indices in the v
 Aborts if i or j is out of bounds.
 
 
-
public fun swap<Element>(v: &mut vector<Element>, i: u64, j: u64)
+
#[bytecode_instruction]
+public fun swap<Element>(v: &mut vector<Element>, i: u64, j: u64)
 

 
 
diff --git a/third_party/move/tools/move-cli/tests/build_tests/simple_build_with_docs/args.exp b/third_party/move/tools/move-cli/tests/build_tests/simple_build_with_docs/args.exp
index 323ab5c2aeff1..1bd534f1b57e7 100644
--- a/third_party/move/tools/move-cli/tests/build_tests/simple_build_with_docs/args.exp
+++ b/third_party/move/tools/move-cli/tests/build_tests/simple_build_with_docs/args.exp
@@ -1,11 +1,11 @@
 Command `new --path . Foo`:
 Command `build`:
-FETCHING GIT DEPENDENCY https://github.com/move-language/move.git
+UPDATING GIT DEPENDENCY https://github.com/move-language/move.git
 INCLUDING DEPENDENCY MoveStdlib
 BUILDING Foo
 Command `docgen --template template.md --exclude-impl --exclude-private-fun --exclude-specs --include-call-diagrams --include-dep-diagrams --independent-specs --no-collapsed-sections --output-directory doc --references-file template.md --section-level-start 3 --toc-depth 3`:
-Generated "doc/template.md"
 Generated "doc/Foo.md"
+Generated "doc/template.md"
 
 Documentation generation successful!
 External Command `grep documentation doc/Foo.md`:

From 6f4524ddf1ebfb5eae598297711d489e927237cf Mon Sep 17 00:00:00 2001
From: Sital Kedia 
Date: Fri, 16 Jun 2023 14:32:01 -0700
Subject: [PATCH 193/200] [Sharding][Execution] Integrate partitioning into the
 block-stm benchmark (#8695)

---
 Cargo.lock                                    |   3 +
 .../aptos-transaction-benchmarks/Cargo.toml   |   3 +
 .../src/transactions.rs                       | 128 ++++++++++++------
 aptos-move/aptos-vm/src/adapter_common.rs     |   2 +-
 aptos-move/aptos-vm/src/aptos_vm.rs           |   8 +-
 aptos-move/aptos-vm/src/block_executor/mod.rs |  28 ++--
 aptos-move/aptos-vm/src/lib.rs                |   3 +-
 .../block_executor_client.rs                  |   9 +-
 .../sharded_block_executor/executor_shard.rs  |   4 +-
 .../src/sharded_block_executor/mod.rs         |  30 ++--
 aptos-move/block-executor/src/executor.rs     |  33 ++---
 .../src/proptest_types/bencher.rs             |   8 +-
 .../src/proptest_types/tests.rs               |  40 ++----
 aptos-move/block-executor/src/task.rs         |   4 +-
 .../block-executor/src/unit_tests/mod.rs      |  13 +-
 aptos-move/e2e-tests/src/executor.rs          |   4 +-
 .../conflict_detector.rs                      |   9 +-
 .../dependent_edges.rs                        |  22 ++-
 .../src/sharded_block_partitioner/messages.rs |  14 +-
 .../src/sharded_block_partitioner/mod.rs      |  55 ++++----
 .../partitioning_shard.rs                     |   8 +-
 execution/executor-service/src/lib.rs         |   3 +-
 .../src/remote_executor_client.rs             |   5 +-
 .../src/remote_executor_service.rs            |  26 +++-
 .../executor/src/components/chunk_output.rs   |  12 +-
 execution/executor/src/fuzzing.rs             |   4 +-
 execution/executor/src/mock_vm/mod.rs         |   4 +-
 testsuite/parallel_execution_performance.py   |  14 +-
 testsuite/sequential_execution_performance.py |   2 +-
 types/src/block_executor/partitioner.rs       | 122 ++++++++++++++---
 types/src/transaction/analyzed_transaction.rs |   5 +-
 31 files changed, 388 insertions(+), 237 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 182e78620ea7f..47e38a1b5394a 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3183,6 +3183,7 @@ name = "aptos-transaction-benchmarks"
 version = "0.1.0"
 dependencies = [
  "aptos-bitvec",
+ "aptos-block-partitioner",
  "aptos-crypto",
  "aptos-executor-service",
  "aptos-gas",
@@ -3196,7 +3197,9 @@ dependencies = [
  "criterion",
  "criterion-cpu-time",
  "num_cpus",
+ "once_cell",
  "proptest",
+ "rayon",
 ]
 
 [[package]]
diff --git a/aptos-move/aptos-transaction-benchmarks/Cargo.toml b/aptos-move/aptos-transaction-benchmarks/Cargo.toml
index 65991ae4c701e..c12858ab2218f 100644
--- a/aptos-move/aptos-transaction-benchmarks/Cargo.toml
+++ b/aptos-move/aptos-transaction-benchmarks/Cargo.toml
@@ -14,6 +14,7 @@ rust-version = { workspace = true }
 
 [dependencies]
 aptos-bitvec = { workspace = true }
+aptos-block-partitioner = { workspace = true }
 aptos-crypto = { workspace = true }
 aptos-executor-service = { workspace = true }
 aptos-gas = { workspace = true, features = ["testing"] }
@@ -27,7 +28,9 @@ clap = { workspace = true }
 criterion = { workspace = true, features = ["html_reports"] }
 criterion-cpu-time = { workspace = true }
 num_cpus = { workspace = true }
+once_cell = { workspace = true }
 proptest = { workspace = true }
+rayon = { workspace = true }
 
 [[bench]]
 name = "transaction_benches"
diff --git a/aptos-move/aptos-transaction-benchmarks/src/transactions.rs b/aptos-move/aptos-transaction-benchmarks/src/transactions.rs
index 133cce21ebd68..57eb02485b856 100644
--- a/aptos-move/aptos-transaction-benchmarks/src/transactions.rs
+++ b/aptos-move/aptos-transaction-benchmarks/src/transactions.rs
@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use aptos_bitvec::BitVec;
+use aptos_block_partitioner::sharded_block_partitioner::ShardedBlockPartitioner;
 use aptos_crypto::HashValue;
 use aptos_executor_service::remote_executor_client::RemoteExecutorClient;
 use aptos_language_e2e_tests::{
@@ -12,15 +13,18 @@ use aptos_language_e2e_tests::{
     gas_costs::TXN_RESERVED,
 };
 use aptos_types::{
+    block_executor::partitioner::BlockExecutorTransactions,
     block_metadata::BlockMetadata,
     on_chain_config::{OnChainConfig, ValidatorSet},
-    transaction::Transaction,
+    transaction::{analyzed_transaction::AnalyzedTransaction, Transaction},
 };
 use aptos_vm::{
+    block_executor::BlockAptosVM,
     data_cache::AsMoveResolver,
     sharded_block_executor::{block_executor_client::LocalExecutorClient, ShardedBlockExecutor},
 };
 use criterion::{measurement::Measurement, BatchSize, Bencher};
+use once_cell::sync::Lazy;
 use proptest::{
     collection::vec,
     strategy::{Strategy, ValueTree},
@@ -28,6 +32,16 @@ use proptest::{
 };
 use std::{net::SocketAddr, sync::Arc, time::Instant};
 
+pub static RAYON_EXEC_POOL: Lazy> = Lazy::new(|| {
+    Arc::new(
+        rayon::ThreadPoolBuilder::new()
+            .num_threads(num_cpus::get())
+            .thread_name(|index| format!("par_exec_{}", index))
+            .build()
+            .unwrap(),
+    )
+});
+
 /// Benchmarking support for transactions.
 #[derive(Clone)]
 pub struct TransactionBencher {
@@ -177,8 +191,8 @@ struct TransactionBenchState {
     num_transactions: usize,
     strategy: S,
     account_universe: AccountUniverse,
-    parallel_block_executor: Arc>,
-    sequential_block_executor: Arc>,
+    parallel_block_executor: Option>>,
+    block_partitioner: Option,
     validator_set: ValidatorSet,
     state_view: Arc,
 }
@@ -228,21 +242,26 @@ where
         let universe = universe_gen.setup_gas_cost_stability(&mut executor);
 
         let state_view = Arc::new(executor.get_state_view().clone());
-        let parallel_block_executor =
-            if let Some(remote_executor_addresses) = remote_executor_addresses {
-                let remote_executor_clients = remote_executor_addresses
-                    .into_iter()
-                    .map(|addr| RemoteExecutorClient::new(addr, 10000))
-                    .collect::>();
-                Arc::new(ShardedBlockExecutor::new(remote_executor_clients))
-            } else {
-                let local_executor_client =
-                    LocalExecutorClient::create_local_clients(num_executor_shards, None);
-                Arc::new(ShardedBlockExecutor::new(local_executor_client))
-            };
-        let sequential_executor_client = LocalExecutorClient::create_local_clients(1, Some(1));
-        let sequential_block_executor =
-            Arc::new(ShardedBlockExecutor::new(sequential_executor_client));
+        let (parallel_block_executor, block_partitioner) = if num_executor_shards == 1 {
+            (None, None)
+        } else {
+            let parallel_block_executor =
+                if let Some(remote_executor_addresses) = remote_executor_addresses {
+                    let remote_executor_clients = remote_executor_addresses
+                        .into_iter()
+                        .map(|addr| RemoteExecutorClient::new(addr, 10000))
+                        .collect::>();
+                    Arc::new(ShardedBlockExecutor::new(remote_executor_clients))
+                } else {
+                    let local_executor_client =
+                        LocalExecutorClient::create_local_clients(num_executor_shards, None);
+                    Arc::new(ShardedBlockExecutor::new(local_executor_client))
+                };
+            (
+                Some(parallel_block_executor),
+                Some(ShardedBlockPartitioner::new(num_executor_shards)),
+            )
+        };
 
         let validator_set = ValidatorSet::fetch_config(
             &FakeExecutor::from_head_genesis()
@@ -256,7 +275,7 @@ where
             strategy,
             account_universe: universe,
             parallel_block_executor,
-            sequential_block_executor,
+            block_partitioner,
             validator_set,
             state_view,
         }
@@ -305,10 +324,7 @@ where
         // The output is ignored here since we're just testing transaction performance, not trying
         // to assert correctness.
         let txns = self.gen_transaction(false);
-        let executor = self.sequential_block_executor;
-        executor
-            .execute_block(self.state_view.clone(), txns, 1, None)
-            .expect("VM should not fail to start");
+        self.execute_benchmark_sequential(txns, None);
     }
 
     /// Executes this state in a single block.
@@ -316,29 +332,65 @@ where
         // The output is ignored here since we're just testing transaction performance, not trying
         // to assert correctness.
         let txns = self.gen_transaction(false);
-        let executor = self.parallel_block_executor.clone();
-        executor
-            .execute_block(self.state_view.clone(), txns, num_cpus::get(), None)
-            .expect("VM should not fail to start");
+        self.execute_benchmark_parallel(txns, num_cpus::get(), None);
+    }
+
+    fn execute_benchmark_sequential(
+        &self,
+        transactions: Vec,
+        maybe_block_gas_limit: Option,
+    ) -> usize {
+        let block_size = transactions.len();
+        let timer = Instant::now();
+        BlockAptosVM::execute_block(
+            Arc::clone(&RAYON_EXEC_POOL),
+            BlockExecutorTransactions::Unsharded(transactions),
+            self.state_view.as_ref(),
+            1,
+            maybe_block_gas_limit,
+        )
+        .expect("VM should not fail to start");
+        let exec_time = timer.elapsed().as_millis();
+
+        block_size * 1000 / exec_time as usize
     }
 
-    fn execute_benchmark(
+    fn execute_benchmark_parallel(
         &self,
         transactions: Vec,
-        block_executor: Arc>,
         concurrency_level_per_shard: usize,
         maybe_block_gas_limit: Option,
     ) -> usize {
         let block_size = transactions.len();
         let timer = Instant::now();
-        block_executor
-            .execute_block(
-                self.state_view.clone(),
-                transactions,
+        if let Some(parallel_block_executor) = self.parallel_block_executor.as_ref() {
+            // TODO(skedia) partition in a pipelined way and evaluate how expensive it is to
+            // parse the txns in a single thread.
+            let partitioned_block = self.block_partitioner.as_ref().unwrap().partition(
+                transactions
+                    .into_iter()
+                    .map(|txn| txn.into())
+                    .collect::>(),
+                1,
+            );
+            parallel_block_executor
+                .execute_block(
+                    self.state_view.clone(),
+                    partitioned_block,
+                    concurrency_level_per_shard,
+                    maybe_block_gas_limit,
+                )
+                .expect("VM should not fail to start");
+        } else {
+            BlockAptosVM::execute_block(
+                Arc::clone(&RAYON_EXEC_POOL),
+                BlockExecutorTransactions::Unsharded(transactions),
+                self.state_view.as_ref(),
                 concurrency_level_per_shard,
                 maybe_block_gas_limit,
             )
             .expect("VM should not fail to start");
+        }
         let exec_time = timer.elapsed().as_millis();
 
         block_size * 1000 / exec_time as usize
@@ -355,9 +407,8 @@ where
         let transactions = self.gen_transaction(no_conflict_txns);
         let par_tps = if run_par {
             println!("Parallel execution starts...");
-            let tps = self.execute_benchmark(
+            let tps = self.execute_benchmark_parallel(
                 transactions.clone(),
-                self.parallel_block_executor.clone(),
                 conurrency_level_per_shard,
                 maybe_block_gas_limit,
             );
@@ -368,12 +419,7 @@ where
         };
         let seq_tps = if run_seq {
             println!("Sequential execution starts...");
-            let tps = self.execute_benchmark(
-                transactions,
-                self.sequential_block_executor.clone(),
-                1,
-                maybe_block_gas_limit,
-            );
+            let tps = self.execute_benchmark_sequential(transactions, maybe_block_gas_limit);
             println!("Sequential execution finishes, TPS = {}", tps);
             tps
         } else {
diff --git a/aptos-move/aptos-vm/src/adapter_common.rs b/aptos-move/aptos-vm/src/adapter_common.rs
index 57799a323ceec..eb86a342c348b 100644
--- a/aptos-move/aptos-vm/src/adapter_common.rs
+++ b/aptos-move/aptos-vm/src/adapter_common.rs
@@ -80,7 +80,7 @@ pub(crate) trait VMAdapter {
 /// Transactions after signature checking:
 /// Waypoints and BlockPrologues are not signed and are unaffected by signature checking,
 /// but a user transaction or writeset transaction is transformed to a SignatureCheckedTransaction.
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub enum PreprocessedTransaction {
     UserTransaction(Box),
     WaypointWriteSet(WriteSetPayload),
diff --git a/aptos-move/aptos-vm/src/aptos_vm.rs b/aptos-move/aptos-vm/src/aptos_vm.rs
index c2a71c6f172bd..f38c96f75895b 100644
--- a/aptos-move/aptos-vm/src/aptos_vm.rs
+++ b/aptos-move/aptos-vm/src/aptos_vm.rs
@@ -30,7 +30,7 @@ use aptos_state_view::StateView;
 use aptos_types::{
     account_config,
     account_config::new_block_event_key,
-    block_executor::partitioner::ExecutableTransactions,
+    block_executor::partitioner::{BlockExecutorTransactions, SubBlocksForShard},
     block_metadata::BlockMetadata,
     fee_statement::FeeStatement,
     on_chain_config::{new_epoch_event_key, FeatureFlag, TimedFeatureOverride},
@@ -1519,7 +1519,7 @@ impl VMExecutor for AptosVM {
         let count = transactions.len();
         let ret = BlockAptosVM::execute_block(
             Arc::clone(&RAYON_EXEC_POOL),
-            ExecutableTransactions::Unsharded(transactions),
+            BlockExecutorTransactions::Unsharded(transactions),
             state_view,
             Self::get_concurrency_level(),
             maybe_block_gas_limit,
@@ -1533,7 +1533,7 @@ impl VMExecutor for AptosVM {
 
     fn execute_block_sharded(
         sharded_block_executor: &ShardedBlockExecutor,
-        transactions: Vec,
+        transactions: Vec>,
         state_view: Arc,
         maybe_block_gas_limit: Option,
     ) -> Result, VMStatus> {
@@ -1541,7 +1541,7 @@ impl VMExecutor for AptosVM {
         info!(
             log_context,
             "Executing block, transaction count: {}",
-            transactions.len()
+            transactions.iter().map(|s| s.num_txns()).sum::()
         );
 
         let count = transactions.len();
diff --git a/aptos-move/aptos-vm/src/block_executor/mod.rs b/aptos-move/aptos-vm/src/block_executor/mod.rs
index 4450be1bb87ac..abcb982f34459 100644
--- a/aptos-move/aptos-vm/src/block_executor/mod.rs
+++ b/aptos-move/aptos-vm/src/block_executor/mod.rs
@@ -25,7 +25,9 @@ use aptos_block_executor::{
 use aptos_infallible::Mutex;
 use aptos_state_view::{StateView, StateViewId};
 use aptos_types::{
-    block_executor::partitioner::{ExecutableTransactions, SubBlock, TransactionWithDependencies},
+    block_executor::partitioner::{
+        BlockExecutorTransactions, SubBlock, SubBlocksForShard, TransactionWithDependencies,
+    },
     executable::ExecutableTestType,
     fee_statement::FeeStatement,
     state_store::state_key::StateKey,
@@ -146,19 +148,21 @@ pub struct BlockAptosVM();
 
 impl BlockAptosVM {
     fn verify_transactions(
-        transactions: ExecutableTransactions,
-    ) -> ExecutableTransactions {
+        transactions: BlockExecutorTransactions,
+    ) -> BlockExecutorTransactions {
         match transactions {
-            ExecutableTransactions::Unsharded(transactions) => {
+            BlockExecutorTransactions::Unsharded(transactions) => {
                 let signature_verified_txns = transactions
                     .into_par_iter()
                     .with_min_len(25)
                     .map(preprocess_transaction::)
                     .collect();
-                ExecutableTransactions::Unsharded(signature_verified_txns)
+                BlockExecutorTransactions::Unsharded(signature_verified_txns)
             },
-            ExecutableTransactions::Sharded(sub_blocks) => {
-                let signature_verified_block = sub_blocks
+            BlockExecutorTransactions::Sharded(sub_blocks) => {
+                let shard_id = sub_blocks.shard_id;
+                let signature_verified_sub_blocks = sub_blocks
+                    .into_sub_blocks()
                     .into_par_iter()
                     .map(|sub_block| {
                         let start_index = sub_block.start_index;
@@ -181,14 +185,18 @@ impl BlockAptosVM {
                         SubBlock::new(start_index, verified_txns)
                     })
                     .collect();
-                ExecutableTransactions::Sharded(signature_verified_block)
+
+                BlockExecutorTransactions::Sharded(SubBlocksForShard::new(
+                    shard_id,
+                    signature_verified_sub_blocks,
+                ))
             },
         }
     }
 
     pub fn execute_block(
         executor_thread_pool: Arc,
-        transactions: ExecutableTransactions,
+        transactions: BlockExecutorTransactions,
         state_view: &S,
         concurrency_level: usize,
         maybe_block_gas_limit: Option,
@@ -204,7 +212,7 @@ impl BlockAptosVM {
             executor_thread_pool.install(|| Self::verify_transactions(transactions));
         drop(signature_verification_timer);
 
-        let num_txns = signature_verified_block.num_transactions();
+        let num_txns = signature_verified_block.num_txns();
         if state_view.id() != StateViewId::Miscellaneous {
             // Speculation is disabled in Miscellaneous context, which is used by testing and
             // can even lead to concurrent execute_block invocations, leading to errors on flush.
diff --git a/aptos-move/aptos-vm/src/lib.rs b/aptos-move/aptos-vm/src/lib.rs
index 54125625acedb..67fed2abd7ddc 100644
--- a/aptos-move/aptos-vm/src/lib.rs
+++ b/aptos-move/aptos-vm/src/lib.rs
@@ -125,6 +125,7 @@ pub use crate::aptos_vm::AptosVM;
 use crate::sharded_block_executor::ShardedBlockExecutor;
 use aptos_state_view::StateView;
 use aptos_types::{
+    block_executor::partitioner::SubBlocksForShard,
     transaction::{SignedTransaction, Transaction, TransactionOutput, VMValidatorResult},
     vm_status::VMStatus,
 };
@@ -158,7 +159,7 @@ pub trait VMExecutor: Send + Sync {
     /// Executes a block of transactions using a sharded block executor and returns the results.
     fn execute_block_sharded(
         sharded_block_executor: &ShardedBlockExecutor,
-        transactions: Vec,
+        block: Vec>,
         state_view: Arc,
         maybe_block_gas_limit: Option,
     ) -> Result, VMStatus>;
diff --git a/aptos-move/aptos-vm/src/sharded_block_executor/block_executor_client.rs b/aptos-move/aptos-vm/src/sharded_block_executor/block_executor_client.rs
index d0989145637ad..aa31d2dc0f309 100644
--- a/aptos-move/aptos-vm/src/sharded_block_executor/block_executor_client.rs
+++ b/aptos-move/aptos-vm/src/sharded_block_executor/block_executor_client.rs
@@ -3,7 +3,7 @@
 use crate::block_executor::BlockAptosVM;
 use aptos_state_view::StateView;
 use aptos_types::{
-    block_executor::partitioner::ExecutableTransactions,
+    block_executor::partitioner::{BlockExecutorTransactions, SubBlocksForShard},
     transaction::{Transaction, TransactionOutput},
 };
 use move_core_types::vm_status::VMStatus;
@@ -12,7 +12,7 @@ use std::sync::Arc;
 pub trait BlockExecutorClient {
     fn execute_block(
         &self,
-        transactions: Vec,
+        transactions: SubBlocksForShard,
         state_view: &S,
         concurrency_level: usize,
         maybe_block_gas_limit: Option,
@@ -22,15 +22,14 @@ pub trait BlockExecutorClient {
 impl BlockExecutorClient for LocalExecutorClient {
     fn execute_block(
         &self,
-        transactions: Vec,
+        sub_blocks: SubBlocksForShard,
         state_view: &S,
         concurrency_level: usize,
         maybe_block_gas_limit: Option,
     ) -> Result, VMStatus> {
         BlockAptosVM::execute_block(
             self.executor_thread_pool.clone(),
-            // TODO: (skedia) Change this to sharded transactions
-            ExecutableTransactions::Unsharded(transactions),
+            BlockExecutorTransactions::Sharded(sub_blocks),
             state_view,
             concurrency_level,
             maybe_block_gas_limit,
diff --git a/aptos-move/aptos-vm/src/sharded_block_executor/executor_shard.rs b/aptos-move/aptos-vm/src/sharded_block_executor/executor_shard.rs
index db525cadacb4a..b70fc4ec24967 100644
--- a/aptos-move/aptos-vm/src/sharded_block_executor/executor_shard.rs
+++ b/aptos-move/aptos-vm/src/sharded_block_executor/executor_shard.rs
@@ -46,7 +46,7 @@ impl ExecutorShard
         loop {
             let command = self.command_rx.recv().unwrap();
             match command {
-                ExecutorShardCommand::ExecuteBlock(
+                ExecutorShardCommand::ExecuteSubBlocks(
                     state_view,
                     transactions,
                     concurrency_level_per_shard,
@@ -55,7 +55,7 @@ impl ExecutorShard
                     trace!(
                         "Shard {} received ExecuteBlock command of block size {} ",
                         self.shard_id,
-                        transactions.len()
+                        transactions.num_txns()
                     );
                     let ret = self.executor_client.execute_block(
                         transactions,
diff --git a/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs b/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs
index f2fcf476abb99..14225c6806fa0 100644
--- a/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs
+++ b/aptos-move/aptos-vm/src/sharded_block_executor/mod.rs
@@ -3,10 +3,12 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::sharded_block_executor::{counters::NUM_EXECUTOR_SHARDS, executor_shard::ExecutorShard};
-use aptos_block_partitioner::{BlockPartitioner, UniformPartitioner};
 use aptos_logger::{error, info, trace};
 use aptos_state_view::StateView;
-use aptos_types::transaction::{Transaction, TransactionOutput};
+use aptos_types::{
+    block_executor::partitioner::SubBlocksForShard,
+    transaction::{Transaction, TransactionOutput},
+};
 use block_executor_client::BlockExecutorClient;
 use move_core_types::vm_status::VMStatus;
 use std::{
@@ -25,7 +27,6 @@ mod executor_shard;
 /// A wrapper around sharded block executors that manages multiple shards and aggregates the results.
 pub struct ShardedBlockExecutor {
     num_executor_shards: usize,
-    partitioner: Arc,
     command_txs: Vec>>,
     shard_threads: Vec>,
     result_rxs: Vec, VMStatus>>>,
@@ -33,7 +34,7 @@ pub struct ShardedBlockExecutor {
 }
 
 pub enum ExecutorShardCommand {
-    ExecuteBlock(Arc, Vec, usize, Option),
+    ExecuteSubBlocks(Arc, SubBlocksForShard, usize, Option),
     Stop,
 }
 
@@ -62,7 +63,6 @@ impl ShardedBlockExecutor {
         );
         Self {
             num_executor_shards,
-            partitioner: Arc::new(UniformPartitioner {}),
             command_txs,
             shard_threads: shard_join_handles,
             result_rxs,
@@ -75,20 +75,22 @@ impl ShardedBlockExecutor {
     pub fn execute_block(
         &self,
         state_view: Arc,
-        block: Vec,
+        block: Vec>,
         concurrency_level_per_shard: usize,
         maybe_block_gas_limit: Option,
     ) -> Result, VMStatus> {
         NUM_EXECUTOR_SHARDS.set(self.num_executor_shards as i64);
-        let block_partitions = self.partitioner.partition(block, self.num_executor_shards);
-        // Number of partitions might be smaller than the number of executor shards in case of
-        // block size is smaller than number of executor shards.
-        let num_partitions = block_partitions.len();
-        for (i, transactions) in block_partitions.into_iter().enumerate() {
+        assert_eq!(
+            self.num_executor_shards,
+            block.len(),
+            "Block must be partitioned into {} sub-blocks",
+            self.num_executor_shards
+        );
+        for (i, sub_blocks_for_shard) in block.into_iter().enumerate() {
             self.command_txs[i]
-                .send(ExecutorShardCommand::ExecuteBlock(
+                .send(ExecutorShardCommand::ExecuteSubBlocks(
                     state_view.clone(),
-                    transactions,
+                    sub_blocks_for_shard,
                     concurrency_level_per_shard,
                     maybe_block_gas_limit,
                 ))
@@ -97,7 +99,7 @@ impl ShardedBlockExecutor {
         // wait for all remote executors to send the result back and append them in order by shard id
         let mut aggregated_results = vec![];
         trace!("ShardedBlockExecutor Waiting for results");
-        for i in 0..num_partitions {
+        for i in 0..self.num_executor_shards {
             let result = self.result_rxs[i].recv().unwrap();
             aggregated_results.extend(result?);
         }
diff --git a/aptos-move/block-executor/src/executor.rs b/aptos-move/block-executor/src/executor.rs
index 2faf75efbd20c..6f2ad1148fb12 100644
--- a/aptos-move/block-executor/src/executor.rs
+++ b/aptos-move/block-executor/src/executor.rs
@@ -23,7 +23,7 @@ use aptos_mvhashmap::{
 };
 use aptos_state_view::TStateView;
 use aptos_types::{
-    block_executor::partitioner::ExecutableTransactions, executable::Executable,
+    block_executor::partitioner::BlockExecutorTransactions, executable::Executable,
     fee_statement::FeeStatement, write_set::WriteOp,
 };
 use aptos_vm_logging::{clear_speculative_txn_logs, init_speculative_logs};
@@ -582,7 +582,7 @@ where
     pub(crate) fn execute_transactions_parallel(
         &self,
         executor_initial_arguments: E::Argument,
-        signature_verified_block: &ExecutableTransactions,
+        signature_verified_block: &Vec,
         base_view: &S,
     ) -> Result, E::Error> {
         let _timer = PARALLEL_EXECUTION_SECONDS.start_timer();
@@ -592,13 +592,6 @@ where
         // w. concurrency_level = 1 for some reason.
         assert!(self.concurrency_level > 1, "Must use sequential execution");
 
-        let signature_verified_block = match signature_verified_block {
-            ExecutableTransactions::Unsharded(txns) => txns,
-            ExecutableTransactions::Sharded(_) => {
-                unimplemented!("Sharded execution is not supported yet")
-            },
-        };
-
         let versioned_cache = MVHashMap::new();
 
         if signature_verified_block.is_empty() {
@@ -687,16 +680,9 @@ where
     pub(crate) fn execute_transactions_sequential(
         &self,
         executor_arguments: E::Argument,
-        signature_verified_block: &ExecutableTransactions,
+        signature_verified_block: &Vec,
         base_view: &S,
     ) -> Result, E::Error> {
-        let signature_verified_block = match signature_verified_block {
-            ExecutableTransactions::Unsharded(txns) => txns,
-            ExecutableTransactions::Sharded(_) => {
-                unimplemented!("Sharded execution is not supported yet")
-            },
-        };
-
         let num_txns = signature_verified_block.len();
         let executor = E::init(executor_arguments);
         let data_map = UnsyncMap::new();
@@ -771,19 +757,20 @@ where
     pub fn execute_block(
         &self,
         executor_arguments: E::Argument,
-        signature_verified_block: ExecutableTransactions,
+        signature_verified_block: BlockExecutorTransactions,
         base_view: &S,
     ) -> Result, E::Error> {
+        let signature_verified_txns = signature_verified_block.into_txns();
         let mut ret = if self.concurrency_level > 1 {
             self.execute_transactions_parallel(
                 executor_arguments,
-                &signature_verified_block,
+                &signature_verified_txns,
                 base_view,
             )
         } else {
             self.execute_transactions_sequential(
                 executor_arguments,
-                &signature_verified_block,
+                &signature_verified_txns,
                 base_view,
             )
         };
@@ -793,18 +780,18 @@ where
 
             // All logs from the parallel execution should be cleared and not reported.
             // Clear by re-initializing the speculative logs.
-            init_speculative_logs(signature_verified_block.num_transactions());
+            init_speculative_logs(signature_verified_txns.len());
 
             ret = self.execute_transactions_sequential(
                 executor_arguments,
-                &signature_verified_block,
+                &signature_verified_txns,
                 base_view,
             )
         }
 
         self.executor_thread_pool.spawn(move || {
             // Explicit async drops.
-            drop(signature_verified_block);
+            drop(signature_verified_txns);
         });
 
         ret
diff --git a/aptos-move/block-executor/src/proptest_types/bencher.rs b/aptos-move/block-executor/src/proptest_types/bencher.rs
index d3ffb13905e59..87bb442323e64 100644
--- a/aptos-move/block-executor/src/proptest_types/bencher.rs
+++ b/aptos-move/block-executor/src/proptest_types/bencher.rs
@@ -9,9 +9,7 @@ use crate::{
         TransactionGenParams, ValueType,
     },
 };
-use aptos_types::{
-    block_executor::partitioner::ExecutableTransactions, executable::ExecutableTestType,
-};
+use aptos_types::executable::ExecutableTestType;
 use criterion::{BatchSize, Bencher as CBencher};
 use num_cpus;
 use proptest::{
@@ -36,7 +34,7 @@ pub(crate) struct BencherState<
 > where
     Vec: From,
 {
-    transactions: ExecutableTransactions, ValueType>>,
+    transactions: Vec, ValueType>>,
     expected_output: ExpectedOutput>,
 }
 
@@ -106,7 +104,7 @@ where
         let expected_output = ExpectedOutput::generate_baseline(&transactions, None, None);
 
         Self {
-            transactions: ExecutableTransactions::Unsharded(transactions),
+            transactions,
             expected_output,
         }
     }
diff --git a/aptos-move/block-executor/src/proptest_types/tests.rs b/aptos-move/block-executor/src/proptest_types/tests.rs
index da4f45966c529..73e65ff53423a 100644
--- a/aptos-move/block-executor/src/proptest_types/tests.rs
+++ b/aptos-move/block-executor/src/proptest_types/tests.rs
@@ -10,9 +10,7 @@ use crate::{
         TransactionGenParams, ValueType,
     },
 };
-use aptos_types::{
-    block_executor::partitioner::ExecutableTransactions, executable::ExecutableTestType,
-};
+use aptos_types::executable::ExecutableTestType;
 use claims::assert_ok;
 use num_cpus;
 use proptest::{
@@ -62,8 +60,6 @@ fn run_transactions(
             .unwrap(),
     );
 
-    let executable_txns = ExecutableTransactions::Unsharded(transactions);
-
     for _ in 0..num_repeat {
         let output = BlockExecutor::<
             Transaction, ValueType>,
@@ -75,18 +71,15 @@ fn run_transactions(
             executor_thread_pool.clone(),
             maybe_block_gas_limit,
         )
-        .execute_transactions_parallel((), &executable_txns, &data_view);
+        .execute_transactions_parallel((), &transactions, &data_view);
 
         if module_access.0 && module_access.1 {
             assert_eq!(output.unwrap_err(), Error::ModulePathReadWrite);
             continue;
         }
 
-        let baseline = ExpectedOutput::generate_baseline(
-            executable_txns.get_unsharded_transactions().unwrap(),
-            None,
-            maybe_block_gas_limit,
-        );
+        let baseline =
+            ExpectedOutput::generate_baseline(&transactions, None, maybe_block_gas_limit);
         baseline.assert_output(&output);
     }
 }
@@ -191,8 +184,6 @@ fn deltas_writes_mixed_with_block_gas_limit(num_txns: usize, maybe_block_gas_lim
         .map(|txn_gen| txn_gen.materialize_with_deltas(&universe, 15, false))
         .collect();
 
-    let executable_txns = ExecutableTransactions::Unsharded(transactions);
-
     let data_view = DeltaDataView::, ValueType<[u8; 32]>> {
         phantom: PhantomData,
     };
@@ -215,13 +206,10 @@ fn deltas_writes_mixed_with_block_gas_limit(num_txns: usize, maybe_block_gas_lim
             executor_thread_pool.clone(),
             maybe_block_gas_limit,
         )
-        .execute_transactions_parallel((), &executable_txns, &data_view);
+        .execute_transactions_parallel((), &transactions, &data_view);
 
-        let baseline = ExpectedOutput::generate_baseline(
-            executable_txns.get_unsharded_transactions().unwrap(),
-            None,
-            maybe_block_gas_limit,
-        );
+        let baseline =
+            ExpectedOutput::generate_baseline(&transactions, None, maybe_block_gas_limit);
         baseline.assert_output(&output);
     }
 }
@@ -251,8 +239,6 @@ fn deltas_resolver_with_block_gas_limit(num_txns: usize, maybe_block_gas_limit:
         .map(|txn_gen| txn_gen.materialize_with_deltas(&universe, 15, false))
         .collect();
 
-    let executable_txns = ExecutableTransactions::Unsharded(transactions);
-
     let executor_thread_pool = Arc::new(
         rayon::ThreadPoolBuilder::new()
             .num_threads(num_cpus::get())
@@ -271,7 +257,7 @@ fn deltas_resolver_with_block_gas_limit(num_txns: usize, maybe_block_gas_limit:
             executor_thread_pool.clone(),
             maybe_block_gas_limit,
         )
-        .execute_transactions_parallel((), &executable_txns, &data_view);
+        .execute_transactions_parallel((), &transactions, &data_view);
 
         let delta_writes = output
             .as_ref()
@@ -281,7 +267,7 @@ fn deltas_resolver_with_block_gas_limit(num_txns: usize, maybe_block_gas_limit:
             .collect();
 
         let baseline = ExpectedOutput::generate_baseline(
-            executable_txns.get_unsharded_transactions().unwrap(),
+            &transactions,
             Some(delta_writes),
             maybe_block_gas_limit,
         );
@@ -427,8 +413,6 @@ fn publishing_fixed_params_with_block_gas_limit(
         phantom: PhantomData,
     };
 
-    let executable_txns = ExecutableTransactions::Unsharded(transactions.clone());
-
     let executor_thread_pool = Arc::new(
         rayon::ThreadPoolBuilder::new()
             .num_threads(num_cpus::get())
@@ -443,7 +427,7 @@ fn publishing_fixed_params_with_block_gas_limit(
         DeltaDataView, ValueType<[u8; 32]>>,
         ExecutableTestType,
     >::new(num_cpus::get(), executor_thread_pool, maybe_block_gas_limit)
-    .execute_transactions_parallel((), &executable_txns, &data_view);
+    .execute_transactions_parallel((), &transactions, &data_view);
     assert_ok!(output);
 
     // Adjust the reads of txn indices[2] to contain module read to key 42.
@@ -480,8 +464,6 @@ fn publishing_fixed_params_with_block_gas_limit(
             .unwrap(),
     );
 
-    let executable_txns = ExecutableTransactions::Unsharded(transactions);
-
     for _ in 0..200 {
         let output = BlockExecutor::<
             Transaction, ValueType<[u8; 32]>>,
@@ -493,7 +475,7 @@ fn publishing_fixed_params_with_block_gas_limit(
             executor_thread_pool.clone(),
             Some(max(w_index, r_index) as u64 + 1),
         ) // Ensure enough gas limit to commit the module txns
-        .execute_transactions_parallel((), &executable_txns, &data_view);
+        .execute_transactions_parallel((), &transactions, &data_view);
 
         assert_eq!(output.unwrap_err(), Error::ModulePathReadWrite);
     }
diff --git a/aptos-move/block-executor/src/task.rs b/aptos-move/block-executor/src/task.rs
index 63c0460212bca..a0ee96d32bc85 100644
--- a/aptos-move/block-executor/src/task.rs
+++ b/aptos-move/block-executor/src/task.rs
@@ -27,9 +27,9 @@ pub enum ExecutionStatus {
 
 /// Trait that defines a transaction type that can be executed by the block executor. A transaction
 /// transaction will write to a key value storage as their side effect.
-pub trait Transaction: Sync + Send + 'static {
+pub trait Transaction: Sync + Send + Clone + 'static {
     type Key: PartialOrd + Ord + Send + Sync + Clone + Hash + Eq + ModulePath + Debug;
-    type Value: Send + Sync + TransactionWrite;
+    type Value: Send + Sync + Clone + TransactionWrite;
 }
 
 /// Inference result of a transaction.
diff --git a/aptos-move/block-executor/src/unit_tests/mod.rs b/aptos-move/block-executor/src/unit_tests/mod.rs
index fc69a0bbd986e..443ba3188d5d4 100644
--- a/aptos-move/block-executor/src/unit_tests/mod.rs
+++ b/aptos-move/block-executor/src/unit_tests/mod.rs
@@ -10,7 +10,6 @@ use crate::{
 use aptos_aggregator::delta_change_set::{delta_add, delta_sub, DeltaOp, DeltaUpdate};
 use aptos_mvhashmap::types::TxnIndex;
 use aptos_types::{
-    block_executor::partitioner::ExecutableTransactions,
     executable::{ExecutableTestType, ModulePath},
     write_set::TransactionWrite,
 };
@@ -41,23 +40,15 @@ where
             .unwrap(),
     );
 
-    let executable_transactions = ExecutableTransactions::Unsharded(transactions);
-
     let output = BlockExecutor::<
         Transaction,
         Task,
         DeltaDataView,
         ExecutableTestType,
     >::new(num_cpus::get(), executor_thread_pool, None)
-    .execute_transactions_parallel((), &executable_transactions, &data_view);
+    .execute_transactions_parallel((), &transactions, &data_view);
 
-    let baseline = ExpectedOutput::generate_baseline(
-        executable_transactions
-            .get_unsharded_transactions()
-            .unwrap(),
-        None,
-        None,
-    );
+    let baseline = ExpectedOutput::generate_baseline(&transactions, None, None);
     baseline.assert_output(&output);
 }
 
diff --git a/aptos-move/e2e-tests/src/executor.rs b/aptos-move/e2e-tests/src/executor.rs
index a055b52243925..fac4a714fcc17 100644
--- a/aptos-move/e2e-tests/src/executor.rs
+++ b/aptos-move/e2e-tests/src/executor.rs
@@ -28,7 +28,7 @@ use aptos_types::{
         new_block_event_key, AccountResource, CoinInfoResource, CoinStoreResource, NewBlockEvent,
         CORE_CODE_ADDRESS,
     },
-    block_executor::partitioner::ExecutableTransactions,
+    block_executor::partitioner::BlockExecutorTransactions,
     block_metadata::BlockMetadata,
     chain_id::ChainId,
     on_chain_config::{
@@ -417,7 +417,7 @@ impl FakeExecutor {
     ) -> Result, VMStatus> {
         BlockAptosVM::execute_block(
             self.executor_thread_pool.clone(),
-            ExecutableTransactions::Unsharded(txn_block),
+            BlockExecutorTransactions::Unsharded(txn_block),
             &self.data_store,
             usize::min(4, num_cpus::get()),
             None,
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/conflict_detector.rs b/execution/block-partitioner/src/sharded_block_partitioner/conflict_detector.rs
index cd42de9e8a939..e760b77d4fe85 100644
--- a/execution/block-partitioner/src/sharded_block_partitioner/conflict_detector.rs
+++ b/execution/block-partitioner/src/sharded_block_partitioner/conflict_detector.rs
@@ -6,7 +6,10 @@ use aptos_types::{
         CrossShardDependencies, ShardId, SubBlock, TransactionWithDependencies, TxnIdxWithShardId,
         TxnIndex,
     },
-    transaction::analyzed_transaction::{AnalyzedTransaction, StorageLocation},
+    transaction::{
+        analyzed_transaction::{AnalyzedTransaction, StorageLocation},
+        Transaction,
+    },
 };
 use std::{
     collections::hash_map::DefaultHasher,
@@ -114,7 +117,7 @@ impl CrossShardConflictDetector {
         current_round_rw_set_with_index: Arc>,
         prev_round_rw_set_with_index: Arc>,
         index_offset: TxnIndex,
-    ) -> (SubBlock, Vec) {
+    ) -> (SubBlock, Vec) {
         let mut frozen_txns = Vec::new();
         let mut cross_shard_dependencies = Vec::new();
         for txn in txns.into_iter() {
@@ -124,7 +127,7 @@ impl CrossShardConflictDetector {
                 prev_round_rw_set_with_index.clone(),
             );
             cross_shard_dependencies.push(dependency.clone());
-            frozen_txns.push(TransactionWithDependencies::new(txn, dependency));
+            frozen_txns.push(TransactionWithDependencies::new(txn.into_txn(), dependency));
         }
         (
             SubBlock::new(index_offset, frozen_txns),
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/dependent_edges.rs b/execution/block-partitioner/src/sharded_block_partitioner/dependent_edges.rs
index 2b8240b4cea82..01f283cdce4d1 100644
--- a/execution/block-partitioner/src/sharded_block_partitioner/dependent_edges.rs
+++ b/execution/block-partitioner/src/sharded_block_partitioner/dependent_edges.rs
@@ -9,7 +9,7 @@ use aptos_types::{
         CrossShardDependencies, CrossShardEdges, ShardId, SubBlocksForShard, TxnIdxWithShardId,
         TxnIndex,
     },
-    transaction::analyzed_transaction::AnalyzedTransaction,
+    transaction::Transaction,
 };
 use itertools::Itertools;
 use std::{collections::HashMap, sync::Arc};
@@ -17,7 +17,7 @@ use std::{collections::HashMap, sync::Arc};
 pub struct DependentEdgeCreator {
     shard_id: ShardId,
     cross_shard_client: Arc,
-    froze_sub_blocks: SubBlocksForShard,
+    froze_sub_blocks: SubBlocksForShard,
     num_shards: usize,
 }
 
@@ -33,7 +33,7 @@ impl DependentEdgeCreator {
     pub fn new(
         shard_id: ShardId,
         cross_shard_client: Arc,
-        froze_sub_blocks: SubBlocksForShard,
+        froze_sub_blocks: SubBlocksForShard,
         num_shards: usize,
     ) -> Self {
         Self {
@@ -156,7 +156,7 @@ impl DependentEdgeCreator {
         }
     }
 
-    pub fn into_frozen_sub_blocks(self) -> SubBlocksForShard {
+    pub fn into_frozen_sub_blocks(self) -> SubBlocksForShard {
         self.froze_sub_blocks
     }
 }
@@ -177,6 +177,7 @@ mod tests {
         },
         transaction::analyzed_transaction::StorageLocation,
     };
+    use itertools::Itertools;
     use std::sync::Arc;
 
     #[test]
@@ -244,7 +245,18 @@ mod tests {
         });
 
         let mut sub_blocks = SubBlocksForShard::empty(shard_id);
-        let sub_block = SubBlock::new(start_index, transactions_with_deps.clone());
+        let sub_block = SubBlock::new(
+            start_index,
+            transactions_with_deps
+                .iter()
+                .map(|txn_with_deps| {
+                    TransactionWithDependencies::new(
+                        txn_with_deps.txn.transaction().clone(),
+                        txn_with_deps.cross_shard_dependencies.clone(),
+                    )
+                })
+                .collect_vec(),
+        );
         sub_blocks.add_sub_block(sub_block);
 
         let mut dependent_edge_creator =
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/messages.rs b/execution/block-partitioner/src/sharded_block_partitioner/messages.rs
index 7336855022947..c4f0b60a0a982 100644
--- a/execution/block-partitioner/src/sharded_block_partitioner/messages.rs
+++ b/execution/block-partitioner/src/sharded_block_partitioner/messages.rs
@@ -3,7 +3,7 @@
 use crate::sharded_block_partitioner::dependency_analysis::WriteSetWithTxnIndex;
 use aptos_types::{
     block_executor::partitioner::{SubBlocksForShard, TxnIndex},
-    transaction::analyzed_transaction::AnalyzedTransaction,
+    transaction::{analyzed_transaction::AnalyzedTransaction, Transaction},
 };
 use std::sync::Arc;
 
@@ -14,7 +14,7 @@ pub struct DiscardCrossShardDep {
     pub current_round_start_index: TxnIndex,
     // This is the frozen sub block for the current shard and is passed because we want to modify
     // it to add dependency back edges.
-    pub frozen_sub_blocks: SubBlocksForShard,
+    pub frozen_sub_blocks: SubBlocksForShard,
 }
 
 impl DiscardCrossShardDep {
@@ -22,7 +22,7 @@ impl DiscardCrossShardDep {
         transactions: Vec,
         prev_rounds_write_set_with_index: Arc>,
         current_round_start_index: TxnIndex,
-        frozen_sub_blocks: SubBlocksForShard,
+        frozen_sub_blocks: SubBlocksForShard,
     ) -> Self {
         Self {
             transactions,
@@ -38,7 +38,7 @@ pub struct AddWithCrossShardDep {
     pub index_offset: TxnIndex,
     // The frozen dependencies in previous chunks.
     pub prev_rounds_write_set_with_index: Arc>,
-    pub frozen_sub_blocks: SubBlocksForShard,
+    pub frozen_sub_blocks: SubBlocksForShard,
 }
 
 impl AddWithCrossShardDep {
@@ -46,7 +46,7 @@ impl AddWithCrossShardDep {
         transactions: Vec,
         index_offset: TxnIndex,
         prev_rounds_write_set_with_index: Arc>,
-        frozen_sub_blocks: SubBlocksForShard,
+        frozen_sub_blocks: SubBlocksForShard,
     ) -> Self {
         Self {
             transactions,
@@ -58,14 +58,14 @@ impl AddWithCrossShardDep {
 }
 
 pub struct PartitioningResp {
-    pub frozen_sub_blocks: SubBlocksForShard,
+    pub frozen_sub_blocks: SubBlocksForShard,
     pub write_set_with_index: WriteSetWithTxnIndex,
     pub discarded_txns: Vec,
 }
 
 impl PartitioningResp {
     pub fn new(
-        frozen_sub_blocks: SubBlocksForShard,
+        frozen_sub_blocks: SubBlocksForShard,
         write_set_with_index: WriteSetWithTxnIndex,
         discarded_txns: Vec,
     ) -> Self {
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/mod.rs b/execution/block-partitioner/src/sharded_block_partitioner/mod.rs
index 9951a476535b7..fe54d2de4d3ab 100644
--- a/execution/block-partitioner/src/sharded_block_partitioner/mod.rs
+++ b/execution/block-partitioner/src/sharded_block_partitioner/mod.rs
@@ -14,7 +14,7 @@ use crate::sharded_block_partitioner::{
 use aptos_logger::{error, info};
 use aptos_types::{
     block_executor::partitioner::{ShardId, SubBlocksForShard, TxnIndex},
-    transaction::analyzed_transaction::AnalyzedTransaction,
+    transaction::{analyzed_transaction::AnalyzedTransaction, Transaction},
 };
 use itertools::Itertools;
 use std::{
@@ -206,7 +206,7 @@ impl ShardedBlockPartitioner {
     fn collect_partition_block_response(
         &self,
     ) -> (
-        Vec>,
+        Vec>,
         Vec,
         Vec>,
     ) {
@@ -234,10 +234,10 @@ impl ShardedBlockPartitioner {
         &self,
         txns_to_partition: Vec>,
         current_round_start_index: TxnIndex,
-        frozen_sub_blocks: Vec>,
+        frozen_sub_blocks: Vec>,
         frozen_write_set_with_index: Arc>,
     ) -> (
-        Vec>,
+        Vec>,
         Vec,
         Vec>,
     ) {
@@ -261,10 +261,10 @@ impl ShardedBlockPartitioner {
         &self,
         index_offset: usize,
         remaining_txns_vec: Vec>,
-        frozen_sub_blocks_by_shard: Vec>,
+        frozen_sub_blocks_by_shard: Vec>,
         frozen_write_set_with_index: Arc>,
     ) -> (
-        Vec>,
+        Vec>,
         Vec,
         Vec>,
     ) {
@@ -295,7 +295,7 @@ impl ShardedBlockPartitioner {
         &self,
         transactions: Vec,
         num_partitioning_round: usize,
-    ) -> Vec> {
+    ) -> Vec> {
         let total_txns = transactions.len();
         if total_txns == 0 {
             return vec![];
@@ -305,7 +305,7 @@ impl ShardedBlockPartitioner {
         let mut txns_to_partition = self.partition_by_senders(transactions);
         let mut frozen_write_set_with_index = Arc::new(Vec::new());
         let mut current_round_start_index = 0;
-        let mut frozen_sub_blocks: Vec> = vec![];
+        let mut frozen_sub_blocks: Vec> = vec![];
         for shard_id in 0..self.num_shards {
             frozen_sub_blocks.push(SubBlocksForShard::empty(shard_id))
         }
@@ -402,15 +402,16 @@ mod tests {
             generate_test_account, generate_test_account_for_address, TestAccount,
         },
     };
+    use aptos_crypto::hash::CryptoHash;
     use aptos_types::{
         block_executor::partitioner::{SubBlock, TxnIdxWithShardId},
-        transaction::analyzed_transaction::AnalyzedTransaction,
+        transaction::{analyzed_transaction::AnalyzedTransaction, Transaction},
     };
     use move_core_types::account_address::AccountAddress;
     use rand::{rngs::OsRng, Rng};
     use std::collections::HashMap;
 
-    fn verify_no_cross_shard_dependency(sub_blocks_for_shards: Vec>) {
+    fn verify_no_cross_shard_dependency(sub_blocks_for_shards: Vec>) {
         for sub_blocks in sub_blocks_for_shards {
             for txn in sub_blocks.iter() {
                 assert_eq!(txn.cross_shard_dependencies().num_required_edges(), 0);
@@ -445,7 +446,7 @@ mod tests {
         // Verify that the transactions are in the same order as the original transactions and cross shard
         // dependencies are empty.
         for (i, txn) in sub_blocks[0].iter().enumerate() {
-            assert_eq!(txn.txn(), &transactions[i]);
+            assert_eq!(txn.txn(), transactions[i].transaction());
             assert_eq!(txn.cross_shard_dependencies().num_required_edges(), 0);
         }
     }
@@ -469,7 +470,7 @@ mod tests {
         for sub_blocks_for_shard in partitioned_txns.into_iter() {
             assert_eq!(sub_blocks_for_shard.num_txns(), num_txns / num_shards);
             for txn in sub_blocks_for_shard.iter() {
-                assert_eq!(txn.txn(), &transactions[current_index]);
+                assert_eq!(txn.txn(), transactions[current_index].transaction());
                 assert_eq!(txn.cross_shard_dependencies().num_required_edges(), 0);
                 current_index += 1;
             }
@@ -522,7 +523,7 @@ mod tests {
 
         // verify that all transactions from the sender end up in shard 0
         for (txn_from_sender, txn) in txns_from_sender.iter().zip(sub_blocks[0].iter().skip(1)) {
-            assert_eq!(txn.txn(), txn_from_sender);
+            assert_eq!(txn.txn(), txn_from_sender.transaction());
         }
         verify_no_cross_shard_dependency(
             sub_blocks
@@ -605,8 +606,8 @@ mod tests {
                 .unwrap()
                 .iter()
                 .map(|x| x.txn.clone())
-                .collect::>(),
-            vec![txn0, txn1, txn2]
+                .collect::>(),
+            vec![txn0.into_txn(), txn1.into_txn(), txn2.into_txn()]
         );
         assert_eq!(
             partitioned_sub_blocks[1]
@@ -614,8 +615,13 @@ mod tests {
                 .unwrap()
                 .iter()
                 .map(|x| x.txn.clone())
-                .collect::>(),
-            vec![txn3, txn4, txn5, txn8]
+                .collect::>(),
+            vec![
+                txn3.into_txn(),
+                txn4.into_txn(),
+                txn5.into_txn(),
+                txn8.into_txn()
+            ]
         );
         //
         // // Rest of the transactions will be added in round 2 along with their dependencies
@@ -647,8 +653,8 @@ mod tests {
                 .unwrap()
                 .iter()
                 .map(|x| x.txn.clone())
-                .collect::>(),
-            vec![txn6, txn7]
+                .collect::>(),
+            vec![txn6.into_txn(), txn7.into_txn()]
         );
 
         // Verify transaction dependencies
@@ -721,6 +727,7 @@ mod tests {
         }
         let num_txns = rng.gen_range(1, max_txns);
         let mut transactions = Vec::new();
+        let mut txns_by_hash = HashMap::new();
         let num_shards = rng.gen_range(1, max_num_shards);
 
         for _ in 0..num_txns {
@@ -729,7 +736,9 @@ mod tests {
             let mut sender = accounts.swap_remove(sender_index);
             let receiver_index = rng.gen_range(0, accounts.len());
             let receiver = accounts.get(receiver_index).unwrap();
-            transactions.push(create_signed_p2p_transaction(&mut sender, vec![receiver]).remove(0));
+            let analyzed_txn = create_signed_p2p_transaction(&mut sender, vec![receiver]).remove(0);
+            txns_by_hash.insert(analyzed_txn.transaction().hash(), analyzed_txn.clone());
+            transactions.push(analyzed_txn);
             accounts.push(sender)
         }
         let partitioner = ShardedBlockPartitioner::new(num_shards);
@@ -740,11 +749,11 @@ mod tests {
         for (shard_id, txns) in partitioned_txns.iter().enumerate() {
             let first_round_sub_block = txns.get_sub_block(0).unwrap();
             for txn in first_round_sub_block.iter() {
-                let storage_locations = txn
-                    .txn()
+                let analyzed_txn = txns_by_hash.get(&txn.txn.hash()).unwrap();
+                let storage_locations = analyzed_txn
                     .read_hints()
                     .iter()
-                    .chain(txn.txn().write_hints().iter());
+                    .chain(analyzed_txn.write_hints().iter());
                 for storage_location in storage_locations {
                     if storage_location_to_shard_map.contains_key(storage_location) {
                         assert_eq!(
diff --git a/execution/block-partitioner/src/sharded_block_partitioner/partitioning_shard.rs b/execution/block-partitioner/src/sharded_block_partitioner/partitioning_shard.rs
index ebb8d83c3611a..9827dc92de5bf 100644
--- a/execution/block-partitioner/src/sharded_block_partitioner/partitioning_shard.rs
+++ b/execution/block-partitioner/src/sharded_block_partitioner/partitioning_shard.rs
@@ -11,7 +11,7 @@ use aptos_logger::trace;
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 use aptos_types::block_executor::partitioner::{ShardId, SubBlock, TransactionWithDependencies};
-use aptos_types::transaction::analyzed_transaction::AnalyzedTransaction;
+use aptos_types::transaction::Transaction;
 use std::sync::{
     mpsc::{Receiver, Sender},
     Arc,
@@ -93,8 +93,10 @@ impl PartitioningShard {
         let accepted_txns_with_dependencies = accepted_txns
             .into_iter()
             .zip(accepted_cross_shard_dependencies.into_iter())
-            .map(|(txn, dependencies)| TransactionWithDependencies::new(txn, dependencies))
-            .collect::>>();
+            .map(|(txn, dependencies)| {
+                TransactionWithDependencies::new(txn.into_txn(), dependencies)
+            })
+            .collect::>>();
 
         let mut frozen_sub_blocks = dependent_edge_creator.into_frozen_sub_blocks();
         let current_frozen_sub_block = SubBlock::new(index_offset, accepted_txns_with_dependencies);
diff --git a/execution/executor-service/src/lib.rs b/execution/executor-service/src/lib.rs
index ca39be9f052b2..1d7988e54760e 100644
--- a/execution/executor-service/src/lib.rs
+++ b/execution/executor-service/src/lib.rs
@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 use aptos_state_view::in_memory_state_view::InMemoryStateView;
 use aptos_types::{
+    block_executor::partitioner::SubBlocksForShard,
     transaction::{Transaction, TransactionOutput},
     vm_status::VMStatus,
 };
@@ -26,7 +27,7 @@ pub enum BlockExecutionRequest {
 
 #[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct ExecuteBlockCommand {
-    pub(crate) transactions: Vec,
+    pub(crate) sub_blocks: SubBlocksForShard,
     // Currently we only support the state view backed by in-memory hashmap, which means that
     // the controller needs to pre-read all the KV pairs from the storage and pass them to the
     // executor service. In the future, we will support other types of state view, e.g., the
diff --git a/execution/executor-service/src/remote_executor_client.rs b/execution/executor-service/src/remote_executor_client.rs
index a492bc58bbdfc..1b8eff64333f9 100644
--- a/execution/executor-service/src/remote_executor_client.rs
+++ b/execution/executor-service/src/remote_executor_client.rs
@@ -7,6 +7,7 @@ use aptos_retrier::{fixed_retry_strategy, retry};
 use aptos_secure_net::NetworkClient;
 use aptos_state_view::StateView;
 use aptos_types::{
+    block_executor::partitioner::SubBlocksForShard,
     transaction::{Transaction, TransactionOutput},
     vm_status::VMStatus,
 };
@@ -59,13 +60,13 @@ impl RemoteExecutorClient {
 impl BlockExecutorClient for RemoteExecutorClient {
     fn execute_block(
         &self,
-        transactions: Vec,
+        sub_blocks: SubBlocksForShard,
         state_view: &S,
         concurrency_level: usize,
         maybe_block_gas_limit: Option,
     ) -> Result, VMStatus> {
         let input = BlockExecutionRequest::ExecuteBlock(ExecuteBlockCommand {
-            transactions,
+            sub_blocks,
             state_view: S::as_in_memory_state_view(state_view),
             concurrency_level,
             maybe_block_gas_limit,
diff --git a/execution/executor-service/src/remote_executor_service.rs b/execution/executor-service/src/remote_executor_service.rs
index 236eb4be498c2..5e1389fec4387 100644
--- a/execution/executor-service/src/remote_executor_service.rs
+++ b/execution/executor-service/src/remote_executor_service.rs
@@ -37,7 +37,7 @@ impl ExecutorService {
     ) -> Result {
         let result = match execution_request {
             BlockExecutionRequest::ExecuteBlock(command) => self.client.execute_block(
-                command.transactions,
+                command.sub_blocks,
                 &command.state_view,
                 command.concurrency_level,
                 command.maybe_block_gas_limit,
@@ -90,6 +90,9 @@ mod tests {
     };
     use aptos_types::{
         account_config::{DepositEvent, WithdrawEvent},
+        block_executor::partitioner::{
+            CrossShardDependencies, SubBlock, SubBlocksForShard, TransactionWithDependencies,
+        },
         transaction::{ExecutionStatus, Transaction, TransactionOutput, TransactionStatus},
     };
     use aptos_vm::sharded_block_executor::{
@@ -194,9 +197,15 @@ mod tests {
         let mut executor = FakeExecutor::from_head_genesis();
         for _ in 0..5 {
             let (txns, receiver) = generate_transactions(&mut executor);
+            let txns_with_deps = txns
+                .into_iter()
+                .map(|txn| TransactionWithDependencies::new(txn, CrossShardDependencies::default()))
+                .collect::>();
+            let sub_block = SubBlock::new(0, txns_with_deps);
+            let sub_blocks_for_shard = SubBlocksForShard::new(0, vec![sub_block]);
 
             let output = client
-                .execute_block(txns, executor.data_store(), 2, None)
+                .execute_block(sub_blocks_for_shard, executor.data_store(), 2, None)
                 .unwrap();
             verify_txn_output(1_000, &output, &mut executor, &receiver);
         }
@@ -214,9 +223,20 @@ mod tests {
         let mut executor = FakeExecutor::from_head_genesis();
         for _ in 0..5 {
             let (txns, receiver) = generate_transactions(&mut executor);
+            let txns_with_deps = txns
+                .into_iter()
+                .map(|txn| TransactionWithDependencies::new(txn, CrossShardDependencies::default()))
+                .collect::>();
+            let sub_block = SubBlock::new(0, txns_with_deps);
+            let sub_blocks_for_shard = SubBlocksForShard::new(0, vec![sub_block]);
 
             let output = sharded_block_executor
-                .execute_block(Arc::new(executor.data_store().clone()), txns, 2, None)
+                .execute_block(
+                    Arc::new(executor.data_store().clone()),
+                    vec![sub_blocks_for_shard],
+                    2,
+                    None,
+                )
                 .unwrap();
             verify_txn_output(1_000, &output, &mut executor, &receiver);
         }
diff --git a/execution/executor/src/components/chunk_output.rs b/execution/executor/src/components/chunk_output.rs
index f72b55cca7cac..f8dd15520f05b 100644
--- a/execution/executor/src/components/chunk_output.rs
+++ b/execution/executor/src/components/chunk_output.rs
@@ -16,7 +16,7 @@ use aptos_storage_interface::{
 };
 use aptos_types::{
     account_config::CORE_CODE_ADDRESS,
-    block_executor::partitioner::ExecutableTransactions,
+    block_executor::partitioner::{ExecutableTransactions, SubBlocksForShard},
     transaction::{ExecutionStatus, Transaction, TransactionOutput, TransactionStatus},
 };
 use aptos_vm::{
@@ -89,13 +89,13 @@ impl ChunkOutput {
     }
 
     pub fn by_transaction_execution_sharded(
-        transactions: Vec,
+        block: Vec>,
         state_view: CachedStateView,
         maybe_block_gas_limit: Option,
     ) -> Result {
         let state_view_arc = Arc::new(state_view);
         let transaction_outputs = Self::execute_block_sharded::(
-            transactions.clone(),
+            block.clone(),
             state_view_arc.clone(),
             maybe_block_gas_limit,
         )?;
@@ -107,7 +107,7 @@ impl ChunkOutput {
         let state_view = Arc::try_unwrap(state_view_arc).unwrap();
 
         Ok(Self {
-            transactions,
+            transactions: SubBlocksForShard::flatten(block),
             transaction_outputs,
             state_cache: state_view.into_state_cache(),
         })
@@ -176,13 +176,13 @@ impl ChunkOutput {
     }
 
     fn execute_block_sharded(
-        transactions: Vec,
+        block: Vec>,
         state_view: Arc,
         maybe_block_gas_limit: Option,
     ) -> Result> {
         Ok(V::execute_block_sharded(
             SHARDED_BLOCK_EXECUTOR.lock().deref(),
-            transactions,
+            block,
             state_view,
             maybe_block_gas_limit,
         )?)
diff --git a/execution/executor/src/fuzzing.rs b/execution/executor/src/fuzzing.rs
index 9bc051e576882..9b7969fe278cf 100644
--- a/execution/executor/src/fuzzing.rs
+++ b/execution/executor/src/fuzzing.rs
@@ -14,7 +14,7 @@ use aptos_storage_interface::{
     cached_state_view::CachedStateView, state_delta::StateDelta, DbReader, DbReaderWriter, DbWriter,
 };
 use aptos_types::{
-    block_executor::partitioner::ExecutableTransactions,
+    block_executor::partitioner::{ExecutableTransactions, SubBlocksForShard},
     ledger_info::LedgerInfoWithSignatures,
     test_helpers::transaction_test_helpers::BLOCK_GAS_LIMIT,
     transaction::{Transaction, TransactionOutput, TransactionToCommit, Version},
@@ -68,7 +68,7 @@ impl TransactionBlockExecutor for FakeVM {
 impl VMExecutor for FakeVM {
     fn execute_block_sharded(
         _sharded_block_executor: &ShardedBlockExecutor,
-        _transactions: Vec,
+        _block: Vec>,
         _state_view: Arc,
         _maybe_block_gas_limit: Option,
     ) -> Result, VMStatus> {
diff --git a/execution/executor/src/mock_vm/mod.rs b/execution/executor/src/mock_vm/mod.rs
index eb584a375c48e..98f5c668649bb 100644
--- a/execution/executor/src/mock_vm/mod.rs
+++ b/execution/executor/src/mock_vm/mod.rs
@@ -14,7 +14,7 @@ use aptos_types::{
     access_path::AccessPath,
     account_address::AccountAddress,
     account_config::CORE_CODE_ADDRESS,
-    block_executor::partitioner::ExecutableTransactions,
+    block_executor::partitioner::{ExecutableTransactions, SubBlocksForShard},
     chain_id::ChainId,
     contract_event::ContractEvent,
     event::EventKey,
@@ -209,7 +209,7 @@ impl VMExecutor for MockVM {
 
     fn execute_block_sharded(
         _sharded_block_executor: &ShardedBlockExecutor,
-        _transactions: Vec,
+        _block: Vec>,
         _state_view: Arc,
         _maybe_block_gas_limit: Option,
     ) -> std::result::Result, VMStatus> {
diff --git a/testsuite/parallel_execution_performance.py b/testsuite/parallel_execution_performance.py
index 072b23dc11e1a..3db98347f5214 100755
--- a/testsuite/parallel_execution_performance.py
+++ b/testsuite/parallel_execution_performance.py
@@ -22,14 +22,14 @@
 
 SPEEDUPS = {
     "1k_8": 3,
-    "1k_16": 4,
+    "1k_16": 3,
     # "1k_32": 4,
-    "10k_8": 5,
-    "10k_16": 8,
-    "10k_32": 11,
-    "50k_8": 6,
-    "50k_16": 9,
-    "50k_32": 12,
+    "10k_8": 4,
+    "10k_16": 6,
+    "10k_32": 9,
+    "50k_8": 3,
+    "50k_16": 5,
+    "50k_32": 8,
 }
 
 THRESHOLDS_NOISE = 0.20
diff --git a/testsuite/sequential_execution_performance.py b/testsuite/sequential_execution_performance.py
index 3d6f9572998ea..b1a039d0efed7 100755
--- a/testsuite/sequential_execution_performance.py
+++ b/testsuite/sequential_execution_performance.py
@@ -4,7 +4,7 @@
 
 # Set the tps threshold for block size 1k, 10k and 50k
 BLOCK_SIZES = ["1k", "10k", "50k"]
-THRESHOLDS = {"1k": 3200, "10k": 4300, "50k": 7400}
+THRESHOLDS = {"1k": 3500, "10k": 5200, "50k": 12600}
 THRESHOLD_NOISE = 0.1
 
 # Run the VM sequential execution with performance optimizations enabled
diff --git a/types/src/block_executor/partitioner.rs b/types/src/block_executor/partitioner.rs
index c5dd6a446c22f..cb97e3a557659 100644
--- a/types/src/block_executor/partitioner.rs
+++ b/types/src/block_executor/partitioner.rs
@@ -2,12 +2,13 @@
 
 use crate::transaction::{analyzed_transaction::StorageLocation, Transaction};
 use aptos_crypto::HashValue;
+use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 
 pub type ShardId = usize;
 pub type TxnIndex = usize;
 
-#[derive(Debug, Clone, Eq, Hash, PartialEq)]
+#[derive(Debug, Clone, Eq, Hash, PartialEq, Serialize, Deserialize)]
 pub struct TxnIdxWithShardId {
     pub txn_index: TxnIndex,
     pub shard_id: ShardId,
@@ -22,7 +23,7 @@ impl TxnIdxWithShardId {
     }
 }
 
-#[derive(Debug, Default, Clone)]
+#[derive(Debug, Default, Clone, Serialize, Deserialize)]
 /// Denotes a set of cross shard edges, which contains the set (required or dependent) transaction
 /// indices and the relevant storage locations that are conflicting.
 pub struct CrossShardEdges {
@@ -73,7 +74,7 @@ impl IntoIterator for CrossShardEdges {
     }
 }
 
-#[derive(Default, Debug, Clone)]
+#[derive(Default, Debug, Clone, Serialize, Deserialize)]
 /// Represents the dependencies of a transaction on other transactions across shards. Two types
 /// of dependencies are supported:
 /// 1. `required_edges`: The transaction depends on the execution of the transactions in the set. In this
@@ -138,7 +139,6 @@ impl CrossShardDependencies {
     }
 }
 
-#[derive(Debug, Clone)]
 /// A contiguous chunk of transactions (along with their dependencies) in a block.
 ///
 /// Each `SubBlock` represents a sequential section of transactions within a block.
@@ -156,13 +156,14 @@ impl CrossShardDependencies {
 ///  | Transaction 3  | Transaction 6    | Transaction 9    |
 ///  +----------------+------------------+------------------+
 /// ```
+#[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct SubBlock {
     // This is the index of first transaction relative to the block.
     pub start_index: TxnIndex,
     pub transactions: Vec>,
 }
 
-impl SubBlock {
+impl SubBlock {
     pub fn new(start_index: TxnIndex, transactions: Vec>) -> Self {
         Self {
             start_index,
@@ -170,6 +171,13 @@ impl SubBlock {
         }
     }
 
+    pub fn empty() -> Self {
+        Self {
+            start_index: 0,
+            transactions: vec![],
+        }
+    }
+
     pub fn num_txns(&self) -> usize {
         self.transactions.len()
     }
@@ -190,6 +198,13 @@ impl SubBlock {
         self.transactions
     }
 
+    pub fn into_txns(self) -> Vec {
+        self.transactions
+            .into_iter()
+            .map(|txn_with_deps| txn_with_deps.into_txn())
+            .collect()
+    }
+
     pub fn add_dependent_edge(
         &mut self,
         source_index: TxnIndex,
@@ -208,7 +223,7 @@ impl SubBlock {
     }
 }
 
-impl IntoIterator for SubBlock {
+impl IntoIterator for SubBlock {
     type IntoIter = std::vec::IntoIter>;
     type Item = TransactionWithDependencies;
 
@@ -218,13 +233,20 @@ impl IntoIterator for SubBlock {
 }
 
 // A set of sub blocks assigned to a shard.
-#[derive(Default)]
+#[derive(Default, Clone, Debug, Serialize, Deserialize)]
 pub struct SubBlocksForShard {
     pub shard_id: ShardId,
     pub sub_blocks: Vec>,
 }
 
-impl SubBlocksForShard {
+impl SubBlocksForShard {
+    pub fn new(shard_id: ShardId, sub_blocks: Vec>) -> Self {
+        Self {
+            shard_id,
+            sub_blocks,
+        }
+    }
+
     pub fn empty(shard_id: ShardId) -> Self {
         Self {
             shard_id,
@@ -247,6 +269,17 @@ impl SubBlocksForShard {
         self.sub_blocks.len()
     }
 
+    pub fn into_sub_blocks(self) -> Vec> {
+        self.sub_blocks
+    }
+
+    pub fn into_txns(self) -> Vec {
+        self.sub_blocks
+            .into_iter()
+            .flat_map(|sub_block| sub_block.into_txns())
+            .collect()
+    }
+
     pub fn is_empty(&self) -> bool {
         self.sub_blocks.is_empty()
     }
@@ -268,15 +301,35 @@ impl SubBlocksForShard {
     pub fn get_sub_block_mut(&mut self, round: usize) -> Option<&mut SubBlock> {
         self.sub_blocks.get_mut(round)
     }
+
+    // Flattens a vector of `SubBlocksForShard` into a vector of transactions in the order they
+    // appear in the block.
+    pub fn flatten(block: Vec>) -> Vec {
+        let num_shards = block.len();
+        let mut flattened_txns = Vec::new();
+        let num_rounds = block[0].num_sub_blocks();
+        let mut ordered_blocks = vec![SubBlock::empty(); num_shards * num_rounds];
+        for (shard_id, sub_blocks) in block.into_iter().enumerate() {
+            for (round, sub_block) in sub_blocks.into_sub_blocks().into_iter().enumerate() {
+                ordered_blocks[round * num_shards + shard_id] = sub_block;
+            }
+        }
+
+        for sub_block in ordered_blocks.into_iter() {
+            flattened_txns.extend(sub_block.into_txns());
+        }
+
+        flattened_txns
+    }
 }
 
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct TransactionWithDependencies {
     pub txn: T,
     pub cross_shard_dependencies: CrossShardDependencies,
 }
 
-impl TransactionWithDependencies {
+impl TransactionWithDependencies {
     pub fn new(txn: T, cross_shard_dependencies: CrossShardDependencies) -> Self {
         Self {
             txn,
@@ -292,6 +345,10 @@ impl TransactionWithDependencies {
         &self.cross_shard_dependencies
     }
 
+    pub fn into_txn(self) -> T {
+        self.txn
+    }
+
     pub fn add_dependent_edge(
         &mut self,
         txn_idx: TxnIdxWithShardId,
@@ -307,7 +364,7 @@ pub struct ExecutableBlock {
     pub transactions: ExecutableTransactions,
 }
 
-impl ExecutableBlock {
+impl ExecutableBlock {
     pub fn new(block_id: HashValue, transactions: ExecutableTransactions) -> Self {
         Self {
             block_id,
@@ -316,18 +373,19 @@ impl ExecutableBlock {
     }
 }
 
-impl From<(HashValue, Vec)> for ExecutableBlock {
+impl From<(HashValue, Vec)> for ExecutableBlock {
     fn from((block_id, transactions): (HashValue, Vec)) -> Self {
         Self::new(block_id, ExecutableTransactions::Unsharded(transactions))
     }
 }
 
+// Represents the transactions in a block that are ready to be executed.
 pub enum ExecutableTransactions {
     Unsharded(Vec),
-    Sharded(Vec>),
+    Sharded(Vec>),
 }
 
-impl ExecutableTransactions {
+impl ExecutableTransactions {
     pub fn num_transactions(&self) -> usize {
         match self {
             ExecutableTransactions::Unsharded(transactions) => transactions.len(),
@@ -337,17 +395,41 @@ impl ExecutableTransactions {
                 .sum(),
         }
     }
+}
+
+impl From> for ExecutableTransactions {
+    fn from(txns: Vec) -> Self {
+        Self::Unsharded(txns)
+    }
+}
+
+// Represents the transactions that are executed on a particular block executor shard. Unsharded
+// transactions represents the entire block. Sharded transactions represents the transactions
+// that are assigned to this shard.
+pub enum BlockExecutorTransactions {
+    Unsharded(Vec),
+    Sharded(SubBlocksForShard),
+}
+
+impl BlockExecutorTransactions {
+    pub fn num_txns(&self) -> usize {
+        match self {
+            BlockExecutorTransactions::Unsharded(transactions) => transactions.len(),
+            BlockExecutorTransactions::Sharded(sub_blocks) => sub_blocks.num_txns(),
+        }
+    }
 
     pub fn get_unsharded_transactions(&self) -> Option<&Vec> {
         match self {
-            ExecutableTransactions::Unsharded(transactions) => Some(transactions),
-            ExecutableTransactions::Sharded(_) => None,
+            BlockExecutorTransactions::Unsharded(transactions) => Some(transactions),
+            BlockExecutorTransactions::Sharded(_) => None,
         }
     }
-}
 
-impl From> for ExecutableTransactions {
-    fn from(txns: Vec) -> Self {
-        Self::Unsharded(txns)
+    pub fn into_txns(self) -> Vec {
+        match self {
+            BlockExecutorTransactions::Unsharded(transactions) => transactions,
+            BlockExecutorTransactions::Sharded(sub_blocks) => sub_blocks.into_txns(),
+        }
     }
 }
diff --git a/types/src/transaction/analyzed_transaction.rs b/types/src/transaction/analyzed_transaction.rs
index b77952a2dc335..92f62a9483d8b 100644
--- a/types/src/transaction/analyzed_transaction.rs
+++ b/types/src/transaction/analyzed_transaction.rs
@@ -14,6 +14,7 @@ pub use move_core_types::abi::{
 use move_core_types::{
     account_address::AccountAddress, language_storage::StructTag, move_resource::MoveStructType,
 };
+use serde::{Deserialize, Serialize};
 use std::hash::{Hash, Hasher};
 
 #[derive(Clone, Debug)]
@@ -32,7 +33,7 @@ pub struct AnalyzedTransaction {
     hash: HashValue,
 }
 
-#[derive(Debug, Clone, Hash, Eq, PartialEq)]
+#[derive(Debug, Clone, Hash, Eq, PartialEq, Serialize, Deserialize)]
 // TODO(skedia): Evaluate if we need to cache the HashValue for efficiency reasons.
 pub enum StorageLocation {
     // A specific storage location denoted by an address and a struct tag.
@@ -68,7 +69,7 @@ impl AnalyzedTransaction {
         AnalyzedTransaction::new(transaction, vec![], vec![])
     }
 
-    pub fn into_inner(self) -> Transaction {
+    pub fn into_txn(self) -> Transaction {
         self.transaction
     }
 

From 1e65e9703625693801fb335d83fc27690354c2c7 Mon Sep 17 00:00:00 2001
From: Josh Lind 
Date: Wed, 14 Jun 2023 22:18:31 -0400
Subject: [PATCH 194/200] [Rust Toolchain] Upgrade up to rust version 1.7

---
 Cargo.lock                                    | 186 +++++++++---------
 api/src/tests/converter_test.rs               |   8 +-
 api/types/src/convert.rs                      |   6 +-
 api/types/src/lib.rs                          |   2 +
 aptos-move/aptos-vm/src/aptos_vm_impl.rs      |   4 +-
 aptos-move/aptos-vm/src/move_vm_ext/mod.rs    |   4 +-
 config/src/config/api_config.rs               |  12 +-
 config/src/config/indexer_grpc_config.rs      |   8 +-
 consensus/consensus-types/src/block_test.rs   |   3 -
 consensus/consensus-types/src/safety_data.rs  |   2 +-
 .../src/liveness/leader_reputation_test.rs    |  10 +-
 .../src/quorum_store/proof_coordinator.rs     |   5 +-
 consensus/src/round_manager_test.rs           |   3 +-
 .../src/txn_hash_and_authenticator_deduper.rs |   2 -
 crates/aptos-crypto/src/multi_ed25519.rs      |   4 +-
 .../src/unit_tests/ed25519_test.rs            |   2 +
 crates/aptos-faucet/core/Cargo.toml           |   2 +-
 crates/aptos-rosetta/src/types/requests.rs    |   9 +-
 .../src/account/derive_resource_account.rs    |   9 +-
 crates/aptos/src/common/types.rs              |   9 +-
 crates/aptos/src/ffi.rs                       |   3 +-
 crates/aptos/src/move_tool/mod.rs             |   1 -
 crates/transaction-emitter-lib/src/args.rs    |   4 +-
 .../transaction-emitter-lib/src/wrappers.rs   |   3 +-
 crates/transaction-generator-lib/src/args.rs  |   9 +-
 .../src/entry_points.rs                       |   1 -
 .../node-checker/src/provider/metrics.rs      |   2 +-
 execution/block-partitioner/src/main.rs       |   1 -
 .../src/transaction_generator.rs              |   1 -
 .../src/in_memory_state_calculator.rs         |   1 -
 rust-toolchain                                |   2 +-
 .../src/streaming_client.rs                   |   2 +-
 .../src/tests/storage_synchronizer.rs         |   2 +-
 storage/aptosdb/src/backup/restore_utils.rs   |   9 +-
 storage/aptosdb/src/test_helper.rs            |   2 +-
 storage/aptosdb/src/transaction_store/test.rs |   2 +
 .../src/backup_types/transaction/restore.rs   |   4 +-
 .../backup-cli/src/utils/stream/buffered_x.rs |   6 +-
 .../src/utils/stream/try_buffered_x.rs        |   6 +-
 storage/jellyfish-merkle/src/test_helper.rs   |   8 +-
 testsuite/forge-cli/src/main.rs               |   7 +-
 testsuite/forge/src/interface/admin.rs        |   2 +-
 testsuite/forge/src/interface/network.rs      |   2 +-
 testsuite/forge/src/runner.rs                 |   1 +
 testsuite/testcases/src/compatibility_test.rs |   2 +-
 .../src/consensus_reliability_tests.rs        |   2 +-
 testsuite/testcases/src/forge_setup_test.rs   |   2 +-
 testsuite/testcases/src/framework_upgrade.rs  |   2 +-
 .../src/fullnode_reboot_stress_test.rs        |   2 +-
 testsuite/testcases/src/lib.rs                |   4 +-
 .../testcases/src/load_vs_perf_benchmark.rs   |   2 +-
 testsuite/testcases/src/modifiers.rs          |   6 +-
 .../src/multi_region_network_test.rs          |   2 +-
 .../testcases/src/network_bandwidth_test.rs   |   2 +-
 testsuite/testcases/src/network_loss_test.rs  |   2 +-
 .../testcases/src/network_partition_test.rs   |   2 +-
 .../testcases/src/partial_nodes_down_test.rs  |   2 +-
 testsuite/testcases/src/performance_test.rs   |   2 +-
 .../src/quorum_store_onchain_enable_test.rs   |   2 +-
 .../testcases/src/reconfiguration_test.rs     |   2 +-
 .../testcases/src/state_sync_performance.rs   |   6 +-
 .../src/three_region_simulation_test.rs       |   2 +-
 .../testcases/src/twin_validator_test.rs      |   2 +-
 testsuite/testcases/src/two_traffics_test.rs  |   2 +-
 .../src/validator_join_leave_test.rs          |   2 +-
 .../src/validator_reboot_stress_test.rs       |   2 +-
 .../move/evm/move-to-yul/src/context.rs       |   3 +-
 .../move-binary-format/src/file_format.rs     |   9 +-
 .../move-command-line-common/src/types.rs     |   2 +-
 .../move-command-line-common/src/values.rs    |   2 +-
 .../move/move-compiler/src/cfgir/translate.rs |   2 +-
 .../move-compiler/src/expansion/translate.rs  |   4 +-
 .../move/move-compiler/src/hlir/translate.rs  |   4 +-
 .../move/move-compiler/src/parser/lexer.rs    |   2 +-
 .../move-core/types/src/account_address.rs    |   1 +
 .../move-ir-to-bytecode/syntax/src/lexer.rs   |   2 +-
 .../move-model/src/builder/module_builder.rs  |   4 +-
 .../bytecode/src/number_operation_analysis.rs |   2 +-
 .../move/move-vm/runtime/src/move_vm.rs       |   4 +-
 .../move/move-vm/test-utils/src/storage.rs    |   8 +-
 .../move-vm/types/src/values/values_impl.rs   |  12 +-
 third_party/move/move-vm/types/src/views.rs   |  18 +-
 82 files changed, 229 insertions(+), 275 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 47e38a1b5394a..3f7163200ee68 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -101,6 +101,15 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "aho-corasick"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43f6cb1bf222025340178f382c426f13757b2960e89779dfcb319c32542a5a41"
+dependencies = [
+ "memchr",
+]
+
 [[package]]
 name = "aliasable"
 version = "0.1.3"
@@ -4394,16 +4403,6 @@ dependencies = [
  "regex-automata",
 ]
 
-[[package]]
-name = "buf_redux"
-version = "0.8.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b953a6887648bb07a535631f2bc00fbdb2a2216f135552cb3f534ed136b9c07f"
-dependencies = [
- "memchr",
- "safemem",
-]
-
 [[package]]
 name = "bumpalo"
 version = "3.11.0"
@@ -4944,7 +4943,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2e4b6aa369f41f5faa04bb80c9b1f4216ea81646ed6124d76ba5c49a7aafd9cd"
 dependencies = [
  "cookie",
- "idna",
+ "idna 0.2.3",
  "log",
  "publicsuffix",
  "serde 1.0.149",
@@ -6079,11 +6078,10 @@ checksum = "00b0228411908ca8685dba7fc2cdd70ec9990a6e753e89b6ac91a84c40fbaf4b"
 
 [[package]]
 name = "form_urlencoded"
-version = "1.0.1"
+version = "1.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5fc25a87fa4fd2094bffb06925852034d90a17f0d1e05197d4956d3555752191"
+checksum = "a62bc1cf6f830c2ec14a513a9fb124d0a213a629668a4186f329db21fe045652"
 dependencies = [
- "matches",
  "percent-encoding",
 ]
 
@@ -6095,9 +6093,9 @@ checksum = "85dcb89d2b10c5f6133de2efd8c11959ce9dbb46a2f7a4cab208c4eeda6ce1ab"
 
 [[package]]
 name = "fs_extra"
-version = "1.2.0"
+version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2022715d62ab30faffd124d40b76f4134a550a87792276512b18d63272333394"
+checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c"
 
 [[package]]
 name = "funty"
@@ -6412,7 +6410,7 @@ version = "0.4.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0a1e17342619edbc21a964c2afbeb6c820c6a2560032872f397bb97ea127bd0a"
 dependencies = [
- "aho-corasick",
+ "aho-corasick 0.7.18",
  "bstr",
  "fnv",
  "log",
@@ -6734,9 +6732,9 @@ checksum = "c4a1e36c821dbe04574f602848a19f742f4fb3c98d40449f11bcad18d6b17421"
 
 [[package]]
 name = "httpmock"
-version = "0.6.6"
+version = "0.6.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c159c4fc205e6c1a9b325cb7ec135d13b5f47188ce175dabb76ec847f331d9bd"
+checksum = "c6b56b6265f15908780cbee987912c1e98dbca675361f748291605a8a3a1df09"
 dependencies = [
  "assert-json-diff",
  "async-object-pool",
@@ -6866,6 +6864,16 @@ dependencies = [
  "unicode-normalization",
 ]
 
+[[package]]
+name = "idna"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7d20d6b07bfbc108882d88ed8e37d39636dcc260e15e30c45e6ba089610b917c"
+dependencies = [
+ "unicode-bidi",
+ "unicode-normalization",
+]
+
 [[package]]
 name = "ignore"
 version = "0.4.18"
@@ -7386,7 +7394,7 @@ dependencies = [
  "petgraph 0.6.2",
  "pico-args",
  "regex",
- "regex-syntax",
+ "regex-syntax 0.6.27",
  "string_cache",
  "term",
  "tiny-keccak",
@@ -7556,6 +7564,12 @@ dependencies = [
  "winapi 0.3.9",
 ]
 
+[[package]]
+name = "libm"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f7012b1bbb0719e1097c47611d3898568c546d597c2e74d66f6087edd5233ff4"
+
 [[package]]
 name = "libnghttp2-sys"
 version = "0.1.7+1.45.0"
@@ -8896,9 +8910,9 @@ dependencies = [
 
 [[package]]
 name = "multer"
-version = "2.0.3"
+version = "2.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a30ba6d97eb198c5e8a35d67d5779d6680cca35652a60ee90fc23dc431d4fde8"
+checksum = "01acbdc23469fd8fe07ab135923371d5f5a422fbf9c522158677c8eb15bc51c2"
 dependencies = [
  "bytes",
  "encoding_rs",
@@ -8913,24 +8927,6 @@ dependencies = [
  "version_check",
 ]
 
-[[package]]
-name = "multipart"
-version = "0.18.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "00dec633863867f29cb39df64a397cdf4a6354708ddd7759f70c7fb51c5f9182"
-dependencies = [
- "buf_redux",
- "httparse",
- "log",
- "mime",
- "mime_guess",
- "quick-error 1.2.3",
- "rand 0.8.5",
- "safemem",
- "tempfile",
- "twoway",
-]
-
 [[package]]
 name = "named-lock"
 version = "0.2.0"
@@ -9165,6 +9161,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "578ede34cf02f8924ab9447f50c28075b4d3e5b269972345e7e0372b38c6cdcd"
 dependencies = [
  "autocfg",
+ "libm",
 ]
 
 [[package]]
@@ -9519,9 +9516,9 @@ dependencies = [
 
 [[package]]
 name = "percent-encoding"
-version = "2.1.0"
+version = "2.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d4fd5641d01c8f18a23da7b6fe29298ff4b55afcccdf78973b24cf3175fee32e"
+checksum = "9b2a4787296e9989611394c33f193f676704af1686e70b8f8033ab5ba9a35a94"
 
 [[package]]
 name = "pest"
@@ -10085,22 +10082,22 @@ dependencies = [
 
 [[package]]
 name = "proptest"
-version = "1.0.0"
+version = "1.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1e0d9cc07f18492d879586c92b485def06bc850da3118075cd45d50e9c95b0e5"
+checksum = "4e35c06b98bf36aba164cc17cb25f7e232f5c4aeea73baa14b8a9f0d92dbfa65"
 dependencies = [
  "bit-set",
  "bitflags 1.3.2",
  "byteorder",
  "lazy_static 1.4.0",
  "num-traits 0.2.15",
- "quick-error 2.0.1",
  "rand 0.8.5",
  "rand_chacha 0.3.1",
  "rand_xorshift",
- "regex-syntax",
+ "regex-syntax 0.6.27",
  "rusty-fork",
  "tempfile",
+ "unarray",
 ]
 
 [[package]]
@@ -10175,7 +10172,7 @@ version = "2.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "aeeedb0b429dc462f30ad27ef3de97058b060016f47790c066757be38ef792b4"
 dependencies = [
- "idna",
+ "idna 0.2.3",
  "psl-types",
 ]
 
@@ -10210,12 +10207,6 @@ version = "1.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a1d01941d82fa2ab50be1e79e6714289dd7cde78eba4c074bc5a4374f650dfe0"
 
-[[package]]
-name = "quick-error"
-version = "2.0.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3"
-
 [[package]]
 name = "quick-xml"
 version = "0.22.0"
@@ -10508,13 +10499,13 @@ dependencies = [
 
 [[package]]
 name = "regex"
-version = "1.6.0"
+version = "1.8.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4c4eb3267174b8c6c2f654116623910a0fef09c4753f8dd83db29c48a0df988b"
+checksum = "d0ab3ca65655bb1e41f2a8c8cd662eb4fb035e67c3f78da1d61dffe89d07300f"
 dependencies = [
- "aho-corasick",
+ "aho-corasick 1.0.2",
  "memchr",
- "regex-syntax",
+ "regex-syntax 0.7.2",
 ]
 
 [[package]]
@@ -10523,7 +10514,7 @@ version = "0.1.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6c230d73fb8d8c1b9c0b3135c5142a8acee3a0558fb8db5cf1cb65f8d7862132"
 dependencies = [
- "regex-syntax",
+ "regex-syntax 0.6.27",
 ]
 
 [[package]]
@@ -10532,6 +10523,12 @@ version = "0.6.27"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a3f87b73ce11b1619a3c6332f45341e0047173771e8b8b73f87bfeefb7b56244"
 
+[[package]]
+name = "regex-syntax"
+version = "0.7.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "436b050e76ed2903236f032a59761c1eb99e1b0aead2c257922771dab1fc8c78"
+
 [[package]]
 name = "remove_dir_all"
 version = "0.5.3"
@@ -10863,7 +10860,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cb3dcc6e454c328bb824492db107ab7c0ae8fcffe4ad210136ef014458c1bc4f"
 dependencies = [
  "fnv",
- "quick-error 1.2.3",
+ "quick-error",
  "tempfile",
  "wait-timeout",
 ]
@@ -10874,12 +10871,6 @@ version = "1.0.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4501abdff3ae82a1c1b477a17252eb69cee9e66eb915c1abaa4f44d873df9f09"
 
-[[package]]
-name = "safemem"
-version = "0.3.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ef703b7cb59335eae2eb93ceb664c0eb7ea6bf567079d843e09420219668e072"
-
 [[package]]
 name = "same-file"
 version = "1.0.6"
@@ -11235,6 +11226,17 @@ dependencies = [
  "digest 0.10.5",
 ]
 
+[[package]]
+name = "sha1"
+version = "0.10.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f04293dc80c3993519f2d7f6f511707ee7094fe0c6d3406feb330cdb3540eba3"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "digest 0.10.5",
+]
+
 [[package]]
 name = "sha1_smol"
 version = "1.0.0"
@@ -12034,9 +12036,9 @@ checksum = "cda74da7e1a664f795bb1f8a87ec406fb89a02522cf6e50620d016add6dbbf5c"
 
 [[package]]
 name = "tokio"
-version = "1.21.2"
+version = "1.26.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a9e03c497dc955702ba729190dc4aac6f2a0ce97f913e5b1b5912fc5039d9099"
+checksum = "03201d01c3c27a29c8a5cee5b55a93ddae1ccf6f08f65365c2c918f8c1b76f64"
 dependencies = [
  "autocfg",
  "bytes",
@@ -12050,7 +12052,7 @@ dependencies = [
  "socket2",
  "tokio-macros",
  "tracing",
- "winapi 0.3.9",
+ "windows-sys 0.45.0",
 ]
 
 [[package]]
@@ -12143,9 +12145,9 @@ dependencies = [
 
 [[package]]
 name = "tokio-tungstenite"
-version = "0.17.2"
+version = "0.18.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f714dd15bead90401d77e04243611caec13726c2408afd5b31901dfcdcb3b181"
+checksum = "54319c93411147bced34cb5609a80e0a8e44c5999c93903a81cd866630ec0bfd"
 dependencies = [
  "futures-util",
  "log",
@@ -12499,9 +12501,9 @@ dependencies = [
 
 [[package]]
 name = "tungstenite"
-version = "0.17.3"
+version = "0.18.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e27992fd6a8c29ee7eef28fc78349aa244134e10ad447ce3b9f0ac0ed0fa4ce0"
+checksum = "30ee6ab729cd4cf0fd55218530c4522ed30b7b6081752839b68fcec8d0960788"
 dependencies = [
  "base64 0.13.0",
  "byteorder",
@@ -12510,21 +12512,12 @@ dependencies = [
  "httparse",
  "log",
  "rand 0.8.5",
- "sha-1",
+ "sha1",
  "thiserror",
  "url",
  "utf-8",
 ]
 
-[[package]]
-name = "twoway"
-version = "0.1.8"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "59b11b2b5241ba34be09c3cc85a36e56e48f9888862e19cedf23336d35316ed1"
-dependencies = [
- "memchr",
-]
-
 [[package]]
 name = "typed-arena"
 version = "2.0.2"
@@ -12577,6 +12570,12 @@ dependencies = [
  "static_assertions",
 ]
 
+[[package]]
+name = "unarray"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eaea85b334db583fe3274d12b4cd1880032beab409c0d774be044d4480ab9a94"
+
 [[package]]
 name = "uncased"
 version = "0.9.7"
@@ -12647,9 +12646,9 @@ dependencies = [
 
 [[package]]
 name = "unicode-bidi"
-version = "0.3.8"
+version = "0.3.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "099b7128301d285f79ddd55b9a83d5e6b9e97c92e0ea0daebee7263e932de992"
+checksum = "92888ba5573ff080736b3648696b70cafad7d250551175acbaa4e0385b3e1460"
 
 [[package]]
 name = "unicode-ident"
@@ -12668,9 +12667,9 @@ dependencies = [
 
 [[package]]
 name = "unicode-normalization"
-version = "0.1.21"
+version = "0.1.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "854cbdc4f7bc6ae19c820d44abdc3277ac3e1b2b93db20a636825d9322fb60e6"
+checksum = "5c5713f0fc4b5db668a2ac63cdb7bb4469d8c9fed047b1d0292cc7b0ce2ba921"
 dependencies = [
  "tinyvec",
 ]
@@ -12740,13 +12739,12 @@ dependencies = [
 
 [[package]]
 name = "url"
-version = "2.2.2"
+version = "2.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a507c383b2d33b5fc35d1861e77e6b383d158b2da5e14fe51b83dfedf6fd578c"
+checksum = "50bff7831e19200a85b17131d085c25d7811bc4e186efdaf54bbd132994a88cb"
 dependencies = [
  "form_urlencoded",
- "idna",
- "matches",
+ "idna 0.4.0",
  "percent-encoding",
  "serde 1.0.149",
 ]
@@ -12865,9 +12863,9 @@ dependencies = [
 
 [[package]]
 name = "warp"
-version = "0.3.3"
+version = "0.3.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ed7b8be92646fc3d18b06147664ebc5f48d222686cb11a8755e561a735aacc6d"
+checksum = "ba431ef570df1287f7f8b07e376491ad54f84d26ac473489427231e1718e1f69"
 dependencies = [
  "bytes",
  "futures-channel",
@@ -12878,10 +12876,10 @@ dependencies = [
  "log",
  "mime",
  "mime_guess",
- "multipart",
+ "multer",
  "percent-encoding",
  "pin-project",
- "rustls-pemfile 0.2.1",
+ "rustls-pemfile 1.0.1",
  "scoped-tls",
  "serde 1.0.149",
  "serde_json",
diff --git a/api/src/tests/converter_test.rs b/api/src/tests/converter_test.rs
index 59c710780b14c..5b14f866162d9 100644
--- a/api/src/tests/converter_test.rs
+++ b/api/src/tests/converter_test.rs
@@ -57,8 +57,8 @@ async fn test_value_conversion() {
     );
 }
 
-fn assert_value_conversion<'r, R: MoveResolverExt, V: Serialize>(
-    converter: &MoveConverter<'r, R>,
+fn assert_value_conversion(
+    converter: &MoveConverter<'_, R>,
     json_move_type: &str,
     json_value: V,
     expected_vm_value: VmMoveValue,
@@ -76,8 +76,8 @@ fn assert_value_conversion<'r, R: MoveResolverExt, V: Serialize>(
     assert_eq!(json_value_back, json!(json_value));
 }
 
-fn assert_value_conversion_bytes<'r, R: MoveResolverExt>(
-    converter: &MoveConverter<'r, R>,
+fn assert_value_conversion_bytes(
+    converter: &MoveConverter<'_, R>,
     json_move_type: &str,
     vm_bytes: &[u8],
 ) {
diff --git a/api/types/src/convert.rs b/api/types/src/convert.rs
index 49307836c9563..33e42902f161d 100644
--- a/api/types/src/convert.rs
+++ b/api/types/src/convert.rs
@@ -80,7 +80,7 @@ impl<'a, R: MoveResolverExt + ?Sized> MoveConverter<'a, R> {
             .collect()
     }
 
-    pub fn try_into_resource<'b>(&self, typ: &StructTag, bytes: &'b [u8]) -> Result {
+    pub fn try_into_resource(&self, typ: &StructTag, bytes: &'_ [u8]) -> Result {
         self.inner.view_resource(typ, bytes)?.try_into()
     }
 
@@ -101,10 +101,10 @@ impl<'a, R: MoveResolverExt + ?Sized> MoveConverter<'a, R> {
             .collect::>>()
     }
 
-    pub fn move_struct_fields<'b>(
+    pub fn move_struct_fields(
         &self,
         typ: &StructTag,
-        bytes: &'b [u8],
+        bytes: &'_ [u8],
     ) -> Result> {
         self.inner.move_struct_fields(typ, bytes)
     }
diff --git a/api/types/src/lib.rs b/api/types/src/lib.rs
index 4d29db8f80fdb..b5785d92c7fb9 100644
--- a/api/types/src/lib.rs
+++ b/api/types/src/lib.rs
@@ -2,6 +2,8 @@
 // Parts of the project are originally copyright © Meta Platforms, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
+#![allow(clippy::match_result_ok)] // Required to overcome the limitations of deriving Union
+
 mod account;
 mod address;
 mod block;
diff --git a/aptos-move/aptos-vm/src/aptos_vm_impl.rs b/aptos-move/aptos-vm/src/aptos_vm_impl.rs
index cf757e4e1c355..00053214bfb06 100644
--- a/aptos-move/aptos-vm/src/aptos_vm_impl.rs
+++ b/aptos-move/aptos-vm/src/aptos_vm_impl.rs
@@ -614,10 +614,10 @@ impl AptosVMImpl {
             .new_session(resolver, session_id, aggregator_enabled)
     }
 
-    pub fn load_module<'r>(
+    pub fn load_module(
         &self,
         module_id: &ModuleId,
-        resolver: &'r impl MoveResolverExt,
+        resolver: &impl MoveResolverExt,
     ) -> VMResult> {
         self.move_vm.load_module(module_id, resolver)
     }
diff --git a/aptos-move/aptos-vm/src/move_vm_ext/mod.rs b/aptos-move/aptos-vm/src/move_vm_ext/mod.rs
index 1d22cdadc4493..a386a2f4ec780 100644
--- a/aptos-move/aptos-vm/src/move_vm_ext/mod.rs
+++ b/aptos-move/aptos-vm/src/move_vm_ext/mod.rs
@@ -1,8 +1,8 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
-///! MoveVM and Session wrapped, to make sure Aptos natives and extensions are always installed and
-///! taken care of after session finish.
+//! MoveVM and Session wrapped, to make sure Aptos natives and extensions are always installed and
+//! taken care of after session finish.
 mod resolver;
 mod respawned_session;
 mod session;
diff --git a/config/src/config/api_config.rs b/config/src/config/api_config.rs
index 2497ef00cc6e8..d2a77471fead2 100644
--- a/config/src/config/api_config.rs
+++ b/config/src/config/api_config.rs
@@ -74,14 +74,14 @@ pub struct ApiConfig {
     pub gas_estimation: GasEstimationConfig,
 }
 
-pub const DEFAULT_ADDRESS: &str = "127.0.0.1";
-pub const DEFAULT_PORT: u16 = 8080;
-pub const DEFAULT_REQUEST_CONTENT_LENGTH_LIMIT: u64 = 8 * 1024 * 1024; // 8 MB
+const DEFAULT_ADDRESS: &str = "127.0.0.1";
+const DEFAULT_PORT: u16 = 8080;
+const DEFAULT_REQUEST_CONTENT_LENGTH_LIMIT: u64 = 8 * 1024 * 1024; // 8 MB
 pub const DEFAULT_MAX_SUBMIT_TRANSACTION_BATCH_SIZE: usize = 10;
 pub const DEFAULT_MAX_PAGE_SIZE: u16 = 100;
-pub const DEFAULT_MAX_ACCOUNT_RESOURCES_PAGE_SIZE: u16 = 9999;
-pub const DEFAULT_MAX_ACCOUNT_MODULES_PAGE_SIZE: u16 = 9999;
-pub const DEFAULT_MAX_VIEW_GAS: u64 = 2_000_000; // We keep this value the same as the max number of gas allowed for one single transaction defined in aptos-gas.
+const DEFAULT_MAX_ACCOUNT_RESOURCES_PAGE_SIZE: u16 = 9999;
+const DEFAULT_MAX_ACCOUNT_MODULES_PAGE_SIZE: u16 = 9999;
+const DEFAULT_MAX_VIEW_GAS: u64 = 2_000_000; // We keep this value the same as the max number of gas allowed for one single transaction defined in aptos-gas.
 
 fn default_enabled() -> bool {
     true
diff --git a/config/src/config/indexer_grpc_config.rs b/config/src/config/indexer_grpc_config.rs
index 019a5002ff0e0..79645d31c65c8 100644
--- a/config/src/config/indexer_grpc_config.rs
+++ b/config/src/config/indexer_grpc_config.rs
@@ -8,10 +8,10 @@ use aptos_types::chain_id::ChainId;
 use serde::{Deserialize, Serialize};
 
 // Useful indexer defaults
-pub const DEFAULT_ADDRESS: &str = "0.0.0.0:50051";
-pub const DEFAULT_OUTPUT_BATCH_SIZE: u16 = 100;
-pub const DEFAULT_PROCESSOR_BATCH_SIZE: u16 = 1000;
-pub const DEFAULT_PROCESSOR_TASK_COUNT: u16 = 20;
+const DEFAULT_ADDRESS: &str = "0.0.0.0:50051";
+const DEFAULT_OUTPUT_BATCH_SIZE: u16 = 100;
+const DEFAULT_PROCESSOR_BATCH_SIZE: u16 = 1000;
+const DEFAULT_PROCESSOR_TASK_COUNT: u16 = 20;
 
 #[derive(Clone, Debug, Default, Deserialize, PartialEq, Eq, Serialize)]
 #[serde(default, deny_unknown_fields)]
diff --git a/consensus/consensus-types/src/block_test.rs b/consensus/consensus-types/src/block_test.rs
index df195c588036b..29544025f5e98 100644
--- a/consensus/consensus-types/src/block_test.rs
+++ b/consensus/consensus-types/src/block_test.rs
@@ -108,9 +108,6 @@ fn test_block_relation() {
         genesis_block.id()
     );
     assert_eq!(next_block.payload(), Some(&payload));
-
-    let cloned_block = next_block.clone();
-    assert_eq!(cloned_block.round(), next_block.round());
 }
 
 // Ensure that blocks that extend from the same QuorumCertificate but with different signatures
diff --git a/consensus/consensus-types/src/safety_data.rs b/consensus/consensus-types/src/safety_data.rs
index ebae3e67c58c2..9e90f2870f68b 100644
--- a/consensus/consensus-types/src/safety_data.rs
+++ b/consensus/consensus-types/src/safety_data.rs
@@ -62,6 +62,6 @@ fn test_safety_data_upgrade() {
         preferred_round: 100,
         last_vote: None,
     };
-    let value = serde_json::to_value(&old_data).unwrap();
+    let value = serde_json::to_value(old_data).unwrap();
     let _: SafetyData = serde_json::from_value(value).unwrap();
 }
diff --git a/consensus/src/liveness/leader_reputation_test.rs b/consensus/src/liveness/leader_reputation_test.rs
index 42858e12f59d4..ad1f58ad3eacf 100644
--- a/consensus/src/liveness/leader_reputation_test.rs
+++ b/consensus/src/liveness/leader_reputation_test.rs
@@ -36,7 +36,7 @@ use std::{collections::HashMap, sync::Arc};
 
 #[test]
 fn test_aggregation_bitmap_to_voters() {
-    let validators: Vec<_> = (0..4).into_iter().map(|_| Author::random()).collect();
+    let validators: Vec<_> = (0..4).map(|_| Author::random()).collect();
     let bitmap = vec![true, true, false, true];
 
     if let Ok(voters) = NewBlockEventAggregation::bitvec_to_voters(&validators, &bitmap.into()) {
@@ -51,7 +51,6 @@ fn test_aggregation_bitmap_to_voters() {
 #[test]
 fn test_aggregation_bitmap_to_voters_mismatched_lengths() {
     let validators: Vec<_> = (0..8) // size of 8 with one u8 in bitvec
-        .into_iter()
         .map(|_| Author::random())
         .collect();
     let bitmap_too_long = vec![true; 9]; // 2 bytes in bitvec
@@ -66,7 +65,7 @@ fn test_aggregation_bitmap_to_voters_mismatched_lengths() {
 
 #[test]
 fn test_aggregation_indices_to_authors() {
-    let validators: Vec<_> = (0..4).into_iter().map(|_| Author::random()).collect();
+    let validators: Vec<_> = (0..4).map(|_| Author::random()).collect();
     let indices = vec![2u64, 2, 0, 3];
 
     if let Ok(authors) = NewBlockEventAggregation::indices_to_validators(&validators, &indices) {
@@ -81,7 +80,7 @@ fn test_aggregation_indices_to_authors() {
 
 #[test]
 fn test_aggregation_indices_to_authors_out_of_index() {
-    let validators: Vec<_> = (0..4).into_iter().map(|_| Author::random()).collect();
+    let validators: Vec<_> = (0..4).map(|_| Author::random()).collect();
     let indices = vec![0, 0, 4, 0];
     assert!(NewBlockEventAggregation::indices_to_validators(&validators, &indices).is_err());
 }
@@ -95,8 +94,7 @@ struct Example1 {
 
 impl Example1 {
     fn new(window_size: usize) -> Self {
-        let mut sorted_validators: Vec =
-            (0..5).into_iter().map(|_| Author::random()).collect();
+        let mut sorted_validators: Vec = (0..5).map(|_| Author::random()).collect();
         sorted_validators.sort();
         // same first 3 validators, different 4th validator (index 3).
         let mut validators0: Vec = sorted_validators[..3].to_vec();
diff --git a/consensus/src/quorum_store/proof_coordinator.rs b/consensus/src/quorum_store/proof_coordinator.rs
index a179cfb617c56..a601542be8579 100644
--- a/consensus/src/quorum_store/proof_coordinator.rs
+++ b/consensus/src/quorum_store/proof_coordinator.rs
@@ -116,13 +116,12 @@ impl IncrementalProofState {
         }
         self.completed = true;
 
-        let proof = match validator_verifier
+        match validator_verifier
             .aggregate_signatures(&PartialSignatures::new(self.aggregated_signature.clone()))
         {
             Ok(sig) => ProofOfStore::new(self.info.clone(), sig),
             Err(e) => unreachable!("Cannot aggregate signatures on digest err = {:?}", e),
-        };
-        proof
+        }
     }
 }
 
diff --git a/consensus/src/round_manager_test.rs b/consensus/src/round_manager_test.rs
index 3f23d6506351b..7fccdface5e66 100644
--- a/consensus/src/round_manager_test.rs
+++ b/consensus/src/round_manager_test.rs
@@ -1305,6 +1305,7 @@ fn vote_resent_on_timeout() {
 }
 
 #[test]
+#[ignore] // TODO: this test needs to be fixed!
 fn sync_on_partial_newer_sync_info() {
     let runtime = consensus_runtime();
     let mut playground = NetworkPlayground::new(runtime.handle().clone());
@@ -1331,7 +1332,7 @@ fn sync_on_partial_newer_sync_info() {
             .unwrap();
         // commit genesis and block 1
         for i in 0..2 {
-            let _ = node.commit_next_ordered(&[i]);
+            node.commit_next_ordered(&[i]).await;
         }
         let vote_msg = node.next_vote().await;
         let vote_data = vote_msg.vote().vote_data();
diff --git a/consensus/src/txn_hash_and_authenticator_deduper.rs b/consensus/src/txn_hash_and_authenticator_deduper.rs
index 38ec5aeef421b..1f3331065b081 100644
--- a/consensus/src/txn_hash_and_authenticator_deduper.rs
+++ b/consensus/src/txn_hash_and_authenticator_deduper.rs
@@ -282,7 +282,6 @@ mod tests {
 
         let sender = Account::new();
         let txns: Vec<_> = (0..PERF_TXN_PER_BLOCK)
-            .into_iter()
             .map(|i| {
                 empty_txn(sender.addr, i as u64, 100)
                     .sign(&sender.privkey, sender.pubkey.clone())
@@ -324,7 +323,6 @@ mod tests {
         let sender = Account::new();
         let receiver = Account::new();
         let txns: Vec<_> = (0..PERF_TXN_PER_BLOCK)
-            .into_iter()
             .map(|i| {
                 peer_to_peer_txn(sender.addr, receiver.addr, i as u64, 100)
                     .sign(&sender.privkey, sender.pubkey.clone())
diff --git a/crates/aptos-crypto/src/multi_ed25519.rs b/crates/aptos-crypto/src/multi_ed25519.rs
index 53bab7eec39cc..0a543dd1c5d07 100644
--- a/crates/aptos-crypto/src/multi_ed25519.rs
+++ b/crates/aptos-crypto/src/multi_ed25519.rs
@@ -284,7 +284,7 @@ impl PublicKey for MultiEd25519PublicKey {
     type PrivateKeyMaterial = MultiEd25519PrivateKey;
 }
 
-#[allow(clippy::derive_hash_xor_eq)]
+#[allow(clippy::derived_hash_with_manual_eq)]
 impl std::hash::Hash for MultiEd25519PublicKey {
     fn hash(&self, state: &mut H) {
         let encoded_pubkey = self.to_bytes();
@@ -457,7 +457,7 @@ impl Length for MultiEd25519Signature {
     }
 }
 
-#[allow(clippy::derive_hash_xor_eq)]
+#[allow(clippy::derived_hash_with_manual_eq)]
 impl std::hash::Hash for MultiEd25519Signature {
     fn hash(&self, state: &mut H) {
         let encoded_signature = self.to_bytes();
diff --git a/crates/aptos-crypto/src/unit_tests/ed25519_test.rs b/crates/aptos-crypto/src/unit_tests/ed25519_test.rs
index 801501c928f07..335f2de2ed248 100644
--- a/crates/aptos-crypto/src/unit_tests/ed25519_test.rs
+++ b/crates/aptos-crypto/src/unit_tests/ed25519_test.rs
@@ -1,6 +1,8 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
+#![allow(clippy::redundant_clone)] // Required to work around prop_assert_eq! limitations
+
 use crate as aptos_crypto;
 use crate::{
     ed25519::{
diff --git a/crates/aptos-faucet/core/Cargo.toml b/crates/aptos-faucet/core/Cargo.toml
index 54d663090e7e2..0653a1eacc56e 100644
--- a/crates/aptos-faucet/core/Cargo.toml
+++ b/crates/aptos-faucet/core/Cargo.toml
@@ -33,7 +33,7 @@ once_cell = { workspace = true }
 poem = { workspace = true }
 poem-openapi = { workspace = true }
 rand = { workspace = true }
-redis = { workspace = true, features = ["aio", "tokio-comp", "connection-manager"], default-features = false }
+redis = { workspace = true, features = ["aio", "tokio-comp", "connection-manager"] }
 reqwest = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
diff --git a/crates/aptos-rosetta/src/types/requests.rs b/crates/aptos-rosetta/src/types/requests.rs
index 624312ec58a8d..32d74addcff11 100644
--- a/crates/aptos-rosetta/src/types/requests.rs
+++ b/crates/aptos-rosetta/src/types/requests.rs
@@ -375,9 +375,10 @@ pub struct PreprocessMetadata {
 }
 
 /// A gas price priority for what gas price to use
-#[derive(Debug, Copy, Clone, Eq, PartialEq)]
+#[derive(Debug, Default, Copy, Clone, Eq, PartialEq)]
 pub enum GasPricePriority {
     Low,
+    #[default]
     Normal,
     High,
 }
@@ -392,12 +393,6 @@ impl GasPricePriority {
     }
 }
 
-impl Default for GasPricePriority {
-    fn default() -> Self {
-        GasPricePriority::Normal
-    }
-}
-
 impl Display for GasPricePriority {
     fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
         f.write_str(self.as_str())
diff --git a/crates/aptos/src/account/derive_resource_account.rs b/crates/aptos/src/account/derive_resource_account.rs
index 2b14449dfbe7b..a2a065442e831 100644
--- a/crates/aptos/src/account/derive_resource_account.rs
+++ b/crates/aptos/src/account/derive_resource_account.rs
@@ -9,8 +9,9 @@ use clap::Parser;
 use std::{fmt::Formatter, str::FromStr};
 
 /// Encoding for the Resource account seed
-#[derive(Debug, Clone, Copy)]
+#[derive(Debug, Default, Clone, Copy)]
 pub enum SeedEncoding {
+    #[default]
     Bcs,
     Hex,
     Utf8,
@@ -20,12 +21,6 @@ const BCS: &str = "bcs";
 const UTF_8: &str = "utf8";
 const HEX: &str = "hex";
 
-impl Default for SeedEncoding {
-    fn default() -> Self {
-        SeedEncoding::Bcs
-    }
-}
-
 impl std::fmt::Display for SeedEncoding {
     fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
         f.write_str(match self {
diff --git a/crates/aptos/src/common/types.rs b/crates/aptos/src/common/types.rs
index dcd1fe85adfed..5b073eb7de8d7 100644
--- a/crates/aptos/src/common/types.rs
+++ b/crates/aptos/src/common/types.rs
@@ -452,11 +452,12 @@ impl ProfileOptions {
 }
 
 /// Types of encodings used by the blockchain
-#[derive(ArgEnum, Clone, Copy, Debug)]
+#[derive(ArgEnum, Clone, Copy, Debug, Default)]
 pub enum EncodingType {
     /// Binary Canonical Serialization
     BCS,
     /// Hex encoded e.g. 0xABCDE12345
+    #[default]
     Hex,
     /// Base 64 encoded
     Base64,
@@ -556,12 +557,6 @@ impl RngArgs {
     }
 }
 
-impl Default for EncodingType {
-    fn default() -> Self {
-        EncodingType::Hex
-    }
-}
-
 impl Display for EncodingType {
     fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
         let str = match self {
diff --git a/crates/aptos/src/ffi.rs b/crates/aptos/src/ffi.rs
index 9e06529025514..968ef24c4485b 100644
--- a/crates/aptos/src/ffi.rs
+++ b/crates/aptos/src/ffi.rs
@@ -30,8 +30,7 @@ pub unsafe extern "C" fn run_aptos_sync(s: *const c_char) -> *const c_char {
     // Create a new Tokio runtime and block on the execution of `cli.execute()`
     let result_string = Runtime::new().unwrap().block_on(async move {
         let cli = Tool::parse_from(input_string);
-        let result = cli.execute().await;
-        result
+        cli.execute().await
     });
 
     let res_cstr = CString::new(result_string.unwrap()).unwrap();
diff --git a/crates/aptos/src/move_tool/mod.rs b/crates/aptos/src/move_tool/mod.rs
index 47c5349cbf8ed..50a401ebd807e 100644
--- a/crates/aptos/src/move_tool/mod.rs
+++ b/crates/aptos/src/move_tool/mod.rs
@@ -313,7 +313,6 @@ impl CliCommand> for CompilePackage {
         }
         let ids = pack
             .modules()
-            .into_iter()
             .map(|m| m.self_id().to_string())
             .collect::>();
         Ok(ids)
diff --git a/crates/transaction-emitter-lib/src/args.rs b/crates/transaction-emitter-lib/src/args.rs
index 8402a1524eff8..d7b22fcbd1f20 100644
--- a/crates/transaction-emitter-lib/src/args.rs
+++ b/crates/transaction-emitter-lib/src/args.rs
@@ -84,11 +84,11 @@ pub struct ClusterArgs {
 
 impl ClusterArgs {
     pub fn get_targets(&self) -> Result> {
-        return match (&self.targets, &self.targets_file) {
+        match (&self.targets, &self.targets_file) {
             (Some(targets), _) => Ok(targets.clone()),
             (None, Some(target_file)) => Self::get_targets_from_file(target_file),
             (_, _) => Err(anyhow::anyhow!("Expected either targets or target_file")),
-        };
+        }
     }
 
     fn get_targets_from_file(path: &String) -> Result> {
diff --git a/crates/transaction-emitter-lib/src/wrappers.rs b/crates/transaction-emitter-lib/src/wrappers.rs
index 00a36f1de247b..14cf2c53fd6cf 100644
--- a/crates/transaction-emitter-lib/src/wrappers.rs
+++ b/crates/transaction-emitter-lib/src/wrappers.rs
@@ -22,8 +22,7 @@ pub async fn emit_transactions(
         let cluster = Cluster::try_from_cluster_args(cluster_args)
             .await
             .context("Failed to build cluster")?;
-        return emit_transactions_with_cluster(&cluster, emit_args, cluster_args.reuse_accounts)
-            .await;
+        emit_transactions_with_cluster(&cluster, emit_args, cluster_args.reuse_accounts).await
     } else {
         let initial_delay_after_minting = emit_args.coordination_delay_between_instances.unwrap();
         let start_time = Instant::now();
diff --git a/crates/transaction-generator-lib/src/args.rs b/crates/transaction-generator-lib/src/args.rs
index 5325266830ce6..5c5906e707e60 100644
--- a/crates/transaction-generator-lib/src/args.rs
+++ b/crates/transaction-generator-lib/src/args.rs
@@ -6,11 +6,12 @@ use clap::{ArgEnum, Parser};
 use serde::{Deserialize, Serialize};
 
 /// Utility class for specifying transaction type with predefined configurations through CLI
-#[derive(Debug, Copy, Clone, ArgEnum, Deserialize, Parser, Serialize)]
+#[derive(Debug, Copy, Clone, ArgEnum, Default, Deserialize, Parser, Serialize)]
 pub enum TransactionTypeArg {
     NoOp,
     NoOp2Signers,
     NoOp5Signers,
+    #[default]
     CoinTransfer,
     CoinTransferWithInvalid,
     NonConflictingCoinTransfer,
@@ -31,12 +32,6 @@ pub enum TransactionTypeArg {
     TokenV2AmbassadorMint,
 }
 
-impl Default for TransactionTypeArg {
-    fn default() -> Self {
-        TransactionTypeArg::CoinTransfer
-    }
-}
-
 impl TransactionTypeArg {
     pub fn materialize_default(&self) -> TransactionType {
         self.materialize(1, false)
diff --git a/crates/transaction-generator-lib/src/entry_points.rs b/crates/transaction-generator-lib/src/entry_points.rs
index 511c68e1ea61f..f1287f6d8f157 100644
--- a/crates/transaction-generator-lib/src/entry_points.rs
+++ b/crates/transaction-generator-lib/src/entry_points.rs
@@ -56,7 +56,6 @@ impl UserModuleTransactionGenerator for EntryPointTransactionGenerator {
             MultiSigConfig::Random(num) => {
                 let new_accounts = Arc::new(
                     (0..num)
-                        .into_iter()
                         .map(|_| LocalAccount::generate(rng))
                         .collect::>(),
                 );
diff --git a/ecosystem/node-checker/src/provider/metrics.rs b/ecosystem/node-checker/src/provider/metrics.rs
index 3cee07634187a..7e88029b4fe37 100644
--- a/ecosystem/node-checker/src/provider/metrics.rs
+++ b/ecosystem/node-checker/src/provider/metrics.rs
@@ -74,7 +74,7 @@ impl MetricsProvider {
                 )
             })
             .map_err(|e| ProviderError::ParseError(anyhow!(e)))?;
-        Scrape::parse(body.lines().into_iter().map(|l| Ok(l.to_string())))
+        Scrape::parse(body.lines().map(|l| Ok(l.to_string())))
             .with_context(|| {
                 format!(
                     "Failed to parse response text from {} as a Prometheus scrape",
diff --git a/execution/block-partitioner/src/main.rs b/execution/block-partitioner/src/main.rs
index f7be700334916..5dade2bc352af 100644
--- a/execution/block-partitioner/src/main.rs
+++ b/execution/block-partitioner/src/main.rs
@@ -37,7 +37,6 @@ fn main() {
     println!("Created {} accounts", num_accounts);
     println!("Creating {} transactions", args.block_size);
     let transactions: Vec = (0..args.block_size)
-        .into_iter()
         .map(|_| {
             // randomly select a sender and receiver from accounts
             let mut rng = OsRng;
diff --git a/execution/executor-benchmark/src/transaction_generator.rs b/execution/executor-benchmark/src/transaction_generator.rs
index fd0b57323faba..a46bb4038eb22 100644
--- a/execution/executor-benchmark/src/transaction_generator.rs
+++ b/execution/executor-benchmark/src/transaction_generator.rs
@@ -412,7 +412,6 @@ impl TransactionGenerator {
         for _ in 0..num_blocks {
             // TODO: handle when block_size isn't divisible by transactions_per_sender
             let transactions: Vec<_> = (0..(block_size / transactions_per_sender))
-                .into_iter()
                 .flat_map(|_| {
                     let (sender, receivers) = self
                         .main_signer_accounts
diff --git a/execution/executor-types/src/in_memory_state_calculator.rs b/execution/executor-types/src/in_memory_state_calculator.rs
index 3010ad637432a..2ea0a22f040df 100644
--- a/execution/executor-types/src/in_memory_state_calculator.rs
+++ b/execution/executor-types/src/in_memory_state_calculator.rs
@@ -82,7 +82,6 @@ impl InMemoryStateCalculator {
         let state_cache = sharded_state_cache
             .iter()
             .flatten()
-            .into_iter()
             .map(|entry| (entry.key().clone(), entry.value().1.clone()))
             .collect();
 
diff --git a/rust-toolchain b/rust-toolchain
index 0403bed10c327..832e9afb6c139 100644
--- a/rust-toolchain
+++ b/rust-toolchain
@@ -1 +1 @@
-1.66.1
+1.70.0
diff --git a/state-sync/state-sync-v2/data-streaming-service/src/streaming_client.rs b/state-sync/state-sync-v2/data-streaming-service/src/streaming_client.rs
index 6015399082ce4..07f9a79381388 100644
--- a/state-sync/state-sync-v2/data-streaming-service/src/streaming_client.rs
+++ b/state-sync/state-sync-v2/data-streaming-service/src/streaming_client.rs
@@ -468,7 +468,7 @@ impl DataStreamingClient for StreamingServiceClient {
             notification_and_feedback,
         });
         // We can ignore the receiver as no data will be sent.
-        let _ = self.send_stream_request(client_request).await?;
+        let _receiver = self.send_stream_request(client_request).await?;
         Ok(())
     }
 }
diff --git a/state-sync/state-sync-v2/state-sync-driver/src/tests/storage_synchronizer.rs b/state-sync/state-sync-v2/state-sync-driver/src/tests/storage_synchronizer.rs
index 4bf2121e85115..678b8aae4daf2 100644
--- a/state-sync/state-sync-v2/state-sync-driver/src/tests/storage_synchronizer.rs
+++ b/state-sync/state-sync-v2/state-sync-driver/src/tests/storage_synchronizer.rs
@@ -451,7 +451,7 @@ async fn test_save_states_invalid_chunk() {
     );
 
     // Initialize the state synchronizer
-    let _ = storage_synchronizer
+    let _join_handle = storage_synchronizer
         .initialize_state_synchronizer(
             vec![create_epoch_ending_ledger_info()],
             create_epoch_ending_ledger_info(),
diff --git a/storage/aptosdb/src/backup/restore_utils.rs b/storage/aptosdb/src/backup/restore_utils.rs
index 5307b2be579ff..8c742d376059e 100644
--- a/storage/aptosdb/src/backup/restore_utils.rs
+++ b/storage/aptosdb/src/backup/restore_utils.rs
@@ -1,13 +1,12 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
-use crate::state_store::StateStore;
-///! This file contains utilities that are helpful for performing
-///! database restore operations, as required by restore and
-///! state sync v2.
+//! This file contains utilities that are helpful for performing
+//! database restore operations, as required by restore and
+//! state sync v2.
 use crate::{
     event_store::EventStore, ledger_store::LedgerStore, new_sharded_kv_schema_batch,
-    schema::transaction_accumulator::TransactionAccumulatorSchema,
+    schema::transaction_accumulator::TransactionAccumulatorSchema, state_store::StateStore,
     transaction_store::TransactionStore, ShardedStateKvSchemaBatch,
 };
 use anyhow::{ensure, Result};
diff --git a/storage/aptosdb/src/test_helper.rs b/storage/aptosdb/src/test_helper.rs
index f0d9f1eefd5bc..1163259bb730f 100644
--- a/storage/aptosdb/src/test_helper.rs
+++ b/storage/aptosdb/src/test_helper.rs
@@ -2,7 +2,7 @@
 // Parts of the project are originally copyright © Meta Platforms, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-///! This module provides reusable helpers in tests.
+//! This module provides reusable helpers in tests.
 use super::*;
 use crate::{
     jellyfish_merkle_node::JellyfishMerkleNodeSchema, schema::state_value::StateValueSchema,
diff --git a/storage/aptosdb/src/transaction_store/test.rs b/storage/aptosdb/src/transaction_store/test.rs
index b6fc708f3f7d2..09e79c219969c 100644
--- a/storage/aptosdb/src/transaction_store/test.rs
+++ b/storage/aptosdb/src/transaction_store/test.rs
@@ -2,6 +2,8 @@
 // Parts of the project are originally copyright © Meta Platforms, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
+#![allow(clippy::redundant_clone)] // Required to work around prop_assert_eq! limitations
+
 use super::*;
 use crate::AptosDB;
 use aptos_proptest_helpers::Index;
diff --git a/storage/backup/backup-cli/src/backup_types/transaction/restore.rs b/storage/backup/backup-cli/src/backup_types/transaction/restore.rs
index d38a37dd1ce7f..a665003b5284a 100644
--- a/storage/backup/backup-cli/src/backup_types/transaction/restore.rs
+++ b/storage/backup/backup-cli/src/backup_types/transaction/restore.rs
@@ -482,9 +482,7 @@ impl TransactionRestoreBatchController {
 
                     // create iterator of txn and its outputs to be replayed after the snapshot.
                     Ok(stream::iter(
-                        izip!(txns, txn_infos, write_sets, event_vecs)
-                            .into_iter()
-                            .map(Result::<_>::Ok),
+                        izip!(txns, txn_infos, write_sets, event_vecs).map(Result::<_>::Ok),
                     ))
                 })
             })
diff --git a/storage/backup/backup-cli/src/utils/stream/buffered_x.rs b/storage/backup/backup-cli/src/utils/stream/buffered_x.rs
index 03df996233464..62193c712b859 100644
--- a/storage/backup/backup-cli/src/utils/stream/buffered_x.rs
+++ b/storage/backup/backup-cli/src/utils/stream/buffered_x.rs
@@ -2,9 +2,9 @@
 // Parts of the project are originally copyright © Meta Platforms, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-///! This is a copy of `futures::stream::buffered` from `futures 0.3.6`, except that it uses
-///! `FuturesOrderedX` which provides concurrency control. So we can buffer more results without
-///! too many futures driven at the same time.
+//! This is a copy of `futures::stream::buffered` from `futures 0.3.6`, except that it uses
+//! `FuturesOrderedX` which provides concurrency control. So we can buffer more results without
+//! too many futures driven at the same time.
 use crate::utils::stream::futures_ordered_x::FuturesOrderedX;
 use futures::{
     ready,
diff --git a/storage/backup/backup-cli/src/utils/stream/try_buffered_x.rs b/storage/backup/backup-cli/src/utils/stream/try_buffered_x.rs
index 494ad8c21077f..8496f04239bf0 100644
--- a/storage/backup/backup-cli/src/utils/stream/try_buffered_x.rs
+++ b/storage/backup/backup-cli/src/utils/stream/try_buffered_x.rs
@@ -2,9 +2,9 @@
 // Parts of the project are originally copyright © Meta Platforms, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-///! This is a copy of `futures::try_stream::try_buffered` from `futures 0.3.16`, except that it uses
-///! `FuturesOrderedX` which provides concurrency control. So we can buffer more results without
-///! too many futures driven at the same time.
+//! This is a copy of `futures::try_stream::try_buffered` from `futures 0.3.16`, except that it uses
+//! `FuturesOrderedX` which provides concurrency control. So we can buffer more results without
+//! too many futures driven at the same time.
 use crate::utils::stream::futures_ordered_x::FuturesOrderedX;
 use core::pin::Pin;
 use futures::{
diff --git a/storage/jellyfish-merkle/src/test_helper.rs b/storage/jellyfish-merkle/src/test_helper.rs
index 7b18af51b5d1c..e606900af8496 100644
--- a/storage/jellyfish-merkle/src/test_helper.rs
+++ b/storage/jellyfish-merkle/src/test_helper.rs
@@ -191,8 +191,8 @@ pub fn test_get_range_proof((btree, n): (BTreeMap(
-    tree: &JellyfishMerkleTree<'a, MockTreeStore, V>,
+fn test_existent_keys_impl(
+    tree: &JellyfishMerkleTree<'_, MockTreeStore, V>,
     version: Version,
     existent_kvs: &HashMap,
 ) {
@@ -207,8 +207,8 @@ fn test_existent_keys_impl<'a, V: TestKey>(
     }
 }
 
-fn test_nonexistent_keys_impl<'a, V: TestKey>(
-    tree: &JellyfishMerkleTree<'a, MockTreeStore, V>,
+fn test_nonexistent_keys_impl(
+    tree: &JellyfishMerkleTree<'_, MockTreeStore, V>,
     version: Version,
     nonexistent_keys: &[HashValue],
 ) {
diff --git a/testsuite/forge-cli/src/main.rs b/testsuite/forge-cli/src/main.rs
index 2e5f7659c1187..581d67d8454c8 100644
--- a/testsuite/forge-cli/src/main.rs
+++ b/testsuite/forge-cli/src/main.rs
@@ -216,7 +216,6 @@ fn random_namespace(dictionary: Vec, rng: &mut R) -> Result>();
     Ok(format!("forge-{}", random_words.join("-")))
@@ -1879,7 +1878,7 @@ impl Test for GetMetadata {
 }
 
 impl AdminTest for GetMetadata {
-    fn run<'t>(&self, ctx: &mut AdminContext<'t>) -> Result<()> {
+    fn run(&self, ctx: &mut AdminContext<'_>) -> Result<()> {
         let client = ctx.rest_client();
         let runtime = Runtime::new().unwrap();
         runtime.block_on(client.get_aptos_version()).unwrap();
@@ -1968,7 +1967,7 @@ impl Test for RestartValidator {
 }
 
 impl NetworkTest for RestartValidator {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> Result<()> {
         let runtime = Runtime::new()?;
         runtime.block_on(async {
             let node = ctx.swarm().validators_mut().next().unwrap();
@@ -1993,7 +1992,7 @@ impl Test for EmitTransaction {
 }
 
 impl NetworkTest for EmitTransaction {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> Result<()> {
         let duration = Duration::from_secs(10);
         let all_validators = ctx
             .swarm()
diff --git a/testsuite/forge/src/interface/admin.rs b/testsuite/forge/src/interface/admin.rs
index 1ee409ea2b53d..50d726ced5a6a 100644
--- a/testsuite/forge/src/interface/admin.rs
+++ b/testsuite/forge/src/interface/admin.rs
@@ -13,7 +13,7 @@ use reqwest::Url;
 /// of the validators or full nodes running on the network.
 pub trait AdminTest: Test {
     /// Executes the test against the given context.
-    fn run<'t>(&self, ctx: &mut AdminContext<'t>) -> Result<()>;
+    fn run(&self, ctx: &mut AdminContext<'_>) -> Result<()>;
 }
 
 #[derive(Debug)]
diff --git a/testsuite/forge/src/interface/network.rs b/testsuite/forge/src/interface/network.rs
index a6f7a94995f7b..243a34995e981 100644
--- a/testsuite/forge/src/interface/network.rs
+++ b/testsuite/forge/src/interface/network.rs
@@ -16,7 +16,7 @@ use tokio::runtime::Runtime;
 /// nodes which comprise the network.
 pub trait NetworkTest: Test {
     /// Executes the test against the given context.
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> Result<()>;
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> Result<()>;
 }
 
 pub struct NetworkContext<'t> {
diff --git a/testsuite/forge/src/runner.rs b/testsuite/forge/src/runner.rs
index cb3b38daac5c9..6117a2f296d6f 100644
--- a/testsuite/forge/src/runner.rs
+++ b/testsuite/forge/src/runner.rs
@@ -92,6 +92,7 @@ arg_enum! {
     }
 }
 
+#[allow(clippy::derivable_impls)] // Required to overcome the limitations of arg_enum!
 impl Default for Format {
     fn default() -> Self {
         Format::Pretty
diff --git a/testsuite/testcases/src/compatibility_test.rs b/testsuite/testcases/src/compatibility_test.rs
index c366525c7a59d..d27ff4392b0f8 100644
--- a/testsuite/testcases/src/compatibility_test.rs
+++ b/testsuite/testcases/src/compatibility_test.rs
@@ -17,7 +17,7 @@ impl Test for SimpleValidatorUpgrade {
 }
 
 impl NetworkTest for SimpleValidatorUpgrade {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> Result<()> {
         let runtime = Runtime::new()?;
 
         // Get the different versions we're testing with
diff --git a/testsuite/testcases/src/consensus_reliability_tests.rs b/testsuite/testcases/src/consensus_reliability_tests.rs
index 816a5358e8206..99a8d6f18ed41 100644
--- a/testsuite/testcases/src/consensus_reliability_tests.rs
+++ b/testsuite/testcases/src/consensus_reliability_tests.rs
@@ -296,7 +296,7 @@ impl NetworkLoadTest for ChangingWorkingQuorumTest {
 }
 
 impl NetworkTest for ChangingWorkingQuorumTest {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> Result<()> {
         ::run(self, ctx)
     }
 }
diff --git a/testsuite/testcases/src/forge_setup_test.rs b/testsuite/testcases/src/forge_setup_test.rs
index e662810be507a..d88a91dde089b 100644
--- a/testsuite/testcases/src/forge_setup_test.rs
+++ b/testsuite/testcases/src/forge_setup_test.rs
@@ -24,7 +24,7 @@ impl Test for ForgeSetupTest {
 }
 
 impl NetworkTest for ForgeSetupTest {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> Result<()> {
         let mut rng = StdRng::from_seed(OsRng.gen());
         let runtime = Runtime::new().unwrap();
 
diff --git a/testsuite/testcases/src/framework_upgrade.rs b/testsuite/testcases/src/framework_upgrade.rs
index d0e43222c6374..cea22bd1476fc 100644
--- a/testsuite/testcases/src/framework_upgrade.rs
+++ b/testsuite/testcases/src/framework_upgrade.rs
@@ -22,7 +22,7 @@ impl Test for FrameworkUpgrade {
 }
 
 impl NetworkTest for FrameworkUpgrade {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> Result<()> {
         let runtime = Runtime::new()?;
 
         // Get the different versions we're testing with
diff --git a/testsuite/testcases/src/fullnode_reboot_stress_test.rs b/testsuite/testcases/src/fullnode_reboot_stress_test.rs
index ba7a109ae8fc1..a2d8702e402a8 100644
--- a/testsuite/testcases/src/fullnode_reboot_stress_test.rs
+++ b/testsuite/testcases/src/fullnode_reboot_stress_test.rs
@@ -47,7 +47,7 @@ impl NetworkLoadTest for FullNodeRebootStressTest {
 }
 
 impl NetworkTest for FullNodeRebootStressTest {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> Result<()> {
         ::run(self, ctx)
     }
 }
diff --git a/testsuite/testcases/src/lib.rs b/testsuite/testcases/src/lib.rs
index 9d98d766d3054..793efe383408f 100644
--- a/testsuite/testcases/src/lib.rs
+++ b/testsuite/testcases/src/lib.rs
@@ -157,7 +157,7 @@ pub trait NetworkLoadTest: Test {
 }
 
 impl NetworkTest for dyn NetworkLoadTest {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> Result<()> {
         let runtime = Runtime::new().unwrap();
         let start_timestamp = SystemTime::now()
             .duration_since(UNIX_EPOCH)
@@ -385,7 +385,7 @@ impl CompositeNetworkTest {
 }
 
 impl NetworkTest for CompositeNetworkTest {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> anyhow::Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> anyhow::Result<()> {
         for wrapper in &self.wrappers {
             wrapper.setup(ctx)?;
         }
diff --git a/testsuite/testcases/src/load_vs_perf_benchmark.rs b/testsuite/testcases/src/load_vs_perf_benchmark.rs
index f75a69e7253ad..4105d838a4809 100644
--- a/testsuite/testcases/src/load_vs_perf_benchmark.rs
+++ b/testsuite/testcases/src/load_vs_perf_benchmark.rs
@@ -141,7 +141,7 @@ impl LoadVsPerfBenchmark {
 }
 
 impl NetworkTest for LoadVsPerfBenchmark {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> Result<()> {
         assert!(
             self.criteria.is_empty() || self.criteria.len() == self.workloads.len(),
             "Invalid config, {} criteria and {} workloads given",
diff --git a/testsuite/testcases/src/modifiers.rs b/testsuite/testcases/src/modifiers.rs
index d8cb346dcf08a..4c02c3e90ba02 100644
--- a/testsuite/testcases/src/modifiers.rs
+++ b/testsuite/testcases/src/modifiers.rs
@@ -102,7 +102,7 @@ impl NetworkLoadTest for ExecutionDelayTest {
 }
 
 impl NetworkTest for ExecutionDelayTest {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> anyhow::Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> anyhow::Result<()> {
         ::run(self, ctx)
     }
 }
@@ -187,7 +187,7 @@ impl NetworkLoadTest for NetworkUnreliabilityTest {
 }
 
 impl NetworkTest for NetworkUnreliabilityTest {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> anyhow::Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> anyhow::Result<()> {
         ::run(self, ctx)
     }
 }
@@ -270,7 +270,7 @@ impl NetworkLoadTest for CpuChaosTest {
 }
 
 impl NetworkTest for CpuChaosTest {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> anyhow::Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> anyhow::Result<()> {
         ::run(self, ctx)
     }
 }
diff --git a/testsuite/testcases/src/multi_region_network_test.rs b/testsuite/testcases/src/multi_region_network_test.rs
index cebdd616652b6..0178c4217a7e7 100644
--- a/testsuite/testcases/src/multi_region_network_test.rs
+++ b/testsuite/testcases/src/multi_region_network_test.rs
@@ -264,7 +264,7 @@ impl NetworkLoadTest for MultiRegionNetworkEmulationTest {
 }
 
 impl NetworkTest for MultiRegionNetworkEmulationTest {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> anyhow::Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> anyhow::Result<()> {
         ::run(self, ctx)
     }
 }
diff --git a/testsuite/testcases/src/network_bandwidth_test.rs b/testsuite/testcases/src/network_bandwidth_test.rs
index 83ab365c8f34f..2b4b8e4dc1335 100644
--- a/testsuite/testcases/src/network_bandwidth_test.rs
+++ b/testsuite/testcases/src/network_bandwidth_test.rs
@@ -56,7 +56,7 @@ impl NetworkLoadTest for NetworkBandwidthTest {
 }
 
 impl NetworkTest for NetworkBandwidthTest {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> anyhow::Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> anyhow::Result<()> {
         ::run(self, ctx)
     }
 }
diff --git a/testsuite/testcases/src/network_loss_test.rs b/testsuite/testcases/src/network_loss_test.rs
index 37a9f98107d34..83df42470e5f5 100644
--- a/testsuite/testcases/src/network_loss_test.rs
+++ b/testsuite/testcases/src/network_loss_test.rs
@@ -42,7 +42,7 @@ impl NetworkLoadTest for NetworkLossTest {
 }
 
 impl NetworkTest for NetworkLossTest {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> anyhow::Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> anyhow::Result<()> {
         ::run(self, ctx)
     }
 }
diff --git a/testsuite/testcases/src/network_partition_test.rs b/testsuite/testcases/src/network_partition_test.rs
index 95300ea5a9dd6..6118a59496ea1 100644
--- a/testsuite/testcases/src/network_partition_test.rs
+++ b/testsuite/testcases/src/network_partition_test.rs
@@ -45,7 +45,7 @@ impl NetworkLoadTest for NetworkPartitionTest {
 }
 
 impl NetworkTest for NetworkPartitionTest {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> anyhow::Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> anyhow::Result<()> {
         ::run(self, ctx)
     }
 }
diff --git a/testsuite/testcases/src/partial_nodes_down_test.rs b/testsuite/testcases/src/partial_nodes_down_test.rs
index 1ba769005f9a4..2d6c126907cc4 100644
--- a/testsuite/testcases/src/partial_nodes_down_test.rs
+++ b/testsuite/testcases/src/partial_nodes_down_test.rs
@@ -16,7 +16,7 @@ impl Test for PartialNodesDown {
 }
 
 impl NetworkTest for PartialNodesDown {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> Result<()> {
         let runtime = Runtime::new()?;
         let duration = Duration::from_secs(120);
         let all_validators = ctx
diff --git a/testsuite/testcases/src/performance_test.rs b/testsuite/testcases/src/performance_test.rs
index 3475584acae96..f602ede7d437f 100644
--- a/testsuite/testcases/src/performance_test.rs
+++ b/testsuite/testcases/src/performance_test.rs
@@ -16,7 +16,7 @@ impl Test for PerformanceBenchmark {
 impl NetworkLoadTest for PerformanceBenchmark {}
 
 impl NetworkTest for PerformanceBenchmark {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> Result<()> {
         ::run(self, ctx)
     }
 }
diff --git a/testsuite/testcases/src/quorum_store_onchain_enable_test.rs b/testsuite/testcases/src/quorum_store_onchain_enable_test.rs
index 77d08a2d549a5..69ec6a2e478f6 100644
--- a/testsuite/testcases/src/quorum_store_onchain_enable_test.rs
+++ b/testsuite/testcases/src/quorum_store_onchain_enable_test.rs
@@ -108,7 +108,7 @@ impl NetworkLoadTest for QuorumStoreOnChainEnableTest {
 }
 
 impl NetworkTest for QuorumStoreOnChainEnableTest {
-    fn run<'t>(&self, ctx: &mut aptos_forge::NetworkContext<'t>) -> anyhow::Result<()> {
+    fn run(&self, ctx: &mut aptos_forge::NetworkContext<'_>) -> anyhow::Result<()> {
         ::run(self, ctx)
     }
 }
diff --git a/testsuite/testcases/src/reconfiguration_test.rs b/testsuite/testcases/src/reconfiguration_test.rs
index 3dfde8f347a91..57f99767eb194 100644
--- a/testsuite/testcases/src/reconfiguration_test.rs
+++ b/testsuite/testcases/src/reconfiguration_test.rs
@@ -14,7 +14,7 @@ impl Test for ReconfigurationTest {
 }
 
 impl NetworkTest for ReconfigurationTest {
-    fn run<'t>(&self, _ctx: &mut NetworkContext<'t>) -> Result<()> {
+    fn run(&self, _ctx: &mut NetworkContext<'_>) -> Result<()> {
         Err(anyhow!("Not supported in aptos-framework yet"))
     }
     // TODO(https://github.com/aptos-labs/aptos-core/issues/317): add back after support those transactions in aptos-framework
diff --git a/testsuite/testcases/src/state_sync_performance.rs b/testsuite/testcases/src/state_sync_performance.rs
index 8fbf771657790..22f43cc7a1569 100644
--- a/testsuite/testcases/src/state_sync_performance.rs
+++ b/testsuite/testcases/src/state_sync_performance.rs
@@ -28,7 +28,7 @@ impl Test for StateSyncFullnodePerformance {
 }
 
 impl NetworkTest for StateSyncFullnodePerformance {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> Result<()> {
         let all_fullnodes = get_fullnodes_and_check_setup(ctx, self.name())?;
 
         // Emit a lot of traffic and ensure the fullnodes can all sync
@@ -54,7 +54,7 @@ impl Test for StateSyncFullnodeFastSyncPerformance {
 }
 
 impl NetworkTest for StateSyncFullnodeFastSyncPerformance {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> Result<()> {
         let all_fullnodes = get_fullnodes_and_check_setup(ctx, self.name())?;
 
         // Emit a lot of traffic and ensure the fullnodes can all sync
@@ -130,7 +130,7 @@ impl Test for StateSyncValidatorPerformance {
 }
 
 impl NetworkTest for StateSyncValidatorPerformance {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> Result<()> {
         // Verify we have at least 7 validators (i.e., 3f+1, where f is 2)
         // so we can kill 2 validators but still make progress.
         let all_validators = ctx
diff --git a/testsuite/testcases/src/three_region_simulation_test.rs b/testsuite/testcases/src/three_region_simulation_test.rs
index 12c3eec27a4b2..2d17e83b00151 100644
--- a/testsuite/testcases/src/three_region_simulation_test.rs
+++ b/testsuite/testcases/src/three_region_simulation_test.rs
@@ -101,7 +101,7 @@ impl NetworkLoadTest for ThreeRegionSameCloudSimulationTest {
 }
 
 impl NetworkTest for ThreeRegionSameCloudSimulationTest {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> anyhow::Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> anyhow::Result<()> {
         ::run(self, ctx)
     }
 }
diff --git a/testsuite/testcases/src/twin_validator_test.rs b/testsuite/testcases/src/twin_validator_test.rs
index 100cbbce8e747..53905027f22b5 100644
--- a/testsuite/testcases/src/twin_validator_test.rs
+++ b/testsuite/testcases/src/twin_validator_test.rs
@@ -19,7 +19,7 @@ impl Test for TwinValidatorTest {
 impl NetworkLoadTest for TwinValidatorTest {}
 
 impl NetworkTest for TwinValidatorTest {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> anyhow::Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> anyhow::Result<()> {
         let runtime = Runtime::new().unwrap();
 
         let all_validators_ids = ctx
diff --git a/testsuite/testcases/src/two_traffics_test.rs b/testsuite/testcases/src/two_traffics_test.rs
index 1d52eb467d726..846099b3134f8 100644
--- a/testsuite/testcases/src/two_traffics_test.rs
+++ b/testsuite/testcases/src/two_traffics_test.rs
@@ -77,7 +77,7 @@ impl NetworkLoadTest for TwoTrafficsTest {
 }
 
 impl NetworkTest for TwoTrafficsTest {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> Result<()> {
         ::run(self, ctx)
     }
 }
diff --git a/testsuite/testcases/src/validator_join_leave_test.rs b/testsuite/testcases/src/validator_join_leave_test.rs
index 5e4d79a44ee00..46141e6304264 100644
--- a/testsuite/testcases/src/validator_join_leave_test.rs
+++ b/testsuite/testcases/src/validator_join_leave_test.rs
@@ -185,7 +185,7 @@ impl NetworkLoadTest for ValidatorJoinLeaveTest {
 }
 
 impl NetworkTest for ValidatorJoinLeaveTest {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> Result<()> {
         ::run(self, ctx)
     }
 }
diff --git a/testsuite/testcases/src/validator_reboot_stress_test.rs b/testsuite/testcases/src/validator_reboot_stress_test.rs
index 8929b8da66e08..9355ac97a99d8 100644
--- a/testsuite/testcases/src/validator_reboot_stress_test.rs
+++ b/testsuite/testcases/src/validator_reboot_stress_test.rs
@@ -61,7 +61,7 @@ impl NetworkLoadTest for ValidatorRebootStressTest {
 }
 
 impl NetworkTest for ValidatorRebootStressTest {
-    fn run<'t>(&self, ctx: &mut NetworkContext<'t>) -> Result<()> {
+    fn run(&self, ctx: &mut NetworkContext<'_>) -> Result<()> {
         ::run(self, ctx)
     }
 }
diff --git a/third_party/move/evm/move-to-yul/src/context.rs b/third_party/move/evm/move-to-yul/src/context.rs
index 11f45c4c85a86..4a8998dde9924 100644
--- a/third_party/move/evm/move-to-yul/src/context.rs
+++ b/third_party/move/evm/move-to-yul/src/context.rs
@@ -174,7 +174,7 @@ impl<'a> Context<'a> {
             .unwrap_or_else(|_| PathBuf::from("."))
             .to_string_lossy()
             .to_string()
-            + &std::path::MAIN_SEPARATOR.to_string();
+            + std::path::MAIN_SEPARATOR_STR;
         if file_path.starts_with(¤t_dir) {
             file_path[current_dir.len()..].to_string()
         } else {
@@ -255,7 +255,6 @@ impl<'a> Context<'a> {
     pub fn derive_contracts(&self) -> Vec {
         self.env
             .get_modules()
-            .into_iter()
             .filter_map(|ref m| {
                 if is_evm_contract_module(m) {
                     Some(self.extract_contract(m))
diff --git a/third_party/move/move-binary-format/src/file_format.rs b/third_party/move/move-binary-format/src/file_format.rs
index bc11c05835b6e..c23bd86ff1980 100644
--- a/third_party/move/move-binary-format/src/file_format.rs
+++ b/third_party/move/move-binary-format/src/file_format.rs
@@ -411,13 +411,14 @@ pub struct FieldDefinition {
 
 /// `Visibility` restricts the accessibility of the associated entity.
 /// - For function visibility, it restricts who may call into the associated function.
-#[derive(Clone, Copy, Debug, Eq, PartialEq, PartialOrd, Ord, Serialize, Deserialize)]
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, PartialOrd, Ord, Serialize, Deserialize)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(no_params))]
 #[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
 #[repr(u8)]
 pub enum Visibility {
     /// Accessible within its defining module only.
+    #[default]
     Private = 0x0,
     /// Accessible by any module or script outside of its declaring module.
     Public = 0x1,
@@ -432,12 +433,6 @@ impl Visibility {
     pub const DEPRECATED_SCRIPT: u8 = 0x2;
 }
 
-impl Default for Visibility {
-    fn default() -> Self {
-        Visibility::Private
-    }
-}
-
 impl std::convert::TryFrom for Visibility {
     type Error = ();
 
diff --git a/third_party/move/move-command-line-common/src/types.rs b/third_party/move/move-command-line-common/src/types.rs
index 6045e30a3c5cc..30c6378830185 100644
--- a/third_party/move/move-command-line-common/src/types.rs
+++ b/third_party/move/move-command-line-common/src/types.rs
@@ -45,7 +45,7 @@ pub enum ParsedType {
 }
 
 impl Display for TypeToken {
-    fn fmt<'f>(&self, formatter: &mut fmt::Formatter<'f>) -> Result<(), fmt::Error> {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
         let s = match *self {
             TypeToken::Whitespace => "[whitespace]",
             TypeToken::Ident => "[identifier]",
diff --git a/third_party/move/move-command-line-common/src/values.rs b/third_party/move/move-command-line-common/src/values.rs
index 54d1178f0ba61..915dedff84c00 100644
--- a/third_party/move/move-command-line-common/src/values.rs
+++ b/third_party/move/move-command-line-common/src/values.rs
@@ -120,7 +120,7 @@ impl ParsableValue for () {
 }
 
 impl Display for ValueToken {
-    fn fmt<'f>(&self, formatter: &mut fmt::Formatter<'f>) -> Result<(), fmt::Error> {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
         let s = match self {
             ValueToken::Number => "[num]",
             ValueToken::NumberTyped => "[num typed]",
diff --git a/third_party/move/move-compiler/src/cfgir/translate.rs b/third_party/move/move-compiler/src/cfgir/translate.rs
index bf3d963ccc4f2..1609edbe910bc 100644
--- a/third_party/move/move-compiler/src/cfgir/translate.rs
+++ b/third_party/move/move-compiler/src/cfgir/translate.rs
@@ -97,7 +97,7 @@ impl<'env> Context<'env> {
     // Returns the blocks inserted in insertion ordering
     pub fn finish_blocks(&mut self) -> (Label, BasicBlocks, Vec<(Label, BlockInfo)>) {
         self.next_label = None;
-        let start = mem::replace(&mut self.start, None);
+        let start = self.start.take();
         let blocks = mem::take(&mut self.blocks);
         let block_ordering = mem::take(&mut self.block_ordering);
         let block_info = mem::take(&mut self.block_info);
diff --git a/third_party/move/move-compiler/src/expansion/translate.rs b/third_party/move/move-compiler/src/expansion/translate.rs
index a3aefcf21835d..4ea08bf3f83bf 100644
--- a/third_party/move/move-compiler/src/expansion/translate.rs
+++ b/third_party/move/move-compiler/src/expansion/translate.rs
@@ -2522,7 +2522,7 @@ fn check_valid_address_name_(
 
 fn check_valid_local_name(context: &mut Context, v: &Var) {
     fn is_valid(s: Symbol) -> bool {
-        s.starts_with('_') || s.starts_with(|c| matches!(c, 'a'..='z'))
+        s.starts_with('_') || s.starts_with(|c: char| c.is_ascii_lowercase())
     }
     if !is_valid(v.value()) {
         let msg = format!(
@@ -2682,7 +2682,7 @@ fn check_valid_module_member_name_impl(
 }
 
 pub fn is_valid_struct_constant_or_schema_name(s: &str) -> bool {
-    s.starts_with(|c| matches!(c, 'A'..='Z'))
+    s.starts_with(|c: char| c.is_ascii_uppercase())
 }
 
 // Checks for a restricted name in any decl case
diff --git a/third_party/move/move-compiler/src/hlir/translate.rs b/third_party/move/move-compiler/src/hlir/translate.rs
index 704e48c73b3e2..2d5bba58bb863 100644
--- a/third_party/move/move-compiler/src/hlir/translate.rs
+++ b/third_party/move/move-compiler/src/hlir/translate.rs
@@ -804,8 +804,8 @@ fn exp(
     Box::new(exp_(context, result, expected_type_opt, te))
 }
 
-fn exp_<'env>(
-    context: &mut Context<'env>,
+fn exp_(
+    context: &mut Context<'_>,
     result: &mut Block,
     initial_expected_type_opt: Option<&H::Type>,
     initial_e: T::Exp,
diff --git a/third_party/move/move-compiler/src/parser/lexer.rs b/third_party/move/move-compiler/src/parser/lexer.rs
index 8a620e59ec689..5fb32638a5832 100644
--- a/third_party/move/move-compiler/src/parser/lexer.rs
+++ b/third_party/move/move-compiler/src/parser/lexer.rs
@@ -84,7 +84,7 @@ pub enum Tok {
 }
 
 impl fmt::Display for Tok {
-    fn fmt<'f>(&self, formatter: &mut fmt::Formatter<'f>) -> Result<(), fmt::Error> {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
         use Tok::*;
         let s = match *self {
             EOF => "[end-of-file]",
diff --git a/third_party/move/move-core/types/src/account_address.rs b/third_party/move/move-core/types/src/account_address.rs
index f1d5d9356aef4..cee0ee8a84c26 100644
--- a/third_party/move/move-core/types/src/account_address.rs
+++ b/third_party/move/move-core/types/src/account_address.rs
@@ -436,6 +436,7 @@ mod tests {
         }
 
         #[test]
+        #[allow(clippy::redundant_clone)] // Required to work around prop_assert_eq! limitations
         fn test_address_protobuf_roundtrip(addr in any::()) {
             let bytes = addr.to_vec();
             prop_assert_eq!(bytes.clone(), addr.as_ref());
diff --git a/third_party/move/move-ir-compiler/move-ir-to-bytecode/syntax/src/lexer.rs b/third_party/move/move-ir-compiler/move-ir-to-bytecode/syntax/src/lexer.rs
index 4bc9b895d7ca2..1435d31df3770 100644
--- a/third_party/move/move-ir-compiler/move-ir-to-bytecode/syntax/src/lexer.rs
+++ b/third_party/move/move-ir-compiler/move-ir-to-bytecode/syntax/src/lexer.rs
@@ -403,7 +403,7 @@ impl<'input> Lexer<'input> {
 fn get_name_len(text: &str) -> usize {
     // If the first character is 0..=9 or EOF, then return a length of 0.
     let first_char = text.chars().next().unwrap_or('0');
-    if ('0'..='9').contains(&first_char) {
+    if first_char.is_ascii_digit() {
         return 0;
     }
     text.chars()
diff --git a/third_party/move/move-model/src/builder/module_builder.rs b/third_party/move/move-model/src/builder/module_builder.rs
index 6c93c5f97be2b..0af5719318699 100644
--- a/third_party/move/move-model/src/builder/module_builder.rs
+++ b/third_party/move/move-model/src/builder/module_builder.rs
@@ -1122,7 +1122,7 @@ impl<'env, 'translator> ModuleBuilder<'env, 'translator> {
         }
         let spec_fun_idx = spec_fun_id.as_usize();
         let body = if self.spec_funs[spec_fun_idx].body.is_some() {
-            std::mem::replace(&mut self.spec_funs[spec_fun_idx].body, None).unwrap()
+            self.spec_funs[spec_fun_idx].body.take().unwrap()
         } else {
             // If the function is native and contains no mutable references
             // as parameters, consider it pure.
@@ -3080,7 +3080,7 @@ impl<'env, 'translator> ModuleBuilder<'env, 'translator> {
         // the full self. Rust requires us to do so (at least the author doesn't know better yet),
         // but moving it should be not too expensive.
         let body = if self.spec_funs[fun_idx].body.is_some() {
-            std::mem::replace(&mut self.spec_funs[fun_idx].body, None).unwrap()
+            self.spec_funs[fun_idx].body.take().unwrap()
         } else {
             // No body: assume it is pure.
             return;
diff --git a/third_party/move/move-prover/bytecode/src/number_operation_analysis.rs b/third_party/move/move-prover/bytecode/src/number_operation_analysis.rs
index d9ca376fa917f..13c145a24dd2a 100644
--- a/third_party/move/move-prover/bytecode/src/number_operation_analysis.rs
+++ b/third_party/move/move-prover/bytecode/src/number_operation_analysis.rs
@@ -84,7 +84,7 @@ impl NumberOperationProcessor {
         }
     }
 
-    fn analyze_fun<'a>(&self, env: &'a GlobalEnv, target: FunctionTarget) {
+    fn analyze_fun(&self, env: &'_ GlobalEnv, target: FunctionTarget) {
         if !target.func_env.is_native_or_intrinsic() {
             let cfg = StacklessControlFlowGraph::one_block(target.get_bytecode());
             let analyzer = NumberOperationAnalysis {
diff --git a/third_party/move/move-vm/runtime/src/move_vm.rs b/third_party/move/move-vm/runtime/src/move_vm.rs
index aab355185ac95..ea57adce68f15 100644
--- a/third_party/move/move-vm/runtime/src/move_vm.rs
+++ b/third_party/move/move-vm/runtime/src/move_vm.rs
@@ -69,10 +69,10 @@ impl MoveVM {
     }
 
     /// Load a module into VM's code cache
-    pub fn load_module<'r>(
+    pub fn load_module(
         &self,
         module_id: &ModuleId,
-        remote: &'r dyn MoveResolver,
+        remote: &dyn MoveResolver,
     ) -> VMResult> {
         self.runtime
             .loader()
diff --git a/third_party/move/move-vm/test-utils/src/storage.rs b/third_party/move/move-vm/test-utils/src/storage.rs
index 47b3cd80c61ef..7eff9cc7724fd 100644
--- a/third_party/move/move-vm/test-utils/src/storage.rs
+++ b/third_party/move/move-vm/test-utils/src/storage.rs
@@ -243,12 +243,8 @@ impl InMemoryStorage {
             changes,
         } = changes;
         self.tables.retain(|h, _| !removed_tables.contains(h));
-        self.tables.extend(
-            new_tables
-                .keys()
-                .into_iter()
-                .map(|h| (*h, BTreeMap::default())),
-        );
+        self.tables
+            .extend(new_tables.keys().map(|h| (*h, BTreeMap::default())));
         for (h, c) in changes {
             assert!(
                 self.tables.contains_key(&h),
diff --git a/third_party/move/move-vm/types/src/values/values_impl.rs b/third_party/move/move-vm/types/src/values/values_impl.rs
index 9d47503ed3101..4f0a947494b6e 100644
--- a/third_party/move/move-vm/types/src/values/values_impl.rs
+++ b/third_party/move/move-vm/types/src/values/values_impl.rs
@@ -3440,15 +3440,13 @@ impl ValueView for SignerRef {
 // Note: We may want to add more helpers to retrieve value views behind references here.
 
 impl Struct {
-    #[allow(clippy::needless_lifetimes)]
-    pub fn field_views<'a>(&'a self) -> impl ExactSizeIterator + Clone {
+    pub fn field_views(&self) -> impl ExactSizeIterator + Clone {
         self.fields.iter()
     }
 }
 
 impl Vector {
-    #[allow(clippy::needless_lifetimes)]
-    pub fn elem_views<'a>(&'a self) -> impl ExactSizeIterator + Clone {
+    pub fn elem_views(&self) -> impl ExactSizeIterator + Clone {
         struct ElemView<'b> {
             container: &'b Container,
             idx: usize,
@@ -3470,8 +3468,7 @@ impl Vector {
 }
 
 impl Reference {
-    #[allow(clippy::needless_lifetimes)]
-    pub fn value_view<'a>(&'a self) -> impl ValueView + 'a {
+    pub fn value_view(&self) -> impl ValueView + '_ {
         struct ValueBehindRef<'b>(&'b ReferenceImpl);
 
         impl<'b> ValueView for ValueBehindRef<'b> {
@@ -3490,8 +3487,7 @@ impl Reference {
 }
 
 impl GlobalValue {
-    #[allow(clippy::needless_lifetimes)]
-    pub fn view<'a>(&'a self) -> Option {
+    pub fn view(&self) -> Option {
         use GlobalValueImpl as G;
 
         struct Wrapper<'b>(&'b Rc>>);
diff --git a/third_party/move/move-vm/types/src/views.rs b/third_party/move/move-vm/types/src/views.rs
index 29a87e3261ac4..fbbb12c261cf6 100644
--- a/third_party/move/move-vm/types/src/views.rs
+++ b/third_party/move/move-vm/types/src/views.rs
@@ -4,7 +4,7 @@
 use move_core_types::{
     account_address::AccountAddress, gas_algebra::AbstractMemorySize, language_storage::TypeTag,
 };
-use std::mem::size_of;
+use std::mem::size_of_val;
 
 /// Trait that provides an abstract view into a Move type.
 ///
@@ -78,35 +78,35 @@ pub trait ValueView {
             }
 
             fn visit_vec_u8(&mut self, _depth: usize, vals: &[u8]) {
-                self.0 += ((size_of::() * vals.len()) as u64).into();
+                self.0 += (size_of_val(vals) as u64).into();
             }
 
             fn visit_vec_u16(&mut self, _depth: usize, vals: &[u16]) {
-                self.0 += ((size_of::() * vals.len()) as u64).into();
+                self.0 += (size_of_val(vals) as u64).into();
             }
 
             fn visit_vec_u32(&mut self, _depth: usize, vals: &[u32]) {
-                self.0 += ((size_of::() * vals.len()) as u64).into();
+                self.0 += (size_of_val(vals) as u64).into();
             }
 
             fn visit_vec_u64(&mut self, _depth: usize, vals: &[u64]) {
-                self.0 += ((size_of::() * vals.len()) as u64).into();
+                self.0 += (size_of_val(vals) as u64).into();
             }
 
             fn visit_vec_u128(&mut self, _depth: usize, vals: &[u128]) {
-                self.0 += ((size_of::() * vals.len()) as u64).into();
+                self.0 += (size_of_val(vals) as u64).into();
             }
 
             fn visit_vec_u256(&mut self, _depth: usize, vals: &[move_core_types::u256::U256]) {
-                self.0 += ((size_of::() * vals.len()) as u64).into();
+                self.0 += (size_of_val(vals) as u64).into();
             }
 
             fn visit_vec_bool(&mut self, _depth: usize, vals: &[bool]) {
-                self.0 += ((size_of::() * vals.len()) as u64).into();
+                self.0 += (size_of_val(vals) as u64).into();
             }
 
             fn visit_vec_address(&mut self, _depth: usize, vals: &[AccountAddress]) {
-                self.0 += ((size_of::() * vals.len()) as u64).into();
+                self.0 += (size_of_val(vals) as u64).into();
             }
 
             fn visit_ref(&mut self, _depth: usize, _is_global: bool) -> bool {

From de3a664a6eb2f38519ba3087f35b31b2e9aa4071 Mon Sep 17 00:00:00 2001
From: igor-aptos <110557261+igor-aptos@users.noreply.github.com>
Date: Sat, 17 Jun 2023 00:09:29 -0700
Subject: [PATCH 195/200] Add so that Forge tests print (less frequently -
 every 1m) emit stats. (#8697)

We have a few odd cases, and need to figure out if emitter is causing issues, or nodes.
---
 .../src/emitter/mod.rs                        | 98 +++++++++++--------
 .../src/emitter/submission_worker.rs          | 55 ++++++++---
 testsuite/forge-cli/src/main.rs               |  2 +-
 testsuite/testcases/src/lib.rs                | 10 +-
 4 files changed, 106 insertions(+), 59 deletions(-)

diff --git a/crates/transaction-emitter-lib/src/emitter/mod.rs b/crates/transaction-emitter-lib/src/emitter/mod.rs
index 79555f480e2e5..7ce901dafec27 100644
--- a/crates/transaction-emitter-lib/src/emitter/mod.rs
+++ b/crates/transaction-emitter-lib/src/emitter/mod.rs
@@ -493,9 +493,41 @@ impl EmitJob {
         self.stats.accumulate(&self.phase_starts)
     }
 
-    pub fn accumulate(&self) -> Vec {
+    pub fn peek_and_accumulate(&self) -> Vec {
         self.stats.accumulate(&self.phase_starts)
     }
+
+    pub async fn stop_job(self) -> Vec {
+        self.stop_and_accumulate().await
+    }
+
+    pub async fn periodic_stat(&self, duration: Duration, interval_secs: u64) {
+        let deadline = Instant::now() + duration;
+        let mut prev_stats: Option> = None;
+        let default_stats = TxnStats::default();
+        let window = Duration::from_secs(max(interval_secs, 1));
+        loop {
+            let left = deadline.saturating_duration_since(Instant::now());
+            if left.is_zero() {
+                break;
+            }
+            tokio::time::sleep(window.min(left)).await;
+            let cur_phase = self.stats.get_cur_phase();
+            let stats = self.peek_and_accumulate();
+            let delta = &stats[cur_phase]
+                - prev_stats
+                    .as_ref()
+                    .map(|p| &p[cur_phase])
+                    .unwrap_or(&default_stats);
+            prev_stats = Some(stats);
+            info!("phase {}: {}", cur_phase, delta.rate());
+        }
+    }
+
+    pub async fn periodic_stat_forward(self, duration: Duration, interval_secs: u64) -> Self {
+        self.periodic_stat(duration, interval_secs).await;
+        self
+    }
 }
 
 #[derive(Debug)]
@@ -615,17 +647,23 @@ impl TxnEmitter {
         );
 
         let all_start_sleep_durations = mode_params.get_all_start_sleep_durations(self.from_rng());
-        let mut all_accounts_iter = all_accounts.into_iter();
-        let mut workers = vec![];
+
+        // Creating workers is slow with many workers (TODO check why)
+        // so we create them all first, before starting them - so they start at the right time for
+        // traffic pattern to be correct.
+        info!("Tx emitter creating workers");
+        let mut submission_workers =
+            Vec::with_capacity(workers_per_endpoint * req.rest_clients.len());
         for _ in 0..workers_per_endpoint {
             for client in &req.rest_clients {
-                let accounts = (&mut all_accounts_iter)
-                    .take(mode_params.accounts_per_worker)
-                    .collect::>();
+                let accounts =
+                    all_accounts.split_off(all_accounts.len() - mode_params.accounts_per_worker);
+                assert!(accounts.len() == mode_params.accounts_per_worker);
+
                 let stop = stop.clone();
                 let stats = Arc::clone(&stats);
                 let txn_generator = txn_generator_creator.create_transaction_generator();
-                let worker_index = workers.len();
+                let worker_index = submission_workers.len();
 
                 let worker = SubmissionWorker::new(
                     accounts,
@@ -638,47 +676,28 @@ impl TxnEmitter {
                     check_account_sequence_only_once_for.contains(&worker_index),
                     self.from_rng(),
                 );
-                let join_handle = tokio_handle.spawn(worker.run().boxed());
-                workers.push(Worker { join_handle });
+                submission_workers.push(worker);
             }
         }
+
+        info!("Tx emitter workers created");
+        let phase_start = Instant::now();
+        let workers = submission_workers
+            .into_iter()
+            .map(|worker| Worker {
+                join_handle: tokio_handle.spawn(worker.run(phase_start).boxed()),
+            })
+            .collect();
         info!("Tx emitter workers started");
 
         Ok(EmitJob {
             workers,
             stop,
             stats,
-            phase_starts: vec![Instant::now()],
+            phase_starts: vec![phase_start],
         })
     }
 
-    pub async fn stop_job(self, job: EmitJob) -> Vec {
-        job.stop_and_accumulate().await
-    }
-
-    pub fn peek_job_stats(&self, job: &EmitJob) -> Vec {
-        job.accumulate()
-    }
-
-    pub async fn periodic_stat(&mut self, job: &EmitJob, duration: Duration, interval_secs: u64) {
-        let deadline = Instant::now() + duration;
-        let mut prev_stats: Option> = None;
-        let default_stats = TxnStats::default();
-        let window = Duration::from_secs(max(interval_secs, 1));
-        while Instant::now() < deadline {
-            tokio::time::sleep(window).await;
-            let cur_phase = job.stats.get_cur_phase();
-            let stats = self.peek_job_stats(job);
-            let delta = &stats[cur_phase]
-                - prev_stats
-                    .as_ref()
-                    .map(|p| &p[cur_phase])
-                    .unwrap_or(&default_stats);
-            prev_stats = Some(stats);
-            info!("phase {}: {}", cur_phase, delta.rate());
-        }
-    }
-
     async fn emit_txn_for_impl(
         mut self,
         source_account: &mut LocalAccount,
@@ -704,14 +723,13 @@ impl TxnEmitter {
                 job.start_next_phase();
             }
             if let Some(interval_secs) = print_stats_interval {
-                self.periodic_stat(&job, per_phase_duration, interval_secs)
-                    .await;
+                job.periodic_stat(per_phase_duration, interval_secs).await;
             } else {
                 time::sleep(per_phase_duration).await;
             }
         }
         info!("Ran for {} secs, stopping job...", duration.as_secs());
-        let stats = self.stop_job(job).await;
+        let stats = job.stop_job().await;
         info!("Stopped job");
         Ok(stats.into_iter().next().unwrap())
     }
diff --git a/crates/transaction-emitter-lib/src/emitter/submission_worker.rs b/crates/transaction-emitter-lib/src/emitter/submission_worker.rs
index 54051976a00a4..499c17e0f091f 100644
--- a/crates/transaction-emitter-lib/src/emitter/submission_worker.rs
+++ b/crates/transaction-emitter-lib/src/emitter/submission_worker.rs
@@ -8,7 +8,7 @@ use crate::{
     },
     EmitModeParams,
 };
-use aptos_logger::{sample, sample::SampleRate, warn};
+use aptos_logger::{info, sample, sample::SampleRate, warn};
 use aptos_rest_client::Client as RestClient;
 use aptos_sdk::{
     move_types::account_address::AccountAddress,
@@ -69,21 +69,22 @@ impl SubmissionWorker {
     }
 
     #[allow(clippy::collapsible_if)]
-    pub(crate) async fn run(mut self) -> Vec {
-        let start_time = Instant::now() + self.start_sleep_duration;
-
-        self.sleep_check_done(self.start_sleep_duration).await;
+    pub(crate) async fn run(mut self, start_instant: Instant) -> Vec {
+        let mut wait_until = start_instant + self.start_sleep_duration;
 
+        let now = Instant::now();
+        if wait_until > now {
+            self.sleep_check_done(wait_until - now).await;
+        }
         let wait_duration = Duration::from_millis(self.params.wait_millis);
-        let mut wait_until = start_time;
 
         while !self.stop.load(Ordering::Relaxed) {
             let stats_clone = self.stats.clone();
             let loop_stats = stats_clone.get_cur();
 
-            let loop_start_time = Arc::new(Instant::now());
+            let loop_start_time = Instant::now();
             if wait_duration.as_secs() > 0
-                && loop_start_time.duration_since(wait_until) > wait_duration
+                && loop_start_time.duration_since(wait_until) > Duration::from_secs(5)
             {
                 sample!(
                     SampleRate::Duration(Duration::from_secs(120)),
@@ -114,6 +115,17 @@ impl SubmissionWorker {
                         })
                         .or_insert((cur, cur + 1));
                 }
+                // Some transaction generators use burner accounts, and will have different
+                // number of accounts per transaction, so useful to very rarely log.
+                sample!(
+                    SampleRate::Duration(Duration::from_secs(300)),
+                    info!(
+                        "[{:?}] txn_emitter worker: handling {} accounts, generated txns for: {}",
+                        self.client.path_prefix_string(),
+                        self.accounts.len(),
+                        account_to_start_and_end_seq_num.len(),
+                    )
+                );
 
                 let txn_expiration_time = requests
                     .iter()
@@ -130,7 +142,7 @@ impl SubmissionWorker {
                             submit_transactions(
                                 &self.client,
                                 reqs,
-                                loop_start_time.clone(),
+                                loop_start_time,
                                 txn_offset_time.clone(),
                                 loop_stats,
                             )
@@ -138,6 +150,18 @@ impl SubmissionWorker {
                 )
                 .await;
 
+                let submitted_after = loop_start_time.elapsed();
+                if submitted_after.as_secs() > 5 {
+                    sample!(
+                        SampleRate::Duration(Duration::from_secs(120)),
+                        warn!(
+                            "[{:?}] txn_emitter worker waited for more than 5s to submit transactions: {}s after loop start",
+                            self.client.path_prefix_string(),
+                            submitted_after.as_secs(),
+                        )
+                    );
+                }
+
                 if self.skip_latency_stats {
                     // we also don't want to be stuck waiting for txn_expiration_time_secs
                     // after stop is called, so we sleep until time or stop is set.
@@ -148,7 +172,7 @@ impl SubmissionWorker {
                 }
 
                 self.wait_and_update_stats(
-                    *loop_start_time,
+                    loop_start_time,
                     txn_offset_time.load(Ordering::Relaxed) / (requests.len() as u64),
                     account_to_start_and_end_seq_num,
                     // skip latency if asked to check seq_num only once
@@ -159,8 +183,11 @@ impl SubmissionWorker {
                     // generally, we should never need to recheck, as we wait enough time
                     // before calling here, but in case of shutdown/or client we are talking
                     // to being stale (having stale transaction_version), we might need to wait.
-                    if self.skip_latency_stats { 10 } else { 1 }
-                        * self.params.check_account_sequence_sleep,
+                    if self.skip_latency_stats {
+                        (10 * self.params.check_account_sequence_sleep).max(Duration::from_secs(3))
+                    } else {
+                        self.params.check_account_sequence_sleep
+                    },
                     loop_stats,
                 )
                 .await;
@@ -288,12 +315,12 @@ impl SubmissionWorker {
 pub async fn submit_transactions(
     client: &RestClient,
     txns: &[SignedTransaction],
-    loop_start_time: Arc,
+    loop_start_time: Instant,
     txn_offset_time: Arc,
     stats: &StatsAccumulator,
 ) {
     let cur_time = Instant::now();
-    let offset = cur_time - *loop_start_time;
+    let offset = cur_time - loop_start_time;
     txn_offset_time.fetch_add(
         txns.len() as u64 * offset.as_millis() as u64,
         Ordering::Relaxed,
diff --git a/testsuite/forge-cli/src/main.rs b/testsuite/forge-cli/src/main.rs
index 581d67d8454c8..56f83625589ae 100644
--- a/testsuite/forge-cli/src/main.rs
+++ b/testsuite/forge-cli/src/main.rs
@@ -1532,7 +1532,7 @@ fn realistic_network_tuned_for_throughput_test() -> ForgeConfig {
                 ["dynamic_max_txn_per_s"] = 6000.into();
 
             // Experimental storage optimizations
-            helm_values["validator"]["config"]["storage"]["rocksdb_configs"]["use_state_kv_db"] =
+            helm_values["validator"]["config"]["storage"]["rocksdb_configs"]["split_ledger_db"] =
                 true.into();
             helm_values["validator"]["config"]["storage"]["rocksdb_configs"]
                 ["use_sharded_state_merkle_db"] = true.into();
diff --git a/testsuite/testcases/src/lib.rs b/testsuite/testcases/src/lib.rs
index 793efe383408f..15070f00f070b 100644
--- a/testsuite/testcases/src/lib.rs
+++ b/testsuite/testcases/src/lib.rs
@@ -236,6 +236,7 @@ impl dyn NetworkLoadTest {
             stats_tracking_phases = 3;
         }
 
+        info!("Starting emitting txns for {}s", duration.as_secs());
         let mut job = rt
             .block_on(emitter.start_job(
                 ctx.swarm().chain_info().root_account,
@@ -248,9 +249,8 @@ impl dyn NetworkLoadTest {
         let cooldown_duration = duration.mul_f32(cooldown_duration_fraction);
         let test_duration = duration - warmup_duration - cooldown_duration;
         let phase_duration = test_duration.div_f32((stats_tracking_phases - 2) as f32);
-        info!("Starting emitting txns for {}s", duration.as_secs());
 
-        std::thread::sleep(warmup_duration);
+        job = rt.block_on(job.periodic_stat_forward(warmup_duration, 60));
         info!("{}s warmup finished", warmup_duration.as_secs());
 
         let max_start_ledger_transactions = rt
@@ -277,8 +277,10 @@ impl dyn NetworkLoadTest {
             }
             let phase_start = Instant::now();
 
+            let join_stats = rt.spawn(job.periodic_stat_forward(phase_duration, 60));
             self.test(ctx.swarm, ctx.report, phase_duration)
                 .context("test NetworkLoadTest")?;
+            job = rt.block_on(join_stats).context("join stats")?;
             actual_phase_durations.push(phase_start.elapsed());
         }
         let actual_test_duration = test_start.elapsed();
@@ -302,7 +304,7 @@ impl dyn NetworkLoadTest {
 
         let cooldown_used = cooldown_start.elapsed();
         if cooldown_used < cooldown_duration {
-            std::thread::sleep(cooldown_duration - cooldown_used);
+            job = rt.block_on(job.periodic_stat_forward(cooldown_duration - cooldown_used, 60));
         }
         info!("{}s cooldown finished", cooldown_duration.as_secs());
 
@@ -310,7 +312,7 @@ impl dyn NetworkLoadTest {
             "Emitting txns ran for {} secs, stopping job...",
             duration.as_secs()
         );
-        let stats_by_phase = rt.block_on(emitter.stop_job(job));
+        let stats_by_phase = rt.block_on(job.stop_job());
 
         info!("Stopped job");
         info!("Warmup stats: {}", stats_by_phase[0].rate());

From 237ac2322839074a20a4d57be19adfe253323c21 Mon Sep 17 00:00:00 2001
From: Kevin <105028215+movekevin@users.noreply.github.com>
Date: Sat, 17 Jun 2023 16:33:06 -0500
Subject: [PATCH 196/200] Add a new() function to smart_vector and simple_map
 to be more standardized across all data structures (#8712)

---
 .../framework/aptos-stdlib/doc/simple_map.md  | 33 +++++++++++++++--
 .../aptos-stdlib/doc/smart_vector.md          | 36 +++++++++++++++++--
 .../sources/data_structures/smart_vector.move |  8 +++++
 .../aptos-stdlib/sources/simple_map.move      |  7 ++++
 4 files changed, 79 insertions(+), 5 deletions(-)

diff --git a/aptos-move/framework/aptos-stdlib/doc/simple_map.md b/aptos-move/framework/aptos-stdlib/doc/simple_map.md
index 66092156f555b..1f15ce26b884c 100644
--- a/aptos-move/framework/aptos-stdlib/doc/simple_map.md
+++ b/aptos-move/framework/aptos-stdlib/doc/simple_map.md
@@ -15,6 +15,7 @@ This module provides a solution for sorted maps, that is it has the properties t
 -  [Struct `Element`](#0x1_simple_map_Element)
 -  [Constants](#@Constants_0)
 -  [Function `length`](#0x1_simple_map_length)
+-  [Function `new`](#0x1_simple_map_new)
 -  [Function `create`](#0x1_simple_map_create)
 -  [Function `borrow`](#0x1_simple_map_borrow)
 -  [Function `borrow_mut`](#0x1_simple_map_borrow_mut)
@@ -159,15 +160,42 @@ Map key is not found
 
 
 
+
+
+
+
+## Function `new`
+
+Create an empty SimpleMap.
+
+
+
public fun new<Key: store, Value: store>(): simple_map::SimpleMap<Key, Value>
+

+
+
+
+

+Implementation
+
+
+
public fun new<Key: store, Value: store>(): SimpleMap<Key, Value> {
+    create()
+}
+

+
+
+
 

 
 
 
 ## Function `create`
 
+Create an empty SimpleMap.
 
 
-
public fun create<Key: store, Value: store>(): simple_map::SimpleMap<Key, Value>
+
#[deprecated]
+public fun create<Key: store, Value: store>(): simple_map::SimpleMap<Key, Value>
 

 
 
@@ -625,7 +653,8 @@ using lambdas to destroy the individual keys and values.
 ### Function `create`
 
 
-
public fun create<Key: store, Value: store>(): simple_map::SimpleMap<Key, Value>
+
#[deprecated]
+public fun create<Key: store, Value: store>(): simple_map::SimpleMap<Key, Value>
 

 
 
diff --git a/aptos-move/framework/aptos-stdlib/doc/smart_vector.md b/aptos-move/framework/aptos-stdlib/doc/smart_vector.md
index 131fa86967b39..9ed0d1bcf4cd9 100644
--- a/aptos-move/framework/aptos-stdlib/doc/smart_vector.md
+++ b/aptos-move/framework/aptos-stdlib/doc/smart_vector.md
@@ -7,6 +7,7 @@
 
 -  [Struct `SmartVector`](#0x1_smart_vector_SmartVector)
 -  [Constants](#@Constants_0)
+-  [Function `new`](#0x1_smart_vector_new)
 -  [Function `empty`](#0x1_smart_vector_empty)
 -  [Function `empty_with_config`](#0x1_smart_vector_empty_with_config)
 -  [Function `singleton`](#0x1_smart_vector_singleton)
@@ -141,16 +142,44 @@ bucket_size cannot be 0
 
 
 
+
+
+## Function `new`
+
+Regular Vector API
+Create an empty vector using default logic to estimate inline_capacity and bucket_size, which may be
+inaccurate.
+This is exactly the same as empty() but is more standardized as all other data structures have new().
+
+
+
public fun new<T: store>(): smart_vector::SmartVector<T>
+

+
+
+
+

+Implementation
+
+
+
public fun new<T: store>(): SmartVector<T> {
+    empty()
+}
+

+
+
+
+

+
 
 
 ## Function `empty`
 
-Regular Vector API
 Create an empty vector using default logic to estimate inline_capacity and bucket_size, which may be
 inaccurate.
 
 
-
public fun empty<T: store>(): smart_vector::SmartVector<T>
+
#[deprecated]
+public fun empty<T: store>(): smart_vector::SmartVector<T>
 

 
 
@@ -817,7 +846,8 @@ Return true if the vector v has no elements and
 ### Function `empty`
 
 
-
public fun empty<T: store>(): smart_vector::SmartVector<T>
+
#[deprecated]
+public fun empty<T: store>(): smart_vector::SmartVector<T>
 

 
 
diff --git a/aptos-move/framework/aptos-stdlib/sources/data_structures/smart_vector.move b/aptos-move/framework/aptos-stdlib/sources/data_structures/smart_vector.move
index 6330e2e4b96e2..1368956100d75 100644
--- a/aptos-move/framework/aptos-stdlib/sources/data_structures/smart_vector.move
+++ b/aptos-move/framework/aptos-stdlib/sources/data_structures/smart_vector.move
@@ -27,6 +27,14 @@ module aptos_std::smart_vector {
 
     /// Regular Vector API
 
+    /// Create an empty vector using default logic to estimate `inline_capacity` and `bucket_size`, which may be
+    /// inaccurate.
+    /// This is exactly the same as empty() but is more standardized as all other data structures have new().
+    public fun new(): SmartVector {
+        empty()
+    }
+
+    #[deprecated]
     /// Create an empty vector using default logic to estimate `inline_capacity` and `bucket_size`, which may be
     /// inaccurate.
     public fun empty(): SmartVector {
diff --git a/aptos-move/framework/aptos-stdlib/sources/simple_map.move b/aptos-move/framework/aptos-stdlib/sources/simple_map.move
index 84a117786cc29..1d05791326513 100644
--- a/aptos-move/framework/aptos-stdlib/sources/simple_map.move
+++ b/aptos-move/framework/aptos-stdlib/sources/simple_map.move
@@ -27,6 +27,13 @@ module aptos_std::simple_map {
         vector::length(&map.data)
     }
 
+    /// Create an empty SimpleMap.
+    public fun new(): SimpleMap {
+        create()
+    }
+
+    #[deprecated]
+    /// Create an empty SimpleMap.
     public fun create(): SimpleMap {
         SimpleMap {
             data: vector::empty(),

From 6f40f0f446a8774fe6113bce930bfcadc1a6ba57 Mon Sep 17 00:00:00 2001
From: Kevin <105028215+movekevin@users.noreply.github.com>
Date: Sun, 18 Jun 2023 18:16:49 -0500
Subject: [PATCH 197/200] Add a new_from and add_all functions to simple_map
 (#8723)

---
 .../framework/aptos-stdlib/doc/simple_map.md  | 220 ++++++++++++++----
 .../aptos-stdlib/sources/simple_map.move      |  60 ++++-
 .../aptos-stdlib/sources/simple_map.spec.move |  12 +
 3 files changed, 238 insertions(+), 54 deletions(-)

diff --git a/aptos-move/framework/aptos-stdlib/doc/simple_map.md b/aptos-move/framework/aptos-stdlib/doc/simple_map.md
index 1f15ce26b884c..876f4238ae9ad 100644
--- a/aptos-move/framework/aptos-stdlib/doc/simple_map.md
+++ b/aptos-move/framework/aptos-stdlib/doc/simple_map.md
@@ -16,12 +16,14 @@ This module provides a solution for sorted maps, that is it has the properties t
 -  [Constants](#@Constants_0)
 -  [Function `length`](#0x1_simple_map_length)
 -  [Function `new`](#0x1_simple_map_new)
+-  [Function `new_from`](#0x1_simple_map_new_from)
 -  [Function `create`](#0x1_simple_map_create)
 -  [Function `borrow`](#0x1_simple_map_borrow)
 -  [Function `borrow_mut`](#0x1_simple_map_borrow_mut)
 -  [Function `contains_key`](#0x1_simple_map_contains_key)
 -  [Function `destroy_empty`](#0x1_simple_map_destroy_empty)
 -  [Function `add`](#0x1_simple_map_add)
+-  [Function `add_all`](#0x1_simple_map_add_all)
 -  [Function `upsert`](#0x1_simple_map_upsert)
 -  [Function `keys`](#0x1_simple_map_keys)
 -  [Function `values`](#0x1_simple_map_values)
@@ -32,12 +34,15 @@ This module provides a solution for sorted maps, that is it has the properties t
 -  [Specification](#@Specification_1)
     -  [Struct `SimpleMap`](#@Specification_1_SimpleMap)
     -  [Function `length`](#@Specification_1_length)
+    -  [Function `new`](#@Specification_1_new)
+    -  [Function `new_from`](#@Specification_1_new_from)
     -  [Function `create`](#@Specification_1_create)
     -  [Function `borrow`](#@Specification_1_borrow)
     -  [Function `borrow_mut`](#@Specification_1_borrow_mut)
     -  [Function `contains_key`](#@Specification_1_contains_key)
     -  [Function `destroy_empty`](#@Specification_1_destroy_empty)
     -  [Function `add`](#@Specification_1_add)
+    -  [Function `add_all`](#@Specification_1_add_all)
     -  [Function `upsert`](#@Specification_1_upsert)
     -  [Function `keys`](#@Specification_1_keys)
     -  [Function `values`](#@Specification_1_values)
@@ -138,6 +143,16 @@ Map key is not found
 
 
 
+
+
+Lengths of keys and values do not match
+
+
+
const EMISMATCHED_LENGTHS: u64 = 3;
+

+
+
+
 
 
 ## Function `length`
@@ -179,7 +194,39 @@ Create an empty SimpleMap.
 
 
 
public fun new<Key: store, Value: store>(): SimpleMap<Key, Value> {
-    create()
+    SimpleMap {
+        data: vector::empty(),
+    }
+}
+

+
+
+
+
+
+
+
+## Function `new_from`
+
+Create a SimpleMap from a vector of keys and values. The keys must be unique.
+
+
+
public fun new_from<Key: store, Value: store>(keys: vector<Key>, values: vector<Value>): simple_map::SimpleMap<Key, Value>
+

+
+
+
+

+Implementation
+
+
+
public fun new_from<Key: store, Value: store>(
+    keys: vector<Key>,
+    values: vector<Value>,
+): SimpleMap<Key, Value> {
+    let map = new();
+    add_all(&mut map, keys, values);
+    map
 }
 

 
@@ -192,6 +239,7 @@ Create an empty SimpleMap.
 ## Function `create`
 
 Create an empty SimpleMap.
+This function is deprecated, use new instead.
 
 
 
#[deprecated]
@@ -205,9 +253,7 @@ Create an empty SimpleMap.
 
 
 
public fun create<Key: store, Value: store>(): SimpleMap<Key, Value> {
-    SimpleMap {
-        data: vector::empty(),
-    }
+    new()
 }
 

 
@@ -332,6 +378,7 @@ Create an empty SimpleMap.
 
 ## Function `add`
 
+Add a key/value pair to the map. The key must not already exist.
 
 
 
public fun add<Key: store, Value: store>(map: &mut simple_map::SimpleMap<Key, Value>, key: Key, value: Value)
@@ -357,6 +404,38 @@ Create an empty SimpleMap.
 
 
 
+

+
+
+
+## Function `add_all`
+
+Add multiple key/value pairs to the map. The keys must not already exist.
+
+
+
public fun add_all<Key: store, Value: store>(map: &mut simple_map::SimpleMap<Key, Value>, keys: vector<Key>, values: vector<Value>)
+

+
+
+
+

+Implementation
+
+
+
public fun add_all<Key: store, Value: store>(
+    map: &mut SimpleMap<Key, Value>,
+    keys: vector<Key>,
+    values: vector<Value>,
+) {
+    assert!(vector::length(&keys) == vector::length(&values), error::invalid_argument(EMISMATCHED_LENGTHS));
+    vector::zip(keys, values, |key, value| {
+        add(map, key, value);
+    });
+}
+

+
+
+
 

 
 
@@ -525,6 +604,7 @@ using lambdas to destroy the individual keys and values.
 
 ## Function `remove`
 
+Remove a key/value pair from the map. The key must exist.
 
 
 
public fun remove<Key: store, Value: store>(map: &mut simple_map::SimpleMap<Key, Value>, key: &Key): (Key, Value)
@@ -593,6 +673,51 @@ using lambdas to destroy the individual keys and values.
 ## Specification
 
 
+
+
+
+
+
native fun spec_len<K, V>(t: SimpleMap<K, V>): num;
+

+
+
+
+
+
+
+
+
native fun spec_contains_key<K, V>(t: SimpleMap<K, V>, k: K): bool;
+

+
+
+
+
+
+
+
+
native fun spec_set<K, V>(t: SimpleMap<K, V>, k: K, v: V): SimpleMap<K, V>;
+

+
+
+
+
+
+
+
+
native fun spec_remove<K, V>(t: SimpleMap<K, V>, k: K): SimpleMap<K, V>;
+

+
+
+
+
+
+
+
+
native fun spec_get<K, V>(t: SimpleMap<K, V>, k: K): V;
+

+
+
+
 
 
 ### Struct `SimpleMap`
@@ -648,13 +773,12 @@ using lambdas to destroy the individual keys and values.
 
 
 
-
+
 
-### Function `create`
+### Function `new`
 
 
-
#[deprecated]
-public fun create<Key: store, Value: store>(): simple_map::SimpleMap<Key, Value>
+
public fun new<Key: store, Value: store>(): simple_map::SimpleMap<Key, Value>
 

 
 
@@ -665,12 +789,12 @@ using lambdas to destroy the individual keys and values.
 
 
 
-
+
 
-### Function `borrow`
+### Function `new_from`
 
 
-
public fun borrow<Key: store, Value: store>(map: &simple_map::SimpleMap<Key, Value>, key: &Key): &Value
+
public fun new_from<Key: store, Value: store>(keys: vector<Key>, values: vector<Value>): simple_map::SimpleMap<Key, Value>
 

 
 
@@ -681,12 +805,13 @@ using lambdas to destroy the individual keys and values.
 
 
 
-
+
 
-### Function `borrow_mut`
+### Function `create`
 
 
-
public fun borrow_mut<Key: store, Value: store>(map: &mut simple_map::SimpleMap<Key, Value>, key: &Key): &mut Value
+
#[deprecated]
+public fun create<Key: store, Value: store>(): simple_map::SimpleMap<Key, Value>
 

 
 
@@ -697,12 +822,12 @@ using lambdas to destroy the individual keys and values.
 
 
 
-
+
 
-### Function `contains_key`
+### Function `borrow`
 
 
-
public fun contains_key<Key: store, Value: store>(map: &simple_map::SimpleMap<Key, Value>, key: &Key): bool
+
public fun borrow<Key: store, Value: store>(map: &simple_map::SimpleMap<Key, Value>, key: &Key): &Value
 

 
 
@@ -713,12 +838,12 @@ using lambdas to destroy the individual keys and values.
 
 
 
-
+
 
-### Function `destroy_empty`
+### Function `borrow_mut`
 
 
-
public fun destroy_empty<Key: store, Value: store>(map: simple_map::SimpleMap<Key, Value>)
+
public fun borrow_mut<Key: store, Value: store>(map: &mut simple_map::SimpleMap<Key, Value>, key: &Key): &mut Value
 

 
 
@@ -729,12 +854,12 @@ using lambdas to destroy the individual keys and values.
 
 
 
-
+
 
-### Function `add`
+### Function `contains_key`
 
 
-
public fun add<Key: store, Value: store>(map: &mut simple_map::SimpleMap<Key, Value>, key: Key, value: Value)
+
public fun contains_key<Key: store, Value: store>(map: &simple_map::SimpleMap<Key, Value>, key: &Key): bool
 

 
 
@@ -745,70 +870,73 @@ using lambdas to destroy the individual keys and values.
 
 
 
-
+
 
-### Function `upsert`
+### Function `destroy_empty`
 
 
-
public fun upsert<Key: store, Value: store>(map: &mut simple_map::SimpleMap<Key, Value>, key: Key, value: Value): (option::Option<Key>, option::Option<Value>)
+
public fun destroy_empty<Key: store, Value: store>(map: simple_map::SimpleMap<Key, Value>)
 

 
 
 
 
 
pragma intrinsic;
-pragma opaque;
-ensures [abstract] !spec_contains_key(old(map), key) ==> option::is_none(result_1);
-ensures [abstract] !spec_contains_key(old(map), key) ==> option::is_none(result_2);
-ensures [abstract] spec_contains_key(map, key);
-ensures [abstract] spec_get(map, key) == value;
-ensures [abstract] spec_contains_key(old(map), key) ==> ((option::is_some(result_1)) && (option::spec_borrow(result_1) == key));
-ensures [abstract] spec_contains_key(old(map), key) ==> ((option::is_some(result_2)) && (option::spec_borrow(result_2) == spec_get(old(map), key)));
 

 
 
 
+
 
-
+### Function `add`
 
 
-
native fun spec_len<K, V>(t: SimpleMap<K, V>): num;
+
public fun add<Key: store, Value: store>(map: &mut simple_map::SimpleMap<Key, Value>, key: Key, value: Value)
 

 
 
 
 
-
-
-
-
native fun spec_contains_key<K, V>(t: SimpleMap<K, V>, k: K): bool;
+
pragma intrinsic;
 

 
 
 
+
 
-
+### Function `add_all`
 
 
-
native fun spec_set<K, V>(t: SimpleMap<K, V>, k: K, v: V): SimpleMap<K, V>;
+
public fun add_all<Key: store, Value: store>(map: &mut simple_map::SimpleMap<Key, Value>, keys: vector<Key>, values: vector<Value>)
 

 
 
 
 
-
+
pragma intrinsic;
+

 
 
-
native fun spec_remove<K, V>(t: SimpleMap<K, V>, k: K): SimpleMap<K, V>;
-

 
+
 
+### Function `upsert`
 
 
-
+
public fun upsert<Key: store, Value: store>(map: &mut simple_map::SimpleMap<Key, Value>, key: Key, value: Value): (option::Option<Key>, option::Option<Value>)
+

 
 
-
native fun spec_get<K, V>(t: SimpleMap<K, V>, k: K): V;
+
+
+
pragma intrinsic;
+pragma opaque;
+ensures [abstract] !spec_contains_key(old(map), key) ==> option::is_none(result_1);
+ensures [abstract] !spec_contains_key(old(map), key) ==> option::is_none(result_2);
+ensures [abstract] spec_contains_key(map, key);
+ensures [abstract] spec_get(map, key) == value;
+ensures [abstract] spec_contains_key(old(map), key) ==> ((option::is_some(result_1)) && (option::spec_borrow(result_1) == key));
+ensures [abstract] spec_contains_key(old(map), key) ==> ((option::is_some(result_2)) && (option::spec_borrow(result_2) == spec_get(old(map), key)));
 

 
 
diff --git a/aptos-move/framework/aptos-stdlib/sources/simple_map.move b/aptos-move/framework/aptos-stdlib/sources/simple_map.move
index 1d05791326513..828ac26a8e71d 100644
--- a/aptos-move/framework/aptos-stdlib/sources/simple_map.move
+++ b/aptos-move/framework/aptos-stdlib/sources/simple_map.move
@@ -13,6 +13,8 @@ module aptos_std::simple_map {
     const EKEY_ALREADY_EXISTS: u64 = 1;
     /// Map key is not found
     const EKEY_NOT_FOUND: u64 = 2;
+    /// Lengths of keys and values do not match
+    const EMISMATCHED_LENGTHS: u64 = 3;
 
     struct SimpleMap has copy, drop, store {
         data: vector>,
@@ -29,15 +31,26 @@ module aptos_std::simple_map {
 
     /// Create an empty SimpleMap.
     public fun new(): SimpleMap {
-        create()
+        SimpleMap {
+            data: vector::empty(),
+        }
+    }
+
+    /// Create a SimpleMap from a vector of keys and values. The keys must be unique.
+    public fun new_from(
+        keys: vector,
+        values: vector,
+    ): SimpleMap {
+        let map = new();
+        add_all(&mut map, keys, values);
+        map
     }
 
     #[deprecated]
     /// Create an empty SimpleMap.
+    /// This function is deprecated, use `new` instead.
     public fun create(): SimpleMap {
-        SimpleMap {
-            data: vector::empty(),
-        }
+        new()
     }
 
     public fun borrow(
@@ -73,6 +86,7 @@ module aptos_std::simple_map {
         vector::destroy_empty(data);
     }
 
+    /// Add a key/value pair to the map. The key must not already exist.
     public fun add(
         map: &mut SimpleMap,
         key: Key,
@@ -84,6 +98,18 @@ module aptos_std::simple_map {
         vector::push_back(&mut map.data, Element { key, value });
     }
 
+    /// Add multiple key/value pairs to the map. The keys must not already exist.
+    public fun add_all(
+        map: &mut SimpleMap,
+        keys: vector,
+        values: vector,
+    ) {
+        assert!(vector::length(&keys) == vector::length(&values), error::invalid_argument(EMISMATCHED_LENGTHS));
+        vector::zip(keys, values, |key, value| {
+            add(map, key, value);
+        });
+    }
+
     /// Insert key/value pair or update an existing key to a new value
     public fun upsert(
         map: &mut SimpleMap,
@@ -146,6 +172,7 @@ module aptos_std::simple_map {
         vector::destroy(values, |_v| dv(_v));
     }
 
+    /// Remove a key/value pair from the map. The key must exist.
     public fun remove(
         map: &mut SimpleMap,
         key: &Key,
@@ -174,7 +201,7 @@ module aptos_std::simple_map {
     }
 
     #[test]
-    public fun add_remove_many() {
+    public fun test_add_remove_many() {
         let map = create();
 
         assert!(length(&map) == 0, 0);
@@ -206,6 +233,23 @@ module aptos_std::simple_map {
         destroy_empty(map);
     }
 
+    #[test]
+    public fun test_add_all() {
+        let map = create();
+
+        assert!(length(&map) == 0, 0);
+        add_all(&mut map, vector[1, 2, 3], vector[10, 20, 30]);
+        assert!(length(&map) ==3, 1);
+        assert!(borrow(&map, &1) == &10, 2);
+        assert!(borrow(&map, &2) == &20, 3);
+        assert!(borrow(&map, &3) == &30, 4);
+
+        remove(&mut map, &1);
+        remove(&mut map, &2);
+        remove(&mut map, &3);
+        destroy_empty(map);
+    }
+
     #[test]
     public fun test_keys() {
         let map = create();
@@ -228,7 +272,7 @@ module aptos_std::simple_map {
 
     #[test]
     #[expected_failure]
-    public fun add_twice() {
+    public fun test_add_twice() {
         let map = create();
         add(&mut map, 3, 1);
         add(&mut map, 3, 1);
@@ -239,7 +283,7 @@ module aptos_std::simple_map {
 
     #[test]
     #[expected_failure]
-    public fun remove_twice() {
+    public fun test_remove_twice() {
         let map = create();
         add(&mut map, 3, 1);
         remove(&mut map, &3);
@@ -249,7 +293,7 @@ module aptos_std::simple_map {
     }
 
     #[test]
-    public fun upsert_test() {
+    public fun test_upsert_test() {
         let map = create();
         // test adding 3 elements using upsert
         upsert(&mut map, 1, 1 );
diff --git a/aptos-move/framework/aptos-stdlib/sources/simple_map.spec.move b/aptos-move/framework/aptos-stdlib/sources/simple_map.spec.move
index 2c8ea20bd5749..b5a4a4a984b95 100644
--- a/aptos-move/framework/aptos-stdlib/sources/simple_map.spec.move
+++ b/aptos-move/framework/aptos-stdlib/sources/simple_map.spec.move
@@ -24,6 +24,14 @@ spec aptos_std::simple_map {
         pragma intrinsic;
     }
 
+    spec new {
+        pragma intrinsic;
+    }
+
+    spec new_from {
+        pragma intrinsic;
+    }
+
     spec create {
         pragma intrinsic;
     }
@@ -48,6 +56,10 @@ spec aptos_std::simple_map {
         pragma intrinsic;
     }
 
+    spec add_all {
+        pragma intrinsic;
+    }
+
     spec remove {
         pragma intrinsic;
     }

From e53e19301f6ea79226602d4b95df3e9ef137b304 Mon Sep 17 00:00:00 2001
From: Kevin <105028215+movekevin@users.noreply.github.com>
Date: Sun, 18 Jun 2023 20:01:45 -0500
Subject: [PATCH 198/200] Add documentation and tests for type_info functions
 (#8706)

---
 .../framework/aptos-stdlib/doc/type_info.md   |  6 ++++-
 .../aptos-stdlib/sources/type_info.move       | 23 +++++++++++++++----
 2 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/aptos-move/framework/aptos-stdlib/doc/type_info.md b/aptos-move/framework/aptos-stdlib/doc/type_info.md
index 85fad0a2decb3..29985bd1b4536 100644
--- a/aptos-move/framework/aptos-stdlib/doc/type_info.md
+++ b/aptos-move/framework/aptos-stdlib/doc/type_info.md
@@ -193,6 +193,7 @@ return whichever ID was passed to aptos_framework::chain_id::initialize_fo
 
 ## Function `type_of`
 
+Return the TypeInfo struct containing  for the type T.
 
 
 
public fun type_of<T>(): type_info::TypeInfo
@@ -215,6 +216,9 @@ return whichever ID was passed to aptos_framework::chain_id::initialize_fo
 
 ## Function `type_name`
 
+Return the human readable string for the type, including the address, module name, and any type arguments.
+Example: 0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>
+Or: 0x1::table::Table<0x1::string::String, 0x1::string::String>
 
 
 
public fun type_name<T>(): string::String
@@ -226,7 +230,7 @@ return whichever ID was passed to aptos_framework::chain_id::initialize_fo
 Implementation
 
 
-
public native fun type_name<T>(): string::String;
+
public native fun type_name<T>(): String;
 

 
 
diff --git a/aptos-move/framework/aptos-stdlib/sources/type_info.move b/aptos-move/framework/aptos-stdlib/sources/type_info.move
index c758476426b17..22f97b324df9b 100644
--- a/aptos-move/framework/aptos-stdlib/sources/type_info.move
+++ b/aptos-move/framework/aptos-stdlib/sources/type_info.move
@@ -1,7 +1,7 @@
 module aptos_std::type_info {
     use std::bcs;
-    use std::string;
     use std::features;
+    use std::string::{Self, String};
     use std::vector;
 
     //
@@ -47,9 +47,13 @@ module aptos_std::type_info {
         chain_id_internal()
     }
 
+    /// Return the `TypeInfo` struct containing  for the type `T`.
     public native fun type_of(): TypeInfo;
 
-    public native fun type_name(): string::String;
+    /// Return the human readable string for the type, including the address, module name, and any type arguments.
+    /// Example: 0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>
+    /// Or: 0x1::table::Table<0x1::string::String, 0x1::string::String>
+    public native fun type_name(): String;
 
     native fun chain_id_internal(): u8;
 
@@ -65,14 +69,25 @@ module aptos_std::type_info {
         vector::length(&bcs::to_bytes(val_ref))
     }
 
+    #[test_only]
+    use aptos_std::table::Table;
+
     #[test]
-    fun test() {
+    fun test_type_of() {
         let type_info = type_of();
         assert!(account_address(&type_info) == @aptos_std, 0);
         assert!(module_name(&type_info) == b"type_info", 1);
         assert!(struct_name(&type_info) == b"TypeInfo", 2);
     }
 
+    #[test]
+    fun test_type_of_with_type_arg() {
+        let type_info = type_of>();
+        assert!(account_address(&type_info) == @aptos_std, 0);
+        assert!(module_name(&type_info) == b"table", 1);
+        assert!(struct_name(&type_info) == b"Table<0x1::string::String, 0x1::string::String>", 2);
+    }
+
     #[test(fx = @std)]
     fun test_chain_id(fx: signer) {
         // We need to enable the feature in order for the native call to be allowed.
@@ -84,7 +99,7 @@ module aptos_std::type_info {
 
     #[test]
     fun test_type_name() {
-        use aptos_std::table::Table;
+
 
         assert!(type_name() == string::utf8(b"bool"), 0);
         assert!(type_name() == string::utf8(b"u8"), 1);

From c8a21a2601e8ca5fccf825f1e9c1d55e0617c849 Mon Sep 17 00:00:00 2001
From: qdrs 
Date: Tue, 20 Jun 2023 19:49:34 +0800
Subject: [PATCH 199/200] dearbitrary derivation for move types

---
 Cargo.lock                                    | 20 ++++++++
 .../move/move-binary-format/Cargo.toml        |  5 +-
 .../move-binary-format/src/file_format.rs     | 49 ++++++++++---------
 third_party/move/move-core/types/Cargo.toml   | 12 ++---
 .../move-core/types/src/account_address.rs    |  2 +-
 .../move/move-core/types/src/identifier.rs    |  2 +-
 .../move-core/types/src/language_storage.rs   |  5 +-
 .../move/move-core/types/src/metadata.rs      |  2 +-
 third_party/move/move-core/types/src/u256.rs  |  7 +++
 third_party/move/move-core/types/src/value.rs |  4 +-
 10 files changed, 69 insertions(+), 39 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 3f7163200ee68..86a798b62ae54 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -5360,6 +5360,14 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "dearbitrary"
+version = "1.2.0"
+source = "git+ssh://git@github.com/otter-sec/dearbitrary.git#08de30e99c6c6b9a3d3f4959f22bb245faa8da8b"
+dependencies = [
+ "derive_dearbitrary",
+]
+
 [[package]]
 name = "debug-ignore"
 version = "1.0.3"
@@ -5397,6 +5405,16 @@ dependencies = [
  "syn 2.0.18",
 ]
 
+[[package]]
+name = "derive_dearbitrary"
+version = "1.2.0"
+source = "git+ssh://git@github.com/otter-sec/dearbitrary.git#08de30e99c6c6b9a3d3f4959f22bb245faa8da8b"
+dependencies = [
+ "proc-macro2 1.0.59",
+ "quote 1.0.28",
+ "syn 1.0.105",
+]
+
 [[package]]
 name = "derive_more"
 version = "0.99.17"
@@ -8110,6 +8128,7 @@ version = "0.0.3"
 dependencies = [
  "anyhow",
  "arbitrary 1.3.0",
+ "dearbitrary",
  "indexmap",
  "move-core-types",
  "once_cell",
@@ -8288,6 +8307,7 @@ dependencies = [
  "anyhow",
  "arbitrary 1.3.0",
  "bcs 0.1.4",
+ "dearbitrary",
  "ethnum",
  "hex",
  "num",
diff --git a/third_party/move/move-binary-format/Cargo.toml b/third_party/move/move-binary-format/Cargo.toml
index 248035640f737..4a2d3602142a9 100644
--- a/third_party/move/move-binary-format/Cargo.toml
+++ b/third_party/move/move-binary-format/Cargo.toml
@@ -11,8 +11,9 @@ edition = "2021"
 
 [dependencies]
 anyhow = "1.0.52"
-arbitrary = { version = "1.1.7", optional = true, features = ["derive"] }
 indexmap = "1.9.3"
+arbitrary = { version = "1.3.0", optional = true, features = ["derive"] }
+dearbitrary = { git = "ssh://git@github.com/otter-sec/dearbitrary.git", features = ["derive"], optional = true }
 move-core-types = { path = "../move-core/types" }
 once_cell = "1.7.2"
 proptest = { version = "1.0.0", optional = true }
@@ -29,4 +30,4 @@ serde_json = "1.0.64"
 
 [features]
 default = []
-fuzzing = ["proptest", "proptest-derive", "arbitrary", "move-core-types/fuzzing"]
+fuzzing = ["proptest", "proptest-derive", "arbitrary", "move-core-types/fuzzing", "dearbitrary"]
diff --git a/third_party/move/move-binary-format/src/file_format.rs b/third_party/move/move-binary-format/src/file_format.rs
index c23bd86ff1980..b0cdde0524d0a 100644
--- a/third_party/move/move-binary-format/src/file_format.rs
+++ b/third_party/move/move-binary-format/src/file_format.rs
@@ -60,7 +60,7 @@ macro_rules! define_index {
         #[derive(Clone, Copy, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
         #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
         #[cfg_attr(any(test, feature = "fuzzing"), proptest(no_params))]
-        #[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+        #[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
         #[doc=$comment]
         pub struct $name(pub TableIndex);
 
@@ -217,7 +217,7 @@ pub const NO_TYPE_ARGUMENTS: SignatureIndex = SignatureIndex(0);
 #[derive(Clone, Debug, Eq, Hash, PartialEq, PartialOrd, Ord)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(no_params))]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct ModuleHandle {
     /// Index into the `AddressIdentifierIndex`. Identifies module-holding account's address.
     pub address: AddressIdentifierIndex,
@@ -241,7 +241,7 @@ pub struct ModuleHandle {
 #[derive(Clone, Debug, Eq, Hash, PartialEq, PartialOrd, Ord)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(no_params))]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct StructHandle {
     /// The module that defines the type.
     pub module: ModuleHandleIndex,
@@ -265,7 +265,7 @@ impl StructHandle {
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, PartialOrd, Ord, Serialize, Deserialize)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(no_params))]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct StructTypeParameter {
     /// The type parameter constraints.
     pub constraints: AbilitySet,
@@ -283,7 +283,7 @@ pub struct StructTypeParameter {
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(params = "usize"))]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct FunctionHandle {
     /// The module that defines the function.
     pub module: ModuleHandleIndex,
@@ -301,7 +301,7 @@ pub struct FunctionHandle {
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(no_params))]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct FieldHandle {
     pub owner: StructDefinitionIndex,
     pub field: MemberCount,
@@ -314,7 +314,7 @@ pub struct FieldHandle {
 #[derive(Clone, Debug, Eq, PartialEq)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(no_params))]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub enum StructFieldInformation {
     Native,
     Declared(Vec),
@@ -332,7 +332,7 @@ pub enum StructFieldInformation {
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(no_params))]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct StructDefInstantiation {
     pub def: StructDefinitionIndex,
     pub type_parameters: SignatureIndex,
@@ -342,7 +342,7 @@ pub struct StructDefInstantiation {
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(no_params))]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct FunctionInstantiation {
     pub handle: FunctionHandleIndex,
     pub type_parameters: SignatureIndex,
@@ -357,7 +357,7 @@ pub struct FunctionInstantiation {
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(no_params))]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct FieldInstantiation {
     pub handle: FieldHandleIndex,
     pub type_parameters: SignatureIndex,
@@ -368,7 +368,7 @@ pub struct FieldInstantiation {
 #[derive(Clone, Debug, Eq, PartialEq)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(no_params))]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct StructDefinition {
     /// The `StructHandle` for this `StructDefinition`. This has the name and the abilities
     /// for the type.
@@ -401,7 +401,7 @@ impl StructDefinition {
 #[derive(Clone, Debug, Eq, PartialEq)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(no_params))]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct FieldDefinition {
     /// The name of the field.
     pub name: IdentifierIndex,
@@ -414,7 +414,7 @@ pub struct FieldDefinition {
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq, PartialOrd, Ord, Serialize, Deserialize)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(no_params))]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 #[repr(u8)]
 pub enum Visibility {
     /// Accessible within its defining module only.
@@ -451,7 +451,7 @@ impl std::convert::TryFrom for Visibility {
 #[derive(Clone, Debug, Default, Eq, PartialEq)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(params = "usize"))]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct FunctionDefinition {
     /// The prototype of the function (module, name, signature).
     pub function: FunctionHandleIndex,
@@ -502,7 +502,7 @@ impl FunctionDefinition {
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(no_params))]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct TypeSignature(pub SignatureToken);
 
 // TODO: remove at some point or move it in the front end (language/move-ir-compiler)
@@ -511,7 +511,7 @@ pub struct TypeSignature(pub SignatureToken);
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(params = "usize"))]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct FunctionSignature {
     /// The list of return types.
     #[cfg_attr(
@@ -536,7 +536,7 @@ pub struct FunctionSignature {
 #[derive(Clone, Debug, Default, Eq, Hash, PartialEq, Ord, PartialOrd)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(params = "usize"))]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct Signature(
     #[cfg_attr(
         any(test, feature = "fuzzing"),
@@ -567,7 +567,7 @@ pub type TypeParameterIndex = u16;
 #[repr(u8)]
 #[derive(Debug, Clone, Eq, Copy, Hash, Ord, PartialEq, PartialOrd)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub enum Ability {
     /// Allows values of types with this ability to be copied, via CopyLoc or ReadRef
     Copy = 0x1,
@@ -625,7 +625,7 @@ impl Ability {
 
 /// A set of `Ability`s
 #[derive(Clone, Eq, Copy, Hash, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct AbilitySet(u8);
 
 impl AbilitySet {
@@ -856,7 +856,7 @@ impl Arbitrary for AbilitySet {
 /// A SignatureToken can express more types than the VM can handle safely, and correctness is
 /// enforced by the verifier.
 #[derive(Clone, Eq, Hash, Ord, PartialEq, PartialOrd)]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub enum SignatureToken {
     /// Boolean, `true` or `false`.
     Bool,
@@ -1134,7 +1134,7 @@ impl SignatureToken {
 /// A `Constant` is a serialized value along with its type. That type will be deserialized by the
 /// loader/evauluator
 #[derive(Clone, Debug, Eq, PartialEq, Hash)]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct Constant {
     pub type_: SignatureToken,
     pub data: Vec,
@@ -1144,7 +1144,7 @@ pub struct Constant {
 #[derive(Clone, Debug, Default, Eq, PartialEq)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(params = "usize"))]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct CodeUnit {
     /// List of locals type. All locals are typed.
     pub locals: SignatureIndex,
@@ -1164,7 +1164,7 @@ pub struct CodeUnit {
 #[derive(Clone, Hash, Eq, VariantCount, PartialEq)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(no_params))]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub enum Bytecode {
     /// Pop and discard the value at the top of the stack.
     /// The value on the stack must be an copyable type.
@@ -1808,6 +1808,7 @@ impl Bytecode {
 /// A CompiledScript defines the constant pools (string, address, signatures, etc.), the handle
 /// tables (external code references) and it has a `main` definition.
 #[derive(Clone, Default, Eq, PartialEq, Debug)]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct CompiledScript {
     /// Version number found during deserialization
     pub version: u32,
@@ -1850,7 +1851,7 @@ impl CompiledScript {
 ///
 /// A module is published as a single entry and it is retrieved as a single blob.
 #[derive(Clone, Debug, Default, Eq, PartialEq)]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct CompiledModule {
     /// Version number found during deserialization
     pub version: u32,
diff --git a/third_party/move/move-core/types/Cargo.toml b/third_party/move/move-core/types/Cargo.toml
index fbfd938df03d0..af22c7d99c63e 100644
--- a/third_party/move/move-core/types/Cargo.toml
+++ b/third_party/move/move-core/types/Cargo.toml
@@ -11,14 +11,15 @@ edition = "2021"
 
 [dependencies]
 anyhow = "1.0.52"
-arbitrary = { version = "1.1.7", features = [ "derive_arbitrary"], optional = true }
+arbitrary = { version = "1.3.0", optional = true, features = ["derive"] }
+dearbitrary = { git = "ssh://git@github.com/otter-sec/dearbitrary.git", features = ["derive"], optional = true }
 ethnum = "1.0.4"
 hex = "0.4.3"
 num = "0.4.0"
 once_cell = "1.7.2"
 primitive-types = { version = "0.10.1", features = ["impl-serde"] }
-proptest = { version = "1.0.0", default-features = false, optional = true }
-proptest-derive = { version = "0.3.0", default-features = false, optional = true }
+proptest = { version = "1.0.0", optional = true }
+proptest-derive = { version = "0.3.0", optional = true }
 rand = "0.8.3"
 ref-cast = "1.0.6"
 serde = { version = "1.0.124", default-features = false }
@@ -28,12 +29,11 @@ uint = "0.9.4"
 bcs = { workspace = true }
 
 [dev-dependencies]
-arbitrary = { version = "1.1.7", features = [ "derive_arbitrary"] }
-proptest = "1.0.0"
+proptest = "1.1.0"
 proptest-derive = "0.3.0"
 regex = "1.5.5"
 serde_json = "1.0.64"
 
 [features]
 default = []
-fuzzing = ["proptest", "proptest-derive", "arbitrary"]
+fuzzing = ["proptest", "proptest-derive", "arbitrary", "dearbitrary"]
diff --git a/third_party/move/move-core/types/src/account_address.rs b/third_party/move/move-core/types/src/account_address.rs
index cee0ee8a84c26..f9b8f35ebea42 100644
--- a/third_party/move/move-core/types/src/account_address.rs
+++ b/third_party/move/move-core/types/src/account_address.rs
@@ -11,7 +11,7 @@ use std::{convert::TryFrom, fmt, str::FromStr};
 /// A struct that represents an account address.
 #[derive(Ord, PartialOrd, Eq, PartialEq, Hash, Clone, Copy)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(proptest_derive::Arbitrary))]
-#[cfg_attr(any(test, feature = "fuzzing"), derive(arbitrary::Arbitrary))]
+#[cfg_attr(any(test, feature = "fuzzing"), derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct AccountAddress([u8; AccountAddress::LENGTH]);
 
 impl AccountAddress {
diff --git a/third_party/move/move-core/types/src/identifier.rs b/third_party/move/move-core/types/src/identifier.rs
index d4cef553a26c2..2781f8c50d27b 100644
--- a/third_party/move/move-core/types/src/identifier.rs
+++ b/third_party/move/move-core/types/src/identifier.rs
@@ -89,7 +89,7 @@ pub(crate) static ALLOWED_NO_SELF_IDENTIFIERS: &str =
 ///
 /// For more details, see the module level documentation.
 #[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize, Deserialize)]
-#[cfg_attr(any(test, feature = "fuzzing"), derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct Identifier(Box);
 // An identifier cannot be mutated so use Box instead of String -- it is 1 word smaller.
 
diff --git a/third_party/move/move-core/types/src/language_storage.rs b/third_party/move/move-core/types/src/language_storage.rs
index 000e9c9160013..119f2e56e41d2 100644
--- a/third_party/move/move-core/types/src/language_storage.rs
+++ b/third_party/move/move-core/types/src/language_storage.rs
@@ -23,7 +23,7 @@ pub const RESOURCE_TAG: u8 = 1;
 pub const CORE_CODE_ADDRESS: AccountAddress = AccountAddress::ONE;
 
 #[derive(Serialize, Deserialize, Debug, PartialEq, Hash, Eq, Clone, PartialOrd, Ord)]
-#[cfg_attr(any(test, feature = "fuzzing"), derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub enum TypeTag {
     // alias for compatibility with old json serialized data.
     #[serde(rename = "bool", alias = "Bool")]
@@ -102,7 +102,7 @@ impl FromStr for TypeTag {
 }
 
 #[derive(Serialize, Deserialize, Debug, PartialEq, Hash, Eq, Clone, PartialOrd, Ord)]
-#[cfg_attr(any(test, feature = "fuzzing"), derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct StructTag {
     pub address: AccountAddress,
     pub module: Identifier,
@@ -203,6 +203,7 @@ impl ResourceKey {
 /// the struct tag
 #[derive(Serialize, Deserialize, Debug, PartialEq, Hash, Eq, Clone, PartialOrd, Ord)]
 #[cfg_attr(any(test, feature = "fuzzing"), derive(Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 #[cfg_attr(any(test, feature = "fuzzing"), proptest(no_params))]
 pub struct ModuleId {
     address: AccountAddress,
diff --git a/third_party/move/move-core/types/src/metadata.rs b/third_party/move/move-core/types/src/metadata.rs
index 9191615d9c39d..e14fdb97ee194 100644
--- a/third_party/move/move-core/types/src/metadata.rs
+++ b/third_party/move/move-core/types/src/metadata.rs
@@ -3,7 +3,7 @@
 
 /// Representation of metadata,
 #[derive(Clone, PartialEq, Eq, Debug)]
-#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub struct Metadata {
     /// The key identifying the type of metadata.
     pub key: Vec,
diff --git a/third_party/move/move-core/types/src/u256.rs b/third_party/move/move-core/types/src/u256.rs
index b73647ea06fe8..44153b1c169b8 100644
--- a/third_party/move/move-core/types/src/u256.rs
+++ b/third_party/move/move-core/types/src/u256.rs
@@ -705,6 +705,13 @@ impl<'a> arbitrary::Arbitrary<'a> for U256 {
     }
 }
 
+#[cfg(any(test, feature = "fuzzing"))]
+impl dearbitrary::Dearbitrary for U256 {
+    fn dearbitrary(&self, dearbitrator: &mut dearbitrary::Dearbitrator) {
+        self.to_le_bytes().dearbitrary(dearbitrator)
+    }
+}
+
 #[test]
 fn wrapping_add() {
     // a + b overflows U256::MAX by 100
diff --git a/third_party/move/move-core/types/src/value.rs b/third_party/move/move-core/types/src/value.rs
index 4820c2cd6213f..c9354653c93f3 100644
--- a/third_party/move/move-core/types/src/value.rs
+++ b/third_party/move/move-core/types/src/value.rs
@@ -29,7 +29,7 @@ pub const MOVE_STRUCT_TYPE: &str = "type";
 pub const MOVE_STRUCT_FIELDS: &str = "fields";
 
 #[derive(Debug, PartialEq, Eq, Clone)]
-#[cfg_attr(any(test, feature = "fuzzing"), derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub enum MoveStruct {
     /// The representation used by the MoveVM
     Runtime(Vec),
@@ -43,7 +43,7 @@ pub enum MoveStruct {
 }
 
 #[derive(Debug, PartialEq, Eq, Clone)]
-#[cfg_attr(any(test, feature = "fuzzing"), derive(arbitrary::Arbitrary))]
+#[cfg_attr(feature = "fuzzing", derive(arbitrary::Arbitrary,dearbitrary::Dearbitrary))]
 pub enum MoveValue {
     U8(u8),
     U64(u64),

From fec84ef8459e54368f42ae05d923ee17a776a3d8 Mon Sep 17 00:00:00 2001
From: qdrs 
Date: Tue, 20 Jun 2023 23:06:13 +0800
Subject: [PATCH 200/200] use https git dep for otter dearbitrary

---
 Cargo.lock                                     | 4 ++--
 third_party/move/move-binary-format/Cargo.toml | 2 +-
 third_party/move/move-core/types/Cargo.toml    | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 86a798b62ae54..6084e94c3363b 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -5363,7 +5363,7 @@ dependencies = [
 [[package]]
 name = "dearbitrary"
 version = "1.2.0"
-source = "git+ssh://git@github.com/otter-sec/dearbitrary.git#08de30e99c6c6b9a3d3f4959f22bb245faa8da8b"
+source = "git+https://github.com/otter-sec/dearbitrary#08de30e99c6c6b9a3d3f4959f22bb245faa8da8b"
 dependencies = [
  "derive_dearbitrary",
 ]
@@ -5408,7 +5408,7 @@ dependencies = [
 [[package]]
 name = "derive_dearbitrary"
 version = "1.2.0"
-source = "git+ssh://git@github.com/otter-sec/dearbitrary.git#08de30e99c6c6b9a3d3f4959f22bb245faa8da8b"
+source = "git+https://github.com/otter-sec/dearbitrary#08de30e99c6c6b9a3d3f4959f22bb245faa8da8b"
 dependencies = [
  "proc-macro2 1.0.59",
  "quote 1.0.28",
diff --git a/third_party/move/move-binary-format/Cargo.toml b/third_party/move/move-binary-format/Cargo.toml
index 4a2d3602142a9..9672cc7d1d448 100644
--- a/third_party/move/move-binary-format/Cargo.toml
+++ b/third_party/move/move-binary-format/Cargo.toml
@@ -13,7 +13,7 @@ edition = "2021"
 anyhow = "1.0.52"
 indexmap = "1.9.3"
 arbitrary = { version = "1.3.0", optional = true, features = ["derive"] }
-dearbitrary = { git = "ssh://git@github.com/otter-sec/dearbitrary.git", features = ["derive"], optional = true }
+dearbitrary = { git = "https://github.com/otter-sec/dearbitrary", features = ["derive"], optional = true }
 move-core-types = { path = "../move-core/types" }
 once_cell = "1.7.2"
 proptest = { version = "1.0.0", optional = true }
diff --git a/third_party/move/move-core/types/Cargo.toml b/third_party/move/move-core/types/Cargo.toml
index af22c7d99c63e..93635947368d4 100644
--- a/third_party/move/move-core/types/Cargo.toml
+++ b/third_party/move/move-core/types/Cargo.toml
@@ -12,7 +12,7 @@ edition = "2021"
 [dependencies]
 anyhow = "1.0.52"
 arbitrary = { version = "1.3.0", optional = true, features = ["derive"] }
-dearbitrary = { git = "ssh://git@github.com/otter-sec/dearbitrary.git", features = ["derive"], optional = true }
+dearbitrary = { git = "https://github.com/otter-sec/dearbitrary", features = ["derive"], optional = true }
 ethnum = "1.0.4"
 hex = "0.4.3"
 num = "0.4.0"