Struct Engine 

pub struct Engine { /* private fields */ }

Same engine for embedded consumers and the standalone service. No signer or user decryption key is present. One synchronization coordinator admits work; the archive lock is never held while waiting for a peer.

Implementations

impl Engine

pub fn with_source(self, source: Arc<dyn ChainSource>) -> Result<Self, Error>

Attach a verifier after archive ownership has been acquired. The CLI uses this order before opening any mutable header-cache files.

pub fn open( path: &Path, config: ArchiveConfig, source: Option<Arc<dyn ChainSource>>, ) -> Result<Self, Error>

pub fn status(&self) -> Result<ArchiveStatus, Error>

pub fn record(&self, txid: Txid) -> Result<Option<ArchivedRecord>, Error>

pub fn wire_page( &self, cursor: Option<&WireCursor>, limit: u32, ) -> Result<WirePage, Error>

Read a bounded Wire view without network or a second scan. All fields and coverage come from one archive critical section. Concurrent writes invalidate continuation tokens instead of silently mixing snapshots. Restart invalidates tokens even if the archive has not changed.

pub fn object_status(&self, root: Txid) -> Result<Option<ObjectStatus>, Error>

pub fn register_names( &self, genesis: Txid, block: ChainPoint, ) -> Result<NamesStatus, Error>

Register an explicitly selected, authenticated Names genesis in a fully scanned block. No registry is chosen implicitly and no source is called.

pub fn names_step(&self, genesis: Txid) -> Result<NamesStep, Error>

Reconcile retained undo, then project at most one fully scanned block. Missing scan coverage leaves progress unchanged. Missing selected commit placement refuses the step. SQL and state changes share the archive lock.

pub fn names_view( &self, genesis: Txid, cursor: Option<&NamesCursor>, limit: u32, ) -> Result<NamesPage, Error>

Read normalized Names state without registration, projection or source access. Metadata and rows share one archive lock. Any committed event or Engine restart invalidates continuation; discard partial traversals.

pub fn names_status(&self, genesis: Txid) -> Result<Option<NamesStatus>, Error>

Orphaned projection checkpoints are refused until a maintenance step reconciles them; an orphaned genesis always requires explicit action.

pub fn names_resolve( &self, genesis: Txid, name: &Name, ) -> Result<NamesResolution, Error>

pub fn maintain_next_names( &self, cancelled: &AtomicBool, ) -> Result<Option<NamesStep>, Error>

Maintain explicitly registered Names projections without source calls. Inspect at most 128 registrations and attempt at most one projection step. The cursor advances before each attempt, including failures and coverage gaps, so one unavailable registry cannot starve later entries. Some reports an attempted step, which may have made no progress. Both retention modes preserve individual Names records. Cancellation is cooperative before a step; an entered SQL/state operation may finish.

pub fn set_pin(&self, root: Txid, pin: bool) -> Result<(), Error>

Pin a previously reconstructed object only if all its evidence remains local. This does not claim current chain selection or fetch missing data. Use retrieval::recover_and_pin to acquire and pin an incomplete object.

pub fn prune_cache(&self) -> Result<u64, Error>

Explicit cache maintenance; no-op for unpruned archives. Returns child record count removed. Pins protect exact members even after a reorg.

pub fn maintain_cache( &self, limit_bytes: u64, cancelled: &AtomicBool, ) -> Result<CacheReceipt, Error>

Enforce a soft logical-byte target on unpinned multipart cache only. Deletes at most 128 child placements and 512 currently unreferenced raw transactions per call. SQL accounting work and elapsed time are not bounded by these row limits. No source calls or scan progress occur. Existing pins and individual/root evidence survive; in-flight unpinned recovery may lose cache and must refuse incomplete completion.

pub fn retain_next_object( &self, sources: &[&dyn RecordSource], slice: Duration, scratch: &Path, cancelled: &AtomicBool, ) -> Result<Option<ObjectStatus>, Error>

One fair unpruned maintenance step on the next incomplete root. Objects are bounded only by the protocol geometry. slice bounds network fetch time only: stored records re-verify outside it, so every visit fetches at least one missing record however large the object. Every record fetched is admitted as it is verified, so a slice that ends before completion is progress, not failure: the next visit continues from what is missing. The cursor always advances, so rounds stay fair across objects. Scan coverage is never advanced by object recovery. Pruned mode performs no acquisition. Cancellation is cooperative between record acquisitions; in-flight source I/O may still finish and leave verified cache bytes.

