Struct TrailRecords 

pub struct TrailRecords<'a, C, D = Data> { /* private fields */ }

Record API scoped to a specific trail.

This handle builds record-oriented transactions and loads record data from the trail’s linked-table storage.

Implementations

impl<'a, C, D> TrailRecords<'a, C, D>

pub fn using_capability(self, capability_id: ObjectID) -> Self

Uses the provided capability as the auth capability for subsequent write operations.

pub async fn get(&self, sequence_number: u64) -> Result<Record<D>, Error>

where C: AuditTrailReadOnly, D: DeserializeOwned,

Loads a single record by sequence number.

Errors

Returns an error if the record cannot be loaded or deserialized.

pub fn add<S>( &self, data: D, metadata: Option<String>, tag: Option<String>, ) -> TransactionBuilder<AddRecord>

where C: AuditTrailFull + CoreClient<S>, S: Signer<IotaKeySignature> + OptionalSync, D: Into<Data>,

Builds a transaction that appends a record to the trail.

Tagged writes must reference a tag already defined on the trail. They also require a capability whose role allows both AddRecord and the requested tag.

pub fn delete<S>( &self, sequence_number: u64, ) -> TransactionBuilder<DeleteRecord>

where C: AuditTrailFull + CoreClient<S>, S: Signer<IotaKeySignature> + OptionalSync,

Builds a transaction that deletes a single record.

Deletion remains subject to record locking rules and tag-based access restrictions enforced on-chain.

pub fn delete_records_batch<S>( &self, limit: u64, ) -> TransactionBuilder<DeleteRecordsBatch>

where C: AuditTrailFull + CoreClient<S>, S: Signer<IotaKeySignature> + OptionalSync,

Builds a transaction that deletes up to limit records in one operation.

Batch deletion requires DeleteAllRecords, walks the trail from the front in sequence order, and silently skips records that are either locked or whose tag is not in the capability’s allowed set. The returned vector contains the sequence numbers actually deleted in deletion order; it may be shorter than limit (or empty) when records are skipped or the trail runs out of records before limit is reached.

Locking semantics

The set of locked records is fixed at the start of the transaction. For count-based windows, the protected window is the last count records present when the call begins — records this same call deletes do not change which other records are protected. Time-based locks are evaluated against the clock timestamp captured at the start of the call. Running delete_records_batch(limit) therefore produces the same final trail state as invoking delete_record once per deletable sequence number, as long as the locking configuration is not mutated and no new records are added between calls.

Caveats

• Partial progress is not an error. An empty returned vector means every front-to-back candidate was either locked or tag-filtered out.
• Tag filtering is silent. A capability with a narrow tag scope can make the batch appear to stop early while locked-and-disallowed records still exist further back.
• Gas and object-size limits. The call walks and mutates inline; prefer modest limit values and repeat the call rather than passing a single large limit.
• Order is fixed. Use Self::delete to target specific sequence numbers.

pub async fn correct( &self, _replaces: Vec<u64>, _data: D, _metadata: Option<String>, ) -> Result<(), Error>

where C: AuditTrailFull,

Placeholder for a future correction helper.

Errors

Always returns Error::NotImplemented.

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

where C: AuditTrailReadOnly,

Returns the number of records currently stored in the trail.

Errors

Returns an error if the count cannot be computed from the current on-chain state.

pub async fn list(&self) -> Result<HashMap<u64, Record<D>>, Error>

where C: AuditTrailReadOnly, D: DeserializeOwned,

Lists all records into a HashMap.

This traverses the full on-chain linked table and can be expensive for large trails. For paginated access, use list_page.

pub async fn list_with_limit( &self, max_entries: usize, ) -> Result<HashMap<u64, Record<D>>, Error>

where C: AuditTrailReadOnly, D: DeserializeOwned,

Lists all records with a hard cap to protect against expensive traversals.

pub async fn list_page( &self, cursor: Option<u64>, limit: usize, ) -> Result<PaginatedRecord<D>, Error>

where C: AuditTrailReadOnly, D: DeserializeOwned,

Lists one page of linked-table records starting from cursor.

Pass None for the first page; use next_cursor for subsequent pages.

Trait Implementations

impl<'a, C: Clone, D: Clone> Clone for TrailRecords<'a, C, D>

fn clone(&self) -> TrailRecords<'a, C, D>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, C: Debug, D: Debug> Debug for TrailRecords<'a, C, D>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.