1  // Copyright (c) 2025 ADnet Contributors
  2  // This file is part of the AlphaOS library.
  3  
  4  // Licensed under the Apache License, Version 2.0 (the "License");
  5  // you may not use this file except in compliance with the License.
  6  // You may obtain a copy of the License at:
  7  
  8  // http://www.apache.org/licenses/LICENSE-2.0
  9  
 10  // Unless required by applicable law or agreed to in writing, software
 11  // distributed under the License is distributed on an "AS IS" BASIS,
 12  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 13  // See the License for the specific language governing permissions and
 14  // limitations under the License.
 15  
 16  use alphavm::{
 17      ledger::{
 18          Block,
 19          PendingBlock,
 20          Transaction,
 21          committee::Committee,
 22          narwhal::{BatchCertificate, Data, Subdag, Transmission, TransmissionID},
 23          puzzle::{Solution, SolutionID},
 24      },
 25      prelude::{Address, ConsensusVersion, Field, Network, Result},
 26  };
 27  
 28  use indexmap::IndexMap;
 29  use std::{fmt::Debug, ops::Range};
 30  
 31  #[async_trait]
 32  pub trait LedgerService<N: Network>: Debug + Send + Sync {
 33      /// Returns the latest round in the ledger.
 34      fn latest_round(&self) -> u64;
 35  
 36      /// Returns the latest block height in the ledger.
 37      fn latest_block_height(&self) -> u32;
 38  
 39      /// Returns the latest block in the ledger.
 40      fn latest_block(&self) -> Block<N>;
 41  
 42      /// Returns the latest restrictions ID in the ledger.
 43      fn latest_restrictions_id(&self) -> Field<N>;
 44  
 45      /// Returns the latest cached leader and its associated round.
 46      fn latest_leader(&self) -> Option<(u64, Address<N>)>;
 47  
 48      /// Updates the latest cached leader and its associated round.
 49      fn update_latest_leader(&self, round: u64, leader: Address<N>);
 50  
 51      /// Returns `true` if the given block height exists in the ledger.
 52      fn contains_block_height(&self, height: u32) -> bool;
 53  
 54      /// Returns the block height for the given block hash, if it exists.
 55      fn get_block_height(&self, hash: &N::BlockHash) -> Result<u32>;
 56  
 57      /// Returns the block hash for the given block height, if it exists.
 58      fn get_block_hash(&self, height: u32) -> Result<N::BlockHash>;
 59  
 60      /// Returns the block round for the given block height, if it exists.
 61      fn get_block_round(&self, height: u32) -> Result<u64>;
 62  
 63      /// Returns the block for the given block height.
 64      fn get_block(&self, height: u32) -> Result<Block<N>>;
 65  
 66      /// Returns the blocks in the given block range.
 67      /// The range is inclusive of the start and exclusive of the end.
 68      fn get_blocks(&self, heights: Range<u32>) -> Result<Vec<Block<N>>>;
 69  
 70      /// Returns the solution for the given solution ID.
 71      fn get_solution(&self, solution_id: &SolutionID<N>) -> Result<Solution<N>>;
 72  
 73      /// Returns the unconfirmed transaction for the given transaction ID.
 74      fn get_unconfirmed_transaction(&self, transaction_id: N::TransactionID) -> Result<Transaction<N>>;
 75  
 76      /// Returns the batch certificate for the given batch certificate ID.
 77      fn get_batch_certificate(&self, certificate_id: &Field<N>) -> Result<BatchCertificate<N>>;
 78  
 79      /// Returns the current committee.
 80      fn current_committee(&self) -> Result<Committee<N>>;
 81  
 82      /// Returns the committee for the given round.
 83      fn get_committee_for_round(&self, round: u64) -> Result<Committee<N>>;
 84  
 85      /// Returns the committee lookback for the given round.
 86      fn get_committee_lookback_for_round(&self, round: u64) -> Result<Committee<N>>;
 87  
 88      /// Returns `true` if the ledger contains the given certificate ID.
 89      fn contains_certificate(&self, certificate_id: &Field<N>) -> Result<bool>;
 90  
 91      /// Returns `true` if the ledger contains the given transmission ID.
 92      fn contains_transmission(&self, transmission_id: &TransmissionID<N>) -> Result<bool>;
 93  
 94      /// Ensures that the given transmission is not a fee and matches the given transmission ID.
 95      fn ensure_transmission_is_well_formed(
 96          &self,
 97          transmission_id: TransmissionID<N>,
 98          transmission: &mut Transmission<N>,
 99      ) -> Result<()>;
100  
101      /// Checks the given solution is well-formed.
102      async fn check_solution_basic(&self, solution_id: SolutionID<N>, solution: Data<Solution<N>>) -> Result<()>;
103  
104      /// Checks the given transaction is well-formed and unique.
105      async fn check_transaction_basic(
106          &self,
107          transaction_id: N::TransactionID,
108          transaction: Transaction<N>,
109      ) -> Result<()>;
110  
111      /// Checks that the subDAG in a given block is valid, but does not fully verify the block.
112      fn check_block_subdag(&self, block: Block<N>, prefix: &[PendingBlock<N>]) -> Result<PendingBlock<N>>;
113  
114      /// Takes a pending block and performs the remaining checks to full verify it.
115      fn check_block_content(&self, _block: PendingBlock<N>) -> Result<Block<N>>;
116  
117      /// Checks the given block is valid next block.
118      fn check_next_block(&self, block: &Block<N>) -> Result<()>;
119  
120      /// Returns a candidate for the next block in the ledger, using a committed subdag and its transmissions.
121      #[cfg(feature = "ledger-write")]
122      fn prepare_advance_to_next_quorum_block(
123          &self,
124          subdag: Subdag<N>,
125          transmissions: IndexMap<TransmissionID<N>, Transmission<N>>,
126      ) -> Result<Block<N>>;
127  
128      /// Adds the given block as the next block in the ledger.
129      #[cfg(feature = "ledger-write")]
130      fn advance_to_next_block(&self, block: &Block<N>) -> Result<()>;
131  
132      /// Returns the spent cost for a transaction in microcredits.
133      fn transaction_spend_in_microcredits(
134          &self,
135          transaction: &Transaction<N>,
136          consensus_version: ConsensusVersion,
137      ) -> Result<u64>;
138  }