pub fn retrieve_located_record( &self, txid: Txid, ) -> Result<Option<ArchivedRecord>, Error>

Fetch only a known transaction location from the independent full-block source. Standard P2P is not assumed to offer an arbitrary TXID lookup. The block is verified in full, but this targeted path does not scan/index every candidate and consequently does not advance coverage.

pub fn resolve_commit(&self, raw: &[u8]) -> Result<usize, Error>

Supply a missing commit by its computed TXID. This is auxiliary prevout evidence, NOT a claim about the commit’s chain placement or witness. Only existing dependencies from locally scanned blocks can be resolved. At most 128 references are processed per call; repeat for a shared parent.

pub fn resolve_next_dependency( &self, source: &dyn CommitSource, cancelled: &AtomicBool, ) -> Result<usize, Error>

Try one distinct selected dependency whose parent is not cached. The display-hex cursor is in memory only and advances before a source miss or error, so one unavailable parent cannot starve later parents. No source is called when none are missing. If a retained record caches the parent, resolve_cached_dependency can finish remaining shared references. Invalid candidates or omitted Pruned children do not cache that parent; remaining references can require another explicit source call.

Fetch runs outside the archive mutex. Its own I/O bounds are the source’s responsibility; cancellation is checked between calls/proof work and before atomic finalization, not a hard interrupt or global deadline. The selected generation is captured before fetch and cannot be rebound to a newer view even if the same parent remains needed after a reorg.

pub fn admit_record( &self, package: RecordPackage, ) -> Result<RecordReceipt, Error>

Cache an explicitly requested record, including children in pruned mode. This is not a pin or a statement that the multipart object is complete. Header selection is independent of the sender; reorg invalidates the ticket before persistence. No source call or database lock spans proof work.

pub fn synchronize_headers(&self) -> Result<ArchiveStatus, Error>

Admit at most 2,000 headers from the selected verifier view. This makes no block-scan or completeness claim. Concurrent callers do not duplicate the synchronization cycle; they receive Busy.

pub fn synchronize_headers_until( &self, cancelled: &AtomicBool, ) -> Result<ArchiveStatus, Error>

Cancellation/deadline is checked between source calls, not a hard I/O interrupt. Each source call must also have its own bounded timeout.

pub fn scan_next(&self) -> Result<ArchiveStatus, Error>

Verify a full block and atomically commit its index evidence. Selective imports cannot call this path or manufacture a locally scanned interval.

pub fn resolve_cached_dependency(&self) -> Result<usize, Error>

Retry one available parent per scheduler round. Missing dependencies do not starve subsequent block scanning or acquire completeness from peers.

pub fn scan_next_until( &self, cancelled: &AtomicBool, ) -> Result<ArchiveStatus, Error>

impl Engine

pub fn scan_catch_up( &self, cancelled: &AtomicBool, blocks: u64, time: Duration, ) -> CatchUp

Scan selected blocks one after another until the selected tip, blocks commits, time elapsed or cancellation, which is checked between blocks. Each block is still its own verified, atomic commit; the first error ends the pass and keeps every block committed before it.

pub fn record_peer_coverage( &self, peer: &str, from: u64, to: u64, generation: u64, ) -> Result<(), Error>

Record that peer (its PeerId string) listed every placement in selected [from, to] and each listed placement was admitted, already held, or answered Missing (listed-only). generation is the one observed before fetching; a reorg since is Stale. admit_record keeps multipart children even in Pruned mode, so synced components stay until cache maintenance evicts them.

pub fn peer_cursor(&self, peer: &str) -> Result<u64, Error>

First height after the peer’s contiguous coverage from app start.

pub fn peer_cursor_from(&self, peer: &str, floor: u64) -> Result<u64, Error>

As peer_cursor, starting at the peer’s own scan floor when that is above app start: heights below it are never asked of this peer.

pub fn peer_synced_through(&self) -> Result<Option<ChainPoint>, Error>

pub fn omitting_peers(&self) -> Result<Vec<String>, Error>

pub fn peer_omissions(&self) -> Result<Vec<Omission>, Error>

pub fn peer_omissions_latest(&self, limit: u32) -> Result<Vec<Omission>, Error>

The limit highest selected omissions, ascending; bounded in SQL.

pub fn chain_peers(&self) -> Result<u64, Error>

Chain peers the source holds now; 0 without a source (offline).

pub fn chain_target(&self) -> Option<u64>

Absolute header-sync target; None while unknown or offline.