@@ -40,15 +40,23 @@ pub enum ShareValidationError {
4040 BadExtranonceSize ,
4141}
4242
43- /// Tracks share validation state for a specific channel (Extended or Standard).
43+ /// Tracks share validation and acceptance state for a specific channel (Extended or Standard).
4444///
45- /// Used only on Mining Clients.
46- /// Keeps statistics and state for shares submitted through the channel:
45+ /// Used only on Mining Clients. Share accounting is split into two phases:
46+ ///
47+ /// **Validation phase** (updated by [`validate_share`] via [`track_validated_share`]):
48+ /// - hashes of seen shares (for duplicate detection)
4749/// - last received share's sequence number
48- /// - total accepted shares
50+ /// - highest difficulty seen in validated shares
51+ ///
52+ /// **Acceptance phase** (updated by the application layer via [`on_share_acknowledgement`]):
53+ /// - total accepted shares (confirmed by upstream [`SubmitSharesSuccess`])
4954/// - cumulative work from accepted shares
50- /// - hashes of seen shares (for duplicate detection)
51- /// - highest difficulty seen in accepted shares
55+ ///
56+ /// [`validate_share`]: super::extended::ExtendedChannel::validate_share
57+ /// [`track_validated_share`]: ShareAccounting::track_validated_share
58+ /// [`on_share_acknowledgement`]: ShareAccounting::on_share_acknowledgement
59+ /// [`SubmitSharesSuccess`]: mining_sv2::SubmitSharesSuccess
5260#[ derive( Clone , Debug ) ]
5361pub struct ShareAccounting {
5462 last_share_sequence_number : u32 ,
@@ -76,20 +84,30 @@ impl ShareAccounting {
7684 }
7785 }
7886
79- /// Updates the accounting state with a newly accepted share.
87+ /// Updates acceptance accounting based on a [`SubmitSharesSuccess`] message from the
88+ /// upstream server.
8089///
81- /// - Increments share count and total work.
82- /// - Updates last share sequence number.
83- /// - Records share hash to detect duplicates.
84- pub fn update_share_accounting (
90+ /// This should be called by the application layer when it receives upstream confirmation
91+ /// that shares were accepted. It is intentionally **not** called from [`validate_share`] —
92+ /// local validation only tracks the share for duplicate detection (via
93+ /// [`track_validated_share`]).
94+ pub fn on_share_acknowledgement (
8595 & mut self ,
86- share_work : f64 ,
87- share_sequence_number : u32 ,
88- share_hash : Hash ,
96+ new_submits_accepted_count : u32 ,
97+ new_shares_sum : f64 ,
8998 ) {
99+ self . shares_accepted += new_submits_accepted_count;
100+ self . share_work_sum += new_shares_sum;
101+ }
102+
103+ /// Records a share that passed local validation.
104+ ///
105+ /// Adds the hash to the seen set for duplicate detection and updates the last sequence
106+ /// number. Called from [`validate_share`] — does **not** count the share as accepted.
107+ /// Acceptance accounting is deferred to [`on_share_acknowledgement`], which should be
108+ /// called when the upstream server confirms via [`SubmitSharesSuccess`].
109+ pub fn track_validated_share ( & mut self , share_sequence_number : u32 , share_hash : Hash ) {
90110 self . last_share_sequence_number = share_sequence_number;
91- self . shares_accepted += 1 ;
92- self . share_work_sum += share_work;
93111 self . seen_shares . insert ( share_hash) ;
94112 }
95113
0 commit comments