KERI DB API

keri.db.basing

keri.db.dbing module

import lmdb db = lmdb.open(“/tmp/keri_db_setup_test”) db.max_key_size() 511

The dupsort, integerkey, integerdup, and dupfixed parameters are ignored if the database already exists. The state of those settings are persistent and immutable per database. See _Database.flags() to view the state of those options for an opened database. A consequence of the immutability of these flags is that the default non-named database will never have these flags set.

So only need to set dupsort first time opened each other opening does not need to call it

class keri.db.basing.Baser(headDirPath=None, reopen=False, **kwa)

Baser sets up named sub databases with Keri Event Logs within main database

see superclass LMDBer for inherited attributes

kevers

Kever instances indexed by identifier prefix qb64

Type:

dict

prefixes

local prefixes corresponding to habitats for this db

Type:

OrderedSet

.evts is named sub DB whose values are serialized events

dgKey DB is keyed by identifier prefix plus digest of serialized event Only one value per DB key is allowed

.fels is named sub DB of first seen event log table

that indexes events in first ‘seen’ accepted order for replay and cloning of event log. Only one value per DB key is allowed. Provides append only ordering of accepted first seen events. Uses first seen order number or fn. fnKey DB is keyed by identifier prefix plus monotonically increasing first seen order number fn. Value is digest of serialized event used to lookup event in .evts sub DB

Type:

FEL

.dtss is named sub DB of datetime stamp strings in ISO 8601 format of

the datetime when the event was first escrosed and then later first seen by log. Used for escrows timeouts and extended validation. dgKey DB is keyed by identifier prefix plus digest of serialized event Value is ISO 8601 datetime stamp bytes

.aess is named sub DB of authorizing event source seal couples

that map digest to seal source couple of authorizer’s (delegator or issuer) event. Each couple is a concatenation of full qualified items, snu+dig of the authorizing (delegating or issuing) source event. dgKey Values are couples used to lookup authorizer’s source event in .kels sub DB DB is keyed by identifier prefix plus digest of key event Only one value per DB key is allowed

.sigs is named sub DB of fully qualified indexed event signatures

dgKey DB is keyed by identifier prefix plus digest of serialized event More than one value per DB key is allowed

.wigs is named sub DB of indexed witness signatures of event

Witnesses always have nontransferable indetifier prefixes. The index is the offset of the witness into the witness list of the most recent establishment event wrt the receipted event. dgKey DB is keyed by identifier prefix plus digest of serialized event More than one value per DB key is allowed

.rcts is named sub DB of event receipt couplets from nontransferable

signers. Each couple is concatenation of fully qualified items. These are: non-transferale prefix plus non-indexed event signature by that prefix. dgKey DB is keyed by identifier prefix plus digest of serialized event More than one value per DB key is allowed

.ures is named sub DB of unverified event receipt escrowed triples from

non-transferable signers. Each triple is concatenation of fully qualified items. These are: receipted event digest, non-transferable receiptor identifier prefix, plus nonindexed receipt event signature by that prefix. snKey DB is keyed by receipted event controller prefix plus sn of serialized event More than one value per DB key is allowed

.vrcs is named sub DB of event validator receipt quadruples from transferable

signers. Each quadruple is concatenation of four fully qualified items of validator. These are: transferable prefix, plus latest establishment event sequence number plus latest establishment event digest, plus indexed event signature. When latest establishment event is multisig then there will be multiple quadruples one per signing key, each a dup at same db key. dgKey DB is keyed by identifier prefix plus digest of serialized event More than one value per DB key is allowed

.vres is named sub DB of unverified event validator receipt escrowed

quadruples from transferable signers. Each quadruple is concatenation of four fully qualified items of validator. These are: transferable prefix, plus latest establishment event sequence number plus latest establishment event digest, plus indexed event signature. When latest establishment event is multisig then there will be multiple quadruples one per signing key, each a dup at same db key. dgKey DB is keyed by identifier prefix plus digest of serialized event More than one value per DB key is allowed

.kels is named sub DB of key event log tables that map sequence numbers

to serialized event digests. snKey Values are digests used to lookup event in .evts sub DB DB is keyed by identifier prefix plus sequence number of key event More than one value per DB key is allowed

.pses is named sub DB of partially signed escrowed event tables

that map sequence numbers to serialized event digests. snKey Values are digests used to lookup event in .evts sub DB DB is keyed by identifier prefix plus sequence number of key event More than one value per DB key is allowed

.pdes is named sub DB of partially delegated escrowed couples

that map digest to seal source couple that provides source (delegator or issuer) event seal. Each couples is concatenations of full qualified items, snu+dig of authorizing (delegating or issuing) source event. dgKey Values are couples used to lookup source event in .kels sub DB DB is keyed by identifier prefix plus digest of key event Only one value per DB key is allowed

.pwes is named sub DB of partially witnessed escrowed event tables

that map sequence numbers to serialized event digests. snKey Values are digests used to lookup event in .evts sub DB DB is keyed by identifier prefix plus sequence number of key event More than one value per DB key is allowed

.uwes is named sub DB of unverified event indexed escrowed couples from

witness signers. Witnesses are from witness list of latest establishment event for the receipted event. Each couple is concatenation of fully qualified items, edig+sig where:

edig is receipted event digest wig is indexed signature of that event with keypair derived from

witness nontrans identifier prefix from witness list and index is offset into witness list of latest establishment event for receipted event

snKey DB is keyed by receipted event controller prefix plus sn of serialized event More than one value per DB key is allowed

.ooes is named sub DB of out of order escrowed event tables

that map a prefix and sequence number to a set of serialized event digests. Values are digests used to lookup event in .evts, .sigs and .dtss sub DBs. snKey DB is keyed by identifier prefix plus sequence number of key event More than one value per DB key is allowed

.dels is named sub DB of duplicitous event log tables that map sequence numbers

to serialized event digests. snKey Values are digests used to lookup event in .evts sub DB DB is keyed by identifier prefix plus sequence number of key event More than one value per DB key is allowed

.ldes is named sub DB of likely duplicitous escrowed event tables

that map sequence numbers to serialized event digests. snKey Values are digests used to lookup event in .evts sub DB DB is keyed by identifier prefix plus sequence number of key event More than one value per DB key is allowed

.fons is named subDB instance of MatterSuber that maps

(prefix, digest) e.g. dgKey to fn value (first seen ordinal number) of the associated event. So one can lookup event digest, get its fn here and then use fn to fetch event by fn from .fels.

.states

to the latest keystate for that prefix. Used by ._kevers.db for read through cache of key state to reload kevers in memory

Type:

stts

.habs is named subDB instance of Komer that maps habitat names to habitat

application state. Includes habitat identifier prefix key is habitat name str value is serialized HabitatRecord dataclass

.nmsp is named subDB instance of Komer that maps habitat namespaces and names to habitat

application state. Includes habitat identifier prefix key is habitat namespace + b’' + name str value is serialized HabitatRecord dataclass

.sdts

that maps SAD SAID to Dater instance’s CESR serialization of ISO-8601 datetime key = said (bytes) of sad, val = dater.qb64b

Type:

sad date-time-stamp

.ssgs

that maps keys quadruple (saider.qb64, prefixer.qb64, seqner.q64, diger.qb64) to val Siger of trans id siganture. Where: saider is said of SAD and prefixer, seqner, and diger indicate the key state est event for signer or reply SAD. Each key may have a set of vals in insertion order one for each signer of the sad. key = join (saider.qb64b, prefixer.qb64b, seqner.qb64b, diger.qb64b) (bytes) val = siger.qb64b

Type:

sad trans indexed sigs

.scgs

that maps said of SAD to couple (Verfer, Cigar) for nontrans signer. For nontrans qb64 of Verfer is same as Prefixer. Each key may have a set of vals in insertion order one for each nontrans signer of the sad. key = said (bytes of SAD, val = cat of (verfer.qb64, cigar.qb64b)

Type:

sad nontrans cigs

.rpys

reply message (versioned SAD) to serialization of that reply message. key is said bytes, val is Serder.raw bytes of reply ‘rpy’ message

Type:

replys

.rpes

maps routes of reply (versioned SAD) to single Saider of that reply msg. Routes such as ‘/end/role/’ and ‘/loc/scheme’ key is route bytes, vals = saider.qb64b of reply ‘rpy’ msg

Type:

reply escrows

.eans is named subDB instance of CesrSuber with klas=Saider that maps

cid.role.eid to said of reply SAD as auth: authN by controller cid of authZ that designates endpoint provider eid in role routes /end/role/add and /end/role/cut to nullify key is cid.role.eid, val = saider.qb64b of reply ‘rpy’ msg SAD

.lans is named subDB instance of CesrSuber with klas=Saider that maps

eid.scheme to said of reply SAD as auth: authN by endpoint provider eid that designates scheme for url route /loc/scheme use null url to nullify key is eid.scheme, val = saider.qb64b of reply ‘rpy’ msg SAD

.ends is named subDB instance of Komer that maps

to attributes about endpoint authorization where: cid is controller prefix, role is endpoint role, watcher etc, and eid is controller prefix of endpoint controller watcher etc. key is cid.role.eid, value is serialized EndpointRecord dataclass

Type:

cid, role, eid

.locs is named subDB instance of Komer that maps endpoint prefix eid

and endpoint network location scheme to endpoint location details key is eid.scheme, val is serialized LocationRecord dataclass

.tops is named subDB instance of Komer that maps Witness identifier

prefix to topic index of last received mailbox message. key is witness prefix identifier value is serialized TopicsRecord dataclass

.gids is named subDB instance of Komer that maps group identifier prefix

to the local identifier prefix and list of remote identifier prefixes that participate in the group identifier. key is group identifier prefix value is serialized GroupIdentifier dataclass

.mpids is named subDB instance of CesrIoSetSuber mapping payload SAID

to the SAID of the exn messages is was contained in. This aggregates identical message bodies across participants in group multisig body trying to reach concensus on events or credentials.

Type:

of ‘e’ block

Properties:

kevers (dbdict): read through cache of kevers of states for KELs in db

__init__(headDirPath=None, reopen=False, **kwa)

Setup named sub databases.

Parameters:

• database (headDirPath is optional str head directory pathname for main) – When system employs more than one keri database, name allows differentiating each instance by name

• boolean (temp is) – True then open in temporary directory, clear on close Othewise then open persistent directory, do not clear on close

• .temp (assign to) – True then open in temporary directory, clear on close Othewise then open persistent directory, do not clear on close

• database – If not provided use default .HeadDirpath

• directory (mode is int numeric os dir permissions for database)

• reopen (bool) – True means database will be reopened by this init

addDe(key, val)

Use snKey() Add duplicate event index val bytes as dup to key in db Adds to existing event indexes at key if any Returns True if written else False if dup val already exists Duplicates are inserted in insertion order.

addKe(key, val)

Use snKey() Add key event val bytes as dup to key in db Adds to existing event indexes at key if any Returns True if written else False if dup val already exists Duplicates are inserted in insertion order.

addLde(key, val)

Use snKey() Add likely duplicitous escrow val bytes as dup to key in db Adds to existing event indexes at key if any Returns True if written else False if dup val already exists Duplicates are inserted in insertion order.

addOoe(key, val)

Use snKey() Add out of order escrow val bytes as dup to key in db Adds to existing event indexes at key if any Returns True if written else False if dup val already exists Duplicates are inserted in insertion order.

addPse(key, val)

Use snKey() Add Partial signed escrow val bytes as dup to key in db Adds to existing event indexes at key if any Returns True if written else False if dup val already exists Duplicates are inserted in insertion order.

addPwe(key, val)

Use snKey() Add Partial witnessed escrow dig val bytes as dup to key in db Adds to existing event indexes at key if any Returns True if written else False if dup val already exists Duplicates are inserted in insertion order.

addQnf(key, val)

Use snKey() Add out of order escrow val bytes as dup to key in db Adds to existing event indexes at key if any Returns True if written else False if dup val already exists Duplicates are inserted in insertion order.

addRct(key, val)

Use dgKey() Add receipt couple val bytes as dup to key in db Couple is pre+cig (non indexed signature) Adds to existing values at key if any Returns True if written else False if dup val already exists Duplicates are inserted in lexocographic order not insertion order.

addSig(key, val)

Use dgKey() Add signature val bytes as dup to key in db Adds to existing values at key if any Returns True if written else False if dup val already exists Duplicates are inserted in lexocographic order not insertion order.

addUre(key, val)

Use snKey() Add receipt triple val bytes as dup to key in db Triple is dig+pre+cig Adds to existing values at key if any Returns True If at least one of vals is added as dup, False otherwise Duplicates are inserted in insertion order.

addUwe(key, val)

Use snKey() Add receipt couple val bytes as dup to key in db Witness couple is edig+wig Adds to existing values at key if any Returns True If at least one of vals is added as dup, False otherwise Duplicates are inserted in insertion order.

addVrc(key, val)

Use dgKey() Add receipt quadruple val bytes as dup to key in db quadruple is spre+ssnu+sdig+sig Adds to existing values at key if any Returns True if written else False if dup val already exists Duplicates are inserted in lexocographic order not insertion order.

addVre(key, val)

Use snKey() Add receipt quintuple val bytes as dup to key in db Quinlet is edig + spre + ssnu + sdig +sig Adds to existing values at key if any Returns True If at least one of vals is added as dup, False otherwise Duplicates are inserted in insertion order.

addWig(key, val)

Use dgKey() Add indexed witness signature val bytes as dup to key in db Adds to existing values at key if any Returns True if written else False if dup val already exists Duplicates are inserted in lexocographic order not insertion order.

appendFe(pre, val)

Return first seen order number int, fn, of appended entry. Computes fn as next fn after last entry. Uses fnKey(pre, fn) for entries.

Append val to end of db entries with same pre but with fn incremented by 1 relative to last preexisting entry at pre.

Parameters:

• event (pre is bytes identifier prefix for)

• digest (val is event)

clean()

Clean database by creating re-verified cleaned cloned copy and then replacing original with cleaned cloned copy

Database usage should be offline during cleaning as it will be cloned in readonly mode

cloneAllPreIter(key=b'')

Returns iterator of first seen event messages with attachments for all identifier prefixes starting at key. If key == b’’ then rstart at first key in databse. Use key to resume replay. Essentially a replay in first seen order with attachments of entire set of FELs.

Parameters:

key (bytes) – fnKey(pre, fn)

cloneDelegation(kever)

Recursively clone delegation chain from AID of Kever if one exits.

Parameters:

kever (Kever) – Kever from which to clone the delegator’s AID.

cloneEvtMsg(pre, fn, dig)

Clones Event as Serialized CESR Message with Body and attached Foot

Parameters:

• pre (bytes) – identifier prefix of event

• fn (int) – first seen number (ordinal) of event

• dig (bytes) – digest of event

Returns:

message body with attachments

Return type:

bytearray

clonePreIter(pre, fn=0)

Returns iterator of first seen event messages with attachments for the identifier prefix pre starting at first seen order number, fn. Essentially a replay in first seen order with attachments

cntDes(key)

Use snKey() Return count of dup event dig vals at key Returns zero if no entry at key

cntKes(key)

Use snKey() Return count of dup key event dig val at key Returns zero if no entry at key

cntLdes(key)

Use snKey() Return count of dup event dig at key Returns zero if no entry at key

cntOoes(key)

Use snKey() Return count of dup event dig at key Returns zero if no entry at key

cntPses(key)

Use snKey() Return count of dup event dig vals at key Returns zero if no entry at key

cntPwes(key)

Use snKey() Return count of dup event dig vals at key Returns zero if no entry at key

cntQnfs(key)

Use snKey() Return count of dup event dig at key Returns zero if no entry at key

cntRcts(key)

Use dgKey() Return count of receipt couplets at key Couple is pre+cig (non indexed signature) Returns zero if no entry at key

cntSigs(key)

Use dgKey() Return count of signatures at key Returns zero if no entry at key

cntUres(key)

Use snKey() Return count of receipt triplets at key Returns zero if no entry at key

cntUwes(key)

Use snKey() Return count of receipt couples at key Returns zero if no entry at key

cntVrcs(key)

Use dgKey() Return count of receipt quadruples at key Returns zero if no entry at key

cntVres(key)

Use snKey() Return count of receipt quinlets at key Returns zero if no entry at key

cntWigs(key)

Use dgKey() Return count of indexed witness signatures at key Returns zero if no entry at key

delAes(key)

Use dgKey() Deletes value at key. Returns True If key exists in database Else False

delDes(key)

Use snKey() Deletes all values at key. Returns True If key exists in database Else False

delDts(key)

Use dgKey() Deletes value at key. Returns True If key exists in database Else False

delEvt(key)

Use dgKey() Deletes value at key. Returns True If key exists in database Else False

delFe(key)

Use snKey() Deletes value at key. Returns True If key exists in database Else False

delKes(key)

Use snKey() Deletes all values at key. Returns True If key exists in database Else False

delLde(key, val)

Use snKey() Deletes dup val at key in db. Returns True If dup at exists in db Else False

Parameters:

• dupsort=True (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

• val (val is dup)

delLdes(key)

Use snKey() Deletes all values at key. Returns True If key exists in database Else False

delOoe(key, val)

Use snKey() Deletes dup val at key in db. Returns True If dup at exists in db Else False

Parameters:

• dupsort=True (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

• val (val is dup)

delOoes(key)

Use snKey() Deletes all values at key. Returns True If key exists in database Else False

delPde(key)

Use dgKey() Deletes value at key. Returns True If key exists in database Else False

delPse(key, val)

Use snKey() Deletes dup val at key in db. Returns True If dup at exists in db Else False

Parameters:

• keyspace (key is bytes of key within sub db's)

• val (val is dup)

delPses(key)

Use snKey() Deletes all values at key in db. Returns True If key exists in db Else False

delPwe(key, val)

Use snKey() Deletes dup val at key in db. Returns True If dup at exists in db Else False

Parameters:

• keyspace (key is bytes of key within sub db's)

• val (val is dup)

delPwes(key)

Use snKey() Deletes all values at key in db. Returns True If key exists in db Else False

delQnf(key, val)

Use snKey() Deletes dup val at key in db. Returns True If dup at exists in db Else False

Parameters:

• dupsort=True (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

• val (val is dup)

delQnfs(key)

Use snKey() Deletes all values at key. Returns True If key exists in database Else False

delRcts(key, val=b'')

Use dgKey() Deletes all values at key if val = b’’ else deletes dup val = val. Returns True If key exists in database (or key, val if val not b’’) Else False

delSigs(key, val=b'')

Use dgKey() Deletes all values at key if val = b’’ else deletes dup val = val. Returns True If key exists in database (or key, val if val not b’’) Else False

delUre(key, val)

Use snKey() Deletes dup val at key in db. Returns True If dup at exists in db Else False

Parameters:

• keyspace (key is bytes of key within sub db's)

• val (val is dup)

delUres(key)

Use snKey() Deletes all values at key in db. Returns True If key exists in database Else False

delUwe(key, val)

Use snKey() Deletes dup val at key in db. Returns True If dup at exists in db Else False

Parameters:

• keyspace (key is bytes of key within sub db's)

• val (val is dup)

delUwes(key)

Use snKey() Deletes all values at key in db. Returns True If key exists in database Else False

delVrcs(key, val=b'')

Use dgKey() Deletes all values at key if val = b’’ else deletes dup val = val. Returns True If key exists in database (or key, val if val not b’’) Else False

delVre(key, val)

Use snKey() Deletes dup val at key in db. Returns True If dup at exists in db Else False

Parameters:

• keyspace (key is bytes of key within sub db's)

• val (val is dup)

delVres(key)

Use snKey()

Deletes all values at key in db. Returns True If key exists in database Else False

delWigs(key, val=b'')

Use dgKey() Deletes all values at key if val = b’’ else deletes dup val = val. Returns True If key exists in database (or key, val if val not b’’) Else False

findAnchoringSeal(pre, seal, sn=0)

Search through a KEL for the event that contains an anchored Seal with same Seal type as provided seal but in dict form. Searchs from sn forward (default = 0). Only searches last event at any sn therefore does not search any disputed or superseded events. Returns the Serder of the first event with the anchored Seal seal,

None if not found

Parameters:

• pre (bytes|str) – identifier of the KEL to search

• seal (dict) – dict form of Seal of any type to find in anchored seals list of each event

• sn (int) – beginning sn to search

findAnchoringSealClone(pre, seal)

Search through a KEL for the event that contains an anchored Seal with same Seal type as provided seal but in dict form. Returns the Serder of the first event with the anchored Seal seal,

None if not found

Searchs from inception forward

Parameters:

• search (pre is qb64 identifier of the KEL to)

• event (seal is dict form of Seal of any type to find in anchored seals list of each)

findAnchoringSealEvent(pre, seal, sn=0)

Search through a KEL for the event that contains a specific anchored SealEvent type of provided seal but in dict form and is also fully witnessed. Searchs from sn forward (default = 0).Searches all events in KEL of pre including disputed and/or superseded events. Returns the Serder of the first event with the anchored SealEvent seal,

None if not found

Parameters:

• pre (bytes|str) – identifier of the KEL to search

• seal (dict) – dict form of Seal of any type SealEvent to find in anchored seals list of each event

• sn (int) – beginning sn to search

findAnchoringSealEventClone(pre, seal)

Search through a KEL for the event that contains a specific anchored SealEvent type of provided seal but in dict form. Returns the Serder of the first event with the anchored SealEvent seal,

None if not found

Searchs from inception forward

Parameters:

• search (pre is qb64 identifier of the KEL to)

• event (seal is dict form of SealEvent to find in anchored seals list of each)

fullyWitnessed(serder)

Verify the witness threshold on the event

Parameters:

serder (Serder) – event serder to validate witness threshold

Returns:

getAes(key)

Use dgKey() Return source seal event couple at key Returns None if no entry at key

getDeLast(key)

Use snKey() Return last inserted dup value of duplicitous event dig vals at key Returns None if no entry at key

Duplicates are retrieved in insertion order.

getDelIter(pre)

Returns iterator of all dup vals in insertion order for any entries with same prefix across all sequence numbers including gaps. Assumes that key is combination of prefix and sequence number given by .snKey().

Raises StopIteration Error when empty. Duplicates are retrieved in insertion order.

Parameters:

• dupsort=True (db is opened named sub db with)

• key (pre is bytes of itdentifier prefix prepended to sn in) – within sub db’s keyspace

getDes(key)

Use snKey() Return list of duplicitous event dig vals at key Returns empty list if no entry at key Duplicates are retrieved in insertion order.

getDts(key)

Use dgKey() Return datetime stamp at key Returns None if no entry at key

getEvt(key)

Use dgKey() Return event at key Returns None if no entry at key

getEvtLastPreIter(pre, sn=0)

Returns iterator of event messages without attachments in sn order from the KEL of identifier prefix pre. Essentially a replay of all event messages without attachments for each sn from the KEL of pre including superseded duplicates

Parameters:

• pre (bytes|str) – identifier prefix

• sn (int) – sequence number (default 0) to begin interation

getEvtPreIter(pre, sn=0)

Returns iterator of event messages without attachments in sn order from the KEL of identifier prefix pre. Essentially a replay of all event messages without attachments for each sn from the KEL of pre including superseded duplicates

Parameters:

• pre (bytes|str) – identifier prefix

• sn (int) – sequence number (default 0) to begin interation

getFe(key)

Use fnKey() Return event digest at key Returns None if no entry at key

getFelItemAllPreIter(key=b'')

Returns iterator of all (pre, fn, dig) triples in first seen order for all events for all prefixes in database. Items are sorted by fnKey(pre, fn) where fn is first seen order number int. Returns all First Seen Event Logs FELs. Returned items are tripes of (pre, fn, dig): Where pre is identifier prefix, fn is first seen order number int and dig is event digest for lookup in .evts sub db.

Raises StopIteration Error when empty.

Parameters:

• replay (key is key location in db to resume) – first key in database

• at (If empty then start) – first key in database

getFelItemPreIter(pre, fn=0)

Returns iterator of all (fn, dig) duples in first seen order for all events with same prefix, pre, in database. Items are sorted by fnKey(pre, fn) where fn is first seen order number int. Returns a First Seen Event Log FEL. Returned items are duples of (fn, dig): Where fn is first seen order number int and dig is event digest for lookup in .evts sub db.

Raises StopIteration Error when empty.

Parameters:

• prefix (pre is bytes of itdentifier)

• fn=0 (fn is int fn to resume replay. Earliset is)

getKeLast(key)

Use snKey() Return last inserted dup key event dig vals at key Returns None if no entry at key Duplicates are retrieved in insertion order.

getKelBackIter(pre, sn=0)

Returns iterator of all dup vals in insertion order for all entries with same prefix across all sequence numbers without gaps in decreasing order starting with first sequence number sn. Stops if encounters gap. Assumes that key is combination of prefix and sequence number given by .snKey().

db .kels values are digests used to lookup event in .evts sub DB

Raises StopIteration Error when empty. Duplicates are retrieved in insertion order. db is opened as named sub db with dupsort=True

Parameters:

• pre (bytes | str) – of itdentifier prefix prepended to sn in key within sub db’s keyspace

• sn (int)

getKelIter(pre, sn=0)

Returns iterator of all dup vals in insertion order for all entries with same prefix across all sequence numbers without gaps. Stops if encounters gap. Assumes that key is combination of prefix and sequence number given by .snKey().

db .kels values are digests used to lookup event in .evts sub DB

Raises StopIteration Error when empty. Duplicates are retrieved in insertion order. db is opened as named sub db with dupsort=True

Parameters:

• pre (bytes | str) – of itdentifier prefix prepended to sn in key within sub db’s keyspace

• sn (int) – initial sequence number to begin at

getKelLastIter(pre, sn=0)

Returns iterator of last one of dup vals at each key in insertion order for all entries with same prefix across all sequence numbers without gaps. Stops if encounters gap. Assumes that key is combination of prefix and sequence number given by .snKey().

db .kels values are digests used to lookup event in .evts sub DB

Raises StopIteration Error when empty. Duplicates are retrieved in insertion order. db is opened as named sub db with dupsort=True

Parameters:

• pre (bytes | str) – of itdentifier prefix prepended to sn in key within sub db’s keyspace

• sn (int)

getKes(key)

Use snKey() Return list of key event dig vals at key Returns empty list if no entry at key Duplicates are retrieved in insertion order.

getLdeItemsNext(key=b'', skip=True)

Use snKey() Return all dups of likely duplicitous escrowed event dig items at next key after key. Item is (key, val) where proem has already been stripped from val If key is b’’ empty then returns dup items at first key. If skip is False and key is not b’’ empty then returns dup items at key Returns empty list if no entry at key Duplicates are retrieved in insertion order.

getLdeItemsNextIter(key=b'', skip=True)

Use sgKey() Return iterator of likely duplicitous escrowed event dig items at next key after key. Items is (key, val) where proem has already been stripped from val If key is b’’ empty then returns dup items at first key. If skip is False and key is not b’’ empty then returns dup items at key Raises StopIteration Error when empty Duplicates are retrieved in insertion order.

getLdeLast(key)

Use snKey() Return last inserted dup val of likely duplicitous event dig vals at key Returns None if no entry at key Duplicates are retrieved in insertion order.

getLdes(key)

Use snKey() Return list of likely duplicitous event dig vals at key Returns empty list if no entry at key Duplicates are retrieved in insertion order.

getOoeItemsNext(key=b'', skip=True)

Use snKey() Return all dups of out of order escrowed event dig items at next key after key. Item is (key, val) where proem has already been stripped from val If key is b’’ empty then returns dup items at first key. If skip is False and key is not b’’ empty then returns dup items at key Returns empty list if no entry at key Duplicates are retrieved in insertion order.

getOoeItemsNextIter(key=b'', skip=True)

Use sgKey() Return iterator of out of order escrowed event dig items at next key after key. Items is (key, val) where proem has already been stripped from val If key is b’’ empty then returns dup items at first key. If skip is False and key is not b’’ empty then returns dup items at key Raises StopIteration Error when empty Duplicates are retrieved in insertion order.

getOoeLast(key)

Use snKey() Return last inserted dup val of out of order escrow event dig vals at key Returns None if no entry at key Duplicates are retrieved in insertion order.

getOoes(key)

Use snKey() Return list of out of order escrow event dig vals at key Returns empty list if no entry at key Duplicates are retrieved in insertion order.

getPde(key)

Use dgKey() Return seal source couple at key Returns None if no entry at key

getPseItemsNext(key=b'', skip=True)

Use snKey() Return all dups of partial signed escrowed event dig items at next key after key. Item is (key, val) where proem has already been stripped from val If key is b’’ empty then returns dup items at first key. If skip is False and key is not b’’ empty then returns dup items at key Returns empty list if no entry at key Duplicates are retrieved in insertion order.

getPseItemsNextIter(key=b'', skip=True)

Use sgKey() Return iterator of partial signed escrowed event dig items at next key after key. Items is (key, val) where proem has already been stripped from val If key is b’’ empty then returns dup items at first key. If skip is False and key is not b’’ empty then returns dup items at key Raises StopIteration Error when empty Duplicates are retrieved in insertion order.

getPseLast(key)

Use snKey() Return last inserted dup partial signed escrowed event dig val at key Returns None if no entry at key Duplicates are retrieved in insertion order.

getPses(key)

Use snKey() Return list of partial signed escrowed event dig vals at key Returns empty list if no entry at key Duplicates are retrieved in insertion order.

getPsesIter(key)

Use sgKey() Return iterator of partial signed escrowed event dig vals at key Raises StopIteration Error when empty Duplicates are retrieved in insertion order.

getPweItemsNext(key=b'', skip=True)

Use snKey() Return all dups of partial witnessed escrowed event dig items at next key after key. Item is (key, val) where proem has already been stripped from val If key is b’’ empty then returns dup items at first key. If skip is False and key is not b’’ empty then returns dup items at key Returns empty list if no entry at key Duplicates are retrieved in insertion order.

getPweItemsNextIter(key=b'', skip=True)

Use sgKey() Return iterator of partial witnessed escrowed event dig items at next key after key. Items is (key, val) where proem has already been stripped from val If key is b’’ empty then returns dup items at first key. If skip is False and key is not b’’ empty then returns dup items at key Raises StopIteration Error when empty Duplicates are retrieved in insertion order.

getPweLast(key)

Use snKey() Return last inserted dup partial witnessed escrowed event dig val at key Returns None if no entry at key Duplicates are retrieved in insertion order.

getPwes(key)

Use snKey() Return list of witnessed signed escrowed event dig vals at key Returns empty list if no entry at key Duplicates are retrieved in insertion order.

getPwesIter(key)

Use sgKey() Return iterator of partial witnessed escrowed event dig vals at key Raises StopIteration Error when empty Duplicates are retrieved in insertion order.

getQnfItemsNext(key=b'', skip=True)

Use snKey() Return all dups of out of order escrowed event dig items at next key after key. Item is (key, val) where proem has already been stripped from val If key is b’’ empty then returns dup items at first key. If skip is False and key is not b’’ empty then returns dup items at key Returns empty list if no entry at key Duplicates are retrieved in insertion order.

getQnfItemsNextIter(key=b'', skip=True)

Use sgKey() Return iterator of out of order escrowed event dig items at next key after key. Items is (key, val) where proem has already been stripped from val If key is b’’ empty then returns dup items at first key. If skip is False and key is not b’’ empty then returns dup items at key Raises StopIteration Error when empty Duplicates are retrieved in insertion order.

getQnfLast(key)

Use snKey() Return last inserted dup val of out of order escrow event dig vals at key Returns None if no entry at key Duplicates are retrieved in insertion order.

getQnfs(key)

Use snKey() Return list of out of order escrow event dig vals at key Returns empty list if no entry at key Duplicates are retrieved in insertion order.

getRcts(key)

Use dgKey() Return list of receipt couplets at key Couple is pre+cig (non indexed signature) Returns empty list if no entry at key Duplicates are retrieved in lexocographic order not insertion order.

getRctsIter(key)

Use dgKey() Return iterator of receipt couplets at key Couple is pre+cig (non indexed signature) Raises StopIteration Error when empty Duplicates are retrieved in lexocographic order not insertion order.

getSigs(key)

Use dgKey() Return list of signatures at key Returns empty list if no entry at key Duplicates are retrieved in lexocographic order not insertion order.

getSigsIter(key)

Use dgKey() Return iterator of signatures at key Raises StopIteration Error when empty Duplicates are retrieved in lexocographic order not insertion order.

getUreItemsNext(key=b'', skip=True)

Use snKey() Return all dups of partial signed escrowed event triple items at next key after key. Item is (key, val) where proem has already been stripped from val val is triple dig+pre+cig If key is b’’ empty then returns dup items at first key. If skip is False and key is not b’’ empty then returns dup items at key Returns empty list if no entry at key Duplicates are retrieved in insertion order.

getUreItemsNextIter(key=b'', skip=True)

Use sgKey() Return iterator of partial signed escrowed event triple items at next key after key. Items is (key, val) where proem has already been stripped from val val is triple dig+pre+cig If key is b’’ empty then returns dup items at first key. If skip is False and key is not b’’ empty then returns dup items at key Raises StopIteration Error when empty Duplicates are retrieved in insertion order.

getUreLast(key)

Use snKey() Return last inserted dup partial signed escrowed event triple val at key Triple is dig+pre+cig Returns None if no entry at key Duplicates are retrieved in insertion order.

getUres(key)

Use snKey() Return list of receipt triplets at key Triple is dig+pre+cig Returns empty list if no entry at key Duplicates are retrieved in insertion order.

getUresIter(key)

Use snKey() Return iterator of receipt triplets at key Triple is dig+pre+cig Raises StopIteration Error when empty Duplicates are retrieved in insertion order.

getUweItemsNext(key=b'', skip=True)

Use snKey() Return all dups of partial signed escrowed receipt couple items at next key after key. Item is (key, val) where proem has already been stripped from val val is couple edig+wig If key is b’’ empty then returns dup items at first key. If skip is False and key is not b’’ empty then returns dup items at key Returns empty list if no entry at key Duplicates are retrieved in insertion order.

getUweItemsNextIter(key=b'', skip=True)

Use sgKey() Return iterator of partial signed escrowed receipt couple items at next key after key. Items is (key, val) where proem has already been stripped from val val is couple edig+wig If key is b’’ empty then returns dup items at first key. If skip is False and key is not b’’ empty then returns dup items at key Raises StopIteration Error when empty Duplicates are retrieved in insertion order.

getUweLast(key)

Use snKey() Return last inserted dup partial signed escrowed receipt couple val at key Witness couple is edig+wig Returns None if no entry at key Duplicates are retrieved in insertion order.

getUwes(key)

Use snKey() Return list of receipt couples at key Witness couple is edig+wig Returns empty list if no entry at key Duplicates are retrieved in insertion order.

getUwesIter(key)

Use snKey() Return iterator of receipt couples at key Witness couple is edig+wig Raises StopIteration Error when empty Duplicates are retrieved in insertion order.

getVrcs(key)

Use dgKey() Return list of receipt quadruples at key quadruple is spre+ssnu+sdig+sig Returns empty list if no entry at key Duplicates are retrieved in lexocographic order not insertion order.

getVrcsIter(key)

Use dgKey() Return iterator of receipt quadruples at key quadruple is spre+ssnu+sdig+sig Raises StopIteration Error when empty Duplicates are retrieved in lexocographic order not insertion order.

getVreItemsNext(key=b'', skip=True)

Use snKey() Return all dups of partial signed escrowed event quintuple items at next key after key. Item is (key, val) where proem has already been stripped from val val is Quinlet is edig + spre + ssnu + sdig +sig If key is b’’ empty then returns dup items at first key. If skip is False and key is not b’’ empty then returns dup items at key Returns empty list if no entry at key Duplicates are retrieved in insertion order.

getVreItemsNextIter(key=b'', skip=True)

Use sgKey() Return iterator of partial signed escrowed event quintuple items at next key after key. Items is (key, val) where proem has already been stripped from val val is Quinlet is edig + spre + ssnu + sdig +sig If key is b’’ empty then returns dup items at first key. If skip is False and key is not b’’ empty then returns dup items at key Raises StopIteration Error when empty Duplicates are retrieved in insertion order.

getVreLast(key)

Use snKey() Return last inserted dup partial signed escrowed event quintuple val at key Quinlet is edig + spre + ssnu + sdig +sig Returns None if no entry at key Duplicates are retrieved in insertion order.

getVres(key)

Use snKey() Return list of receipt quinlets at key Quinlet is edig + spre + ssnu + sdig +sig Returns empty list if no entry at key Duplicates are retrieved in insertion order.

getVresIter(key)

Use snKey() Return iterator of receipt quinlets at key Quinlet is edig + spre + ssnu + sdig +sig Raises StopIteration Error when empty Duplicates are retrieved in insertion order.

getWigs(key)

Use dgKey() Return list of indexed witness signatures at key Returns empty list if no entry at key Duplicates are retrieved in lexocographic order not insertion order.

getWigsIter(key)

Use dgKey() Return iterator of indexed witness signatures at key Raises StopIteration Error when empty Duplicates are retrieved in lexocographic order not insertion order.

property kevers

Returns .db.kevers

putAes(key, val)

Use dgKey() Write serialized source seal event couple val to key Does not overwrite existing val if any Returns True If val successfully written Else False Returns False if key already exists

putDes(key, vals)

Use snKey() Write each duplicitous event entry dig from list of bytes vals to key Adds to existing event indexes at key if any Returns True If at least one of vals is added as dup, False otherwise Duplicates are inserted in insertion order.

putDts(key, val)

Use dgKey() Write serialized event datetime stamp val to key Does not overwrite existing val if any Returns True If val successfully written Else False Returns False if key already exists

putEvt(key, val)

Use dgKey() Write serialized event bytes val to key Does not overwrite existing val if any Returns True If val successfully written Else False Return False if key already exists

putFe(key, val)

Use fnKey() Write event digest bytes val to key Does not overwrite existing val if any Returns True If val successfully written Else False Return False if key already exists

putKes(key, vals)

Use snKey() Write each key event dig entry from list of bytes vals to key Adds to existing event indexes at key if any Returns True If at least one of vals is added as dup, False otherwise Duplicates are inserted in insertion order.

putLdes(key, vals)

Use snKey() Write each likely duplicitous event entry dig from list of bytes vals to key Adds to existing event indexes at key if any Returns True If at least one of vals is added as dup, False otherwise Duplicates are inserted in insertion order.

putOoes(key, vals)

Use snKey() Write each out of order escrow event dig entry from list of bytes vals to key Adds to existing event indexes at key if any Returns True If at least one of vals is added as dup, False otherwise Duplicates are inserted in insertion order.

putPde(key, val)

Use dgKey() Write serialized event source couple to key (snu+dig) Does not overwrite existing val if any Returns True If val successfully written Else False Returns False if key already exists

putPses(key, vals)

Use snKey() Write each partial signed escrow event entry from list of bytes dig vals to key Adds to existing event indexes at key if any Returns True If at least one of vals is added as dup, False otherwise Duplicates are inserted in insertion order.

putPwes(key, vals)

Use snKey() Write each partial witnessed escrow event entry from list of bytes dig vals to key Adds to existing event indexes at key if any Returns True If at least one of vals is added as dup, False otherwise Duplicates are inserted in insertion order.

putQnfs(key, vals)

Use snKey() Write each out of order escrow event dig entry from list of bytes vals to key Adds to existing event indexes at key if any Returns True If at least one of vals is added as dup, False otherwise Duplicates are inserted in insertion order.

putRcts(key, vals)

Use dgKey() Write each entry from list of bytes receipt couplets vals to key Couple is pre+cig (non indexed signature) Adds to existing receipts at key if any Returns True If no error Apparently always returns True (is this how .put works with dupsort=True) Duplicates are inserted in lexocographic order not insertion order.

putSigs(key, vals)

Use dgKey() Write each entry from list of bytes signatures vals to key Adds to existing signatures at key if any Returns True If no error Apparently always returns True (is this how .put works with dupsort=True) Duplicates are inserted in lexocographic order not insertion order.

putUres(key, vals)

Use snKey() Write each entry from list of bytes receipt triples vals to key Triple is dig+pre+cig Adds to existing receipts at key if any Returns True If at least one of vals is added as dup, False otherwise Duplicates are inserted in insertion order.

putUwes(key, vals)

Use snKey() Write each entry from list of bytes witness receipt couples vals to key Witness couple is edig+wig Adds to existing receipts at key if any Returns True If at least one of vals is added as dup, False otherwise Duplicates are inserted in insertion order.

putVrcs(key, vals)

Use dgKey() Write each entry from list of bytes receipt quadruples vals to key quadruple is spre+ssnu+sdig+sig Adds to existing receipts at key if any Returns True If no error Apparently always returns True (is this how .put works with dupsort=True) Duplicates are inserted in lexocographic order not insertion order.

putVres(key, vals)

Use snKey() Write each entry from list of bytes receipt quinlets vals to key Quinlet is edig + spre + ssnu + sdig +sig Adds to existing receipts at key if any Returns True If at least one of vals is added as dup, False otherwise Duplicates are inserted in insertion order.

putWigs(key, vals)

Use dgKey() Write each entry from list of bytes indexed witness signatures vals to key Adds to existing signatures at key if any Returns True If no error Apparently always returns True (is this how .put works with dupsort=True) Duplicates are inserted in lexocographic order not insertion order.

reload()

Reload stored prefixes and Kevers from .habs

reopen(**kwa)

Open sub databases

Notes:

dupsort=True for sub DB means allow unique (key,pair) duplicates at a key. Duplicate means that is more than one value at a key but not a redundant copies a (key,value) pair per key. In other words the pair (key,value) must be unique both key and value in combination. Attempting to put the same (key,value) pair a second time does not add another copy.

Duplicates are inserted in lexocographic order by value, insertion order.

resolveVerifiers(pre=None, sn=0, dig=None)

Returns the Tholder and Verfers for the provided identifier prefix. Default pre is own .pre

Parameters:

• pre (str)

• sn (int)

• dig (str)

rotationMembers(pre: str)

Find rotation members of a multisig group aid.

Using the digs index to lookup member pres of a group aid

Parameters:

pre (str) – qb64 identifier prefix to find members

Returns:

qb64 identifier prefixes of rotation members for provided aid

Return type:

list

setAes(key, val)

Use dgKey() Write serialized source seal event couple val to key Overwrites existing val if any Returns True If val successfully written Else False

setDts(key, val)

Use dgKey() Write serialized event datetime stamp val to key Overwrites existing val if any Returns True If val successfully written Else False

setEvt(key, val)

Use dgKey() Write serialized event bytes val to key Overwrites existing val if any Returns True If val successfully written Else False

setFe(key, val)

Use fnKey() Write event digest bytes val to key Overwrites existing val if any Returns True If val successfully written Else False

setPde(key, val)

Use dgKey() Write serialized seal source couple to key (snu+dig) Overwrites existing val if any Returns True If val successfully written Else False

signingMembers(pre: str)

Find signing members of a multisig group aid.

Using the pubs index to find members of a signing group

Parameters:

pre (str) – qb64 identifier prefix to find members

Returns:

qb64 identifier prefixes of signing members for provided aid

Return type:

list

class keri.db.basing.BaserDoer(baser, **kwa)

Basic Baser Doer ( LMDB Database )

Attributes: (inherited)

done (bool): completion state:

True means completed Otherwise incomplete. Incompletion maybe due to close or abort.

.baser is Baser or LMDBer subclass

Properties: (inherited)

.tyme is float relative cycle time of associated Tymist .tyme obtained

via injected .tymth function wrapper closure.

.tymth is function wrapper closure returned by Tymist .tymeth() method.

When .tymth is called it returns associated Tymist .tyme. .tymth provides injected dependency on Tymist tyme base.

.tock is float, desired time in seconds between runs or until next run,

non negative, zero means run asap

Properties:

.wind  injects ._tymth dependency from associated Tymist to get its .tyme

.__call__ makes instance callable

Appears as generator function that returns generator

.do is generator method that returns generator

.enter is enter context action method

.recur is recur context action method or generator method

.exit is exit context method

.close is close context method

.abort is abort context method

Hidden:

._tymth is injected function wrapper closure returned by .tymen() of

associated Tymist instance that returns Tymist .tyme. when called.

._tock is hidden attribute for .tock property

__init__(baser, **kwa)

Inherited Parameters:

tymist is Tymist instance tock is float seconds initial value of .tock

Parameters:

instance (baser is Baser)

class keri.db.basing.EndAuthRecord(cid: str = '', roles: list[str] = <factory>)

Service Endpoint Authorization Record provides cross reference field for search purposes to find authorization for endpoint provider eid. The default is controller id, cid, and a role. used to lookup authorization in end authN database with keyspace given by (cid.role.eid) where cid is the authorizing controller for the eid (endpoint id) at the given role. The cid is usually a transferable identifier with a KEL but may be non-trans. The eid is usually a nontransferable identifier when its used for roles witness or watcher but may be transferable for other roles such as controller, judge, juror, public watcher, or registrar.

This is an embedded record type in a LocationRecord in the cids field

class keri.db.basing.EndpointRecord(allowed: bool | None = None, enabled: bool | None = None, name: str = '')

Service Endpoint ID (SEID) Record with fields and keys to manage endpoints by cid,role, and eid. Serves as aggregation mechanism for authorization and other functions such as UX naming with regards the endpoint.

The namespace is a tree of branches with each leaf at a specific (cid, role, eid). Retrieval by branch returns groups of leaves as appropriate for a cid braanch or cid.role branch. Database Keys are (cid, role, eid) where cid is attributable controller identifier (qb64 prefix) that has role(s) such as watcher, witness etc and eid is the identifier of the controller acting in a role i.e. watcher identifier.

allowed

AuthZ via reply message True means eid is allowed as controller of endpoint in role False means eid is disallowed as conroller of endpint in role None means eid is neither allowed or disallowed (no reply msg)

Type:

bool

enabled

AuthZ via expose message True means eid is enabled as controller of endpoint in role False means eid is disenabled as conroller of endpint in role None means eid is neither enabled or disenabled (no expose msg)

Type:

bool

name

user fieldly name for eid in role

Type:

str

An end authorization reply message is required from which the field values for this record are extracted. A routes of /end/role/eid/add /end/role/eid/cut Uses add-cut model with allowed field allowed==True eid is allowed (add) as endpoint provider for cid at role and name allowed==False eid is disallowed (cut) as endpoint provider for cid at role and name

{

“v” : “KERI10JSON00011c_”, “t” : “rep”, “d”: “EZ-i0d8JZAoTNZH3ULaU6JR2nmwyvYAfSVPzhzS6b5CM”, “dt”: “2020-08-22T17:50:12.988921+00:00”, “r” : “/end/role/add”, “a” : {

“cid”: “EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM”, “role”: “watcher”, # one of kering.Roles “eid”: “BrHLayDN-mXKv62DAjFLX1_Y5yEUe0vA9YPe_ihiKYHE”,

}

}

{

“v” : “KERI10JSON00011c_”, “t” : “rep”, “d”: “EZ-i0d8JZAoTNZH3ULaU6JR2nmwyvYAfSVPzhzS6b5CM”, “dt”: “2020-08-22T17:50:12.988921+00:00”, “r” : “/end/role/cut”, “a” : {

“cid”: “EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM”, “role”: “watcher”, # one of kering.Roles “eid”: “BrHLayDN-mXKv62DAjFLX1_Y5yEUe0vA9YPe_ihiKYHE”,

}

}

An end authorization expose message provides enablement via an exposure of and anchored seal to the expose message on the authorizing KEL.

class keri.db.basing.HabitatRecord(hid: str, mid: str | None = None, smids: list | None = None, rmids: list | None = None, sid: str | None = None, watchers: list[str] = <factory>)

Habitat application state information keyed by habitat name (baser.habs)

hid

identifier prefix of hab qb64

Type:

str

mid

group member identifier qb64 when hid is group

Type:

str | None

smids

group signing member identifiers qb64 when hid is group

Type:

list | None

rmids

group signing member identifiers qb64 when hid is group

Type:

list | None

watchers

(list[str]) = list of id prefixes qb64 of watchers

Type:

list[str]

class keri.db.basing.KeyStateRecord(vn: list[int] = <factory>, i: str = '', s: str = '0', p: str = '', d: str = '', f: str = '0', dt: str = '', et: str = '', kt: str = '0', k: list[str] = <factory>, nt: str = '0', n: list[str] = <factory>, bt: str = '0', b: list = <factory>, c: list[str] = <factory>, ee: ~keri.db.basing.StateEERecord = <factory>, di: str = '')

Key State information keyed by Identifier Prefix of associated KEL. For local AIDs that correspond to Habs this is the Hab AID. (see baser.state at ‘stts’)

vn

version number [major, minor]

Type:

list[int]

i

identifier prefix qb64

Type:

str

s

sequence number of latest event in KEL as hex str

Type:

str

p

prior event digest qb64

Type:

str

d

latest event digest qb64

Type:

str

f

first seen ordinal number of latest event in KEL as hex str

Type:

str

dt

datetime iso-8601 of key state record update, usually now

Type:

str

et

latest event packet type

Type:

str

kt

signing threshold sith

Type:

str

k

signing keys qb64

Type:

list[str]

nt

next prerotated threshold sith

Type:

str

n

pre-rotation keys qb64

Type:

list[str]

bt

backer threshold hex num

Type:

str

b

backer aids qb64

Type:

list[str]

c

config traits

Type:

list[str]

ee

instance corresponds to StateEstEvent namedtuple

s = sn of latest est event as lowercase hex string no leading zeros, d = SAID digest qb64 of latest establishment event br = backer (witness) remove list (cuts) from latest est event ba = backer (witness) add list (adds) from latest est event

Type:

StateEERecord

di

delegator aid qb64 or empty str if not delegated

Type:

str

Note: the seal anchor dict ‘a’ field is not included in the state notice because it may be verbose and would impede the main purpose of a notic which is to trigger the download of the latest events, which would include the anchored seals.

class keri.db.basing.LocationRecord(url: str)

Service Endpoint Record with url for endpoint of a given scheme The eid is usually a nontransferable identifier when its used for roles witness or watcher but may be transferable for other roles such as controller, judge, juror, public watcher, or registrar.

Database Keys are (eid, scheme) where eid is service endpoint identifier (qb64 prefix) and scheme is the url protocol scheme (tcp, https).

A loc reply message is required from which the values of this database record are extracted. route is /loc/scheme Uses enact-anul model To nullify endpoint set url field to empty.

An end authorization reply message is also required to authorize the eid as endpoint provider for cid at role. See EndpointRecord

{

“v” : “KERI10JSON00011c_”, “t” : “rep”, “d”: “EZ-i0d8JZAoTNZH3ULaU6JR2nmwyvYAfSVPzhzS6b5CM”, “dt”: “2020-08-22T17:50:12.988921+00:00”, “r” : “/loc/scheme”, “a” : {

“eid”: “BrHLayDN-mXKv62DAjFLX1_Y5yEUe0vA9YPe_ihiKYHE”, “scheme”: “http”, # one of kering.Schemes “url”: “http://localhost:8080/watcher/wilma”,

}

}

{

“v” : “KERI10JSON00011c_”, “t” : “rep”, “d”: “EZ-i0d8JZAoTNZH3ULaU6JR2nmwyvYAfSVPzhzS6b5CM”, “dt”: “2020-08-22T17:50:12.988921+00:00”, “r” : “/loc/scheme”, “a” : {

“eid”: “BrHLayDN-mXKv62DAjFLX1_Y5yEUe0vA9YPe_ihiKYHE”, “scheme”: “http”, # one of kering.Schemes “url”: “”,

}

}

class keri.db.basing.OobiQueryRecord(cid: str | None = None, role: str | None = None, eids: list[str] = <factory>, scheme: str | None = None)

Keyed by cid in oobis field of HabitatRecord (oobiq). Determines which endpoints are allowed as responses to oobi query for cid cid is aid of controller with endpoint. role is functional role of endpoint provider eids are aids of endpoint providers for a role. schemes are url schemes of endpoint url

This record acts as a constraint tree with path cid.role.eid.scheme. Partial path specification permits the resultant subtree. Full path specification permits only the leaf. No record could be either all allowed or none allowed depending on the habitat type or function. Defaults rules for each pairing of querier and replier.

This functionality is aspirational for now. It is likely that we need an endpoint identity constraint graph to properly model the endpoint relationship permissing constraint structure. For now we just operate with a promiscuous constraint policy for endpoint discovery .

Usage:

oobiqs: dict[str, OobiQueryRecord] = field(default_factory=dict)

class keri.db.basing.OobiRecord(oobialias: str | None = None, said: str | None = None, cid: str | None = None, eid: str | None = None, role: str | None = None, date: str | None = None, state: str | None = None, urls: list | None = None)

Keyed by CID (AID) and role, the minimum information needed for any OOBI

class keri.db.basing.RawRecord

RawRecord is base class for dataclasses that provides private utility methods for representing the dataclass as some other format like dict, json bytes, cbor bytes, mgpk bytes as a raw format. Typically uses case is to transform dataclass into dict or serialization of its transformation into dict so that it can be included in messages or stored in a database.

class keri.db.basing.StateEERecord(s: str = '0', d: str = '', br: list = <factory>, ba: list = <factory>)

Corresponds to StateEstEvent namedtuple used as sub record in KeyStateRecord for latest establishment event associated with current key state

s

sequence number of latest est evt lowercase hex no leading zeros

Type:

str

d

SAID qb64 of latest est evt

Type:

str

br

backer aids qb64 remove list (cuts) from latest est event

Type:

list[str]

ba

backer aids qb64 add list (adds) from latest est event

Type:

list[str]

class keri.db.basing.TopicsRecord(topics: dict)

Tracks the last message topic index retrieved from the witness mailbox Database Key is the identifier prefix of the witness that is storing events in a mailbox. (baser.tops)

class keri.db.basing.WellKnownAuthN(url: str, dt: str)

Each WellKnownAuthN represents a successfully resolved .well-known OOBI URL keyed by the AID of the OOBI tuple embedded in the URL

class keri.db.basing.dbdict(*pa, **kwa)

Subclass of dict that has db as attribute and employs read through cache from db Baser.stts of kever states to reload kever from state in database when not found in memory as dict item.

get(k, default=None)

Override of dict get method

Parameters:

• k (str) – key for dict

• default – default value to return if not found

Returns:

converted from underlying dict or database

Return type:

kever

keri.db.basing.openDB(*, cls=None, name='test', **kwa)

Returns contextmanager generated by openLMDB but with Baser instance as default

keri.db.basing.reopenDB(db, clear=False, **kwa)

Context manager wrapper LMDB DB instances. Repens and closes db.path and db.env LMDB

Parameters:

• db (LMDBer) – instance with LMDB environment at .env

• clear (bool) – True means clear directory after close

Usage:

with reopenDB(baser) as env:

env. ….

keri.db.dbing

keri.db.dbing module

import lmdb db = lmdb.open(“/tmp/keri_db_setup_test”) db.max_key_size() 511

# create named dbs (core and tables)

gDbEnv.open_db(b’core’) gDbEnv.open_db(b’hid2did’) # table of dids keyed by hids gDbEnv.open_db(b’did2offer’, dupsort=True) # table of offer expirations keyed by offer relative dids gDbEnv.open_db(b’anon’, dupsort=True) # anonymous messages gDbEnv.open_db(b’expire2uid’, dupsort=True) # expiration to uid anon

The dupsort, integerkey, integerdup, and dupfixed parameters are ignored if the database already exists. The state of those settings are persistent and immutable per database. See _Database.flags() to view the state of those options for an opened database. A consequence of the immutability of these flags is that the default non-named database will never have these flags set.

So only need to set dupsort first time opened each other opening does not need to call it

May want to use buffers for reads of immutable serializations such as events and sigs. Anything not read modify write but read only.

“{:032x}”.format(1024) ‘00000000000000000000000000000400’

h = [“00”, “01”, “02”, “0a”, “0f”, “10”, “1a”, “11”, “1f”, “f0”, “a0”] h.sort() h [‘00’, ‘01’, ‘02’, ‘0a’, ‘0f’, ‘10’, ‘11’, ‘1a’, ‘1f’, ‘a0’, ‘f0’]

l [‘a’, ‘aa’, ‘b’, ‘ba’, ‘aaa’, ‘baa’] l.sort() l [‘a’, ‘aa’, ‘aaa’, ‘b’, ‘ba’, ‘baa’]

class keri.db.dbing.LMDBer(readonly=False, **kwa)

LBDBer base class for LMDB manager instances. Creates a specific instance of an LMDB database directory and environment.

Attributes: (inherited)

name (str): unique path component used in directory or file path name base (str): another unique path component inserted before name temp (bool): True means use /tmp directory headDirPath is head directory path path is full directory path perm is numeric os permissions for directory and/or file(s) filed (bool): True means .path ends in file.

False means .path ends in directory

mode (str): file open mode if filed fext (str): file extension if filed file (File) opened is Boolean, True means directory created and if file then file

is opened. False otherwise

env

LMDB main (super) database environment

Type:

lmdb.env

readonly

True means open LMDB env as readonly

Type:

bool

Properties:

File/Directory Creation Mode Notes:

.Perm provides default restricted access permissions to directory and/or files stat.S_ISVTX | stat.S_IRUSR | stat.S_IWUSR | stat.S_IXUSR 0o1700==960

stat.S_ISVTX is Sticky bit. When this bit is set on a directory it means

that a file in that directory can be renamed or deleted only by the owner of the file, by the owner of the directory, or by a privileged process. When this bit is set on a file it means nothing

stat.S_IRUSR Owner has read permission. stat.S_IWUSR Owner has write permission. stat.S_IXUSR Owner has execute permission.

__init__(readonly=False, **kwa)

Setup main database directory at .dirpath. Create main database environment at .env using .path.

Parameters:

• name (str) – directory path name differentiator directory/file When system employs more than one keri installation, name allows differentiating each instance by name

• base (str) – optional directory path segment inserted before name that allows further differentiation with a hierarchy. “” means optional.

• temp (bool) – assign to .temp True then open in temporary directory, clear on close Otherwise then open persistent directory, do not clear on close

• headDirPath (str) – optional head directory pathname for main database Default .HeadDirPath

• mode (str) – optional numeric os dir permissions for database directory and database files. Default .DirMode

• reopen (bool) – True means (re)opened by this init False means not (re)opened by this init but later

• clear (bool) – True means remove directory upon close if reopon False means do not remove directory upon close if reopen

• reuse (bool) – True means reuse self.path if already exists False means do not reuse but remake self.path

• clean (bool) – True means path uses clean tail variant False means path uses normal tail variant

• filed (bool) – True means .path is file path not directory path False means .path is directory path not file path

• mode – File open mode when filed

• fext (str) – File extension when filed

• readonly (bool) – True means open database in readonly mode False means open database in read/write mode

addIoSetVal(db, key, val, *, sep=b'.')

Add val to insertion ordered set of values all with the same apparent effective key if val not already in set of vals at key. Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.

Returns:

True is added to set. False if already in set.

Return type:

result (bool)

Parameters:

• db (lmdb._Database) – instance of named sub db with dupsort==False

• key (bytes) – Apparent effective key

• val (bytes) – serialized value to add

addIoVal(db, key, val)

Add val bytes as dup in insertion order to key in db Adds to existing values at key if any Returns True if written else False if val is already a dup Actual value written include prepended proem ordinal Assumes DB opened with dupsort=True

Because lmdb is lexocographic an insertion ordering proem is prepended to all values that makes lexocographic order that same as insertion order Duplicates are ordered as a pair of key plus value so prepending prefix to each value changes duplicate ordering. Proem is 17 characters long. With 16 character hex string followed by ‘.’.

Parameters:

• dupsort=False (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

• written (val is bytes of value to be)

addVal(db, key, val)

Add val bytes as dup to key in db Adds to existing values at key if any Returns True if written else False if dup val already exists

Duplicates are inserted in lexocographic order not insertion order. Lmdb does not insert a duplicate unless it is a unique value for that key.

Does inclusion test to dectect of duplicate already exists Uses a python set for the duplicate inclusion test. Set inclusion scales with O(1) whereas list inclusion scales with O(n).

Parameters:

• dupsort=True (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

• written (val is bytes of value to be)

appendIoSetVal(db, key, val, *, sep=b'.')

Append val to insertion ordered set of values all with the same apparent effective key. Assumes val is not already in set. Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.

Returns:

hidden insertion ordering ordinal of appended val

Return type:

ion (int)

Parameters:

• db (lmdb._Database) – instance of named sub db with dupsort==False

• key (bytes) – Apparent effective key

• val (bytes) – value to append

appendOrdValPre(db, pre, val)

Appends val in order after last previous key with same pre in db. Returns ordinal number in, on, of appended entry. Appended on is 1 greater than previous latest on. Uses onKey(pre, on) for entries.

Append val to end of db entries with same pre but with on incremented by 1 relative to last preexisting entry at pre.

Parameters:

• dupsort=False (db is opened named sub db with)

• event (pre is bytes identifier prefix for)

• digest (val is event)

close(clear=False)

Close lmdb at .env and if clear or .temp then remove lmdb directory at .path :param clear is boolean: :param True means clear lmdb directory:

cnt(db)

Return count of values in db, or zero otherwise

Parameters:

dupsort=True (db is opened named sub db with)

cntIoSetVals(db, key, *, sep=b'.')

Count all values with the same apparent effective key. Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.

Returns:

count values in set at apparent effective key

Return type:

count (int)

Parameters:

• db (lmdb._Database) – instance of named sub db with dupsort==False

• key (bytes) – Apparent effective key

cntIoVals(db, key)

Return count of dup values at key in db, or zero otherwise Assumes DB opened with dupsort=True

Parameters:

• dupsort=True (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

cntVals(db, key)

Return count of dup values at key in db, or zero otherwise

Parameters:

• dupsort=True (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

cntValsAllPre(db, pre, on=0)

Returns (int): count of of all vals with same pre in key but different

on in key in db starting at ordinal number on of pre

Does not count dups

Parameters:

• db (db is opened named sub)

• pre.on (pre is bytes of key within sub db's keyspace)

delIoSetIokey(db, iokey)

Deletes val at at actual iokey that includes ordinal key suffix.

Returns:

True if val was deleted at iokey. False otherwise

if no val at iokey

Return type:

result (bool)

Parameters:

• db (lmdb._Database) – instance of named sub db with dupsort==False

• iokey (bytes) – actual key with ordinal key suffix

delIoSetVal(db, key, val, *, sep=b'.')

Deletes val at apparent effective key if exists. Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.

Because the insertion order of val is not provided must perform a linear search over set of values.

Another problem is that vals may get added and deleted in any order so the max suffix ion may creep up over time. The suffix ordinal max > 2**16 is an impossibly large number, however, so the suffix will not max out practically.But its not the most elegant solution.

In some cases a better approach would be to use getIoSetItemsIter which returns the actual iokey not the apparent effetive key so can delete using the iokey without searching for the value. This is most applicable when processing escrows where all the escrowed items are processed linearly and one needs to delete some of them in stride with their processing.

Returns:

True if val was deleted at key. False otherwise

if val not found at key

Return type:

result (bool)

Parameters:

• db (lmdb._Database) – instance of named sub db with dupsort==False

• key (bytes) – Apparent effective key

• val (bytes) – value to delete

delIoSetVals(db, key, *, sep=b'.')

Deletes all values at apparent effective key. Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.

Returns:

True if values were deleted at key. False otherwise

if no values at key

Return type:

result (bool)

Parameters:

• db (lmdb._Database) – instance of named sub db with dupsort==False

• key (bytes) – Apparent effective key

delIoVal(db, key, val)

Deletes dup io val at key in db. Performs strip search to find match. Strips proems and then searches. Returns True if delete else False if val not present Assumes DB opened with dupsort=True

Duplicates at a given key preserve insertion order of duplicate. Because lmdb is lexocographic an insertion ordering proem is prepended to all values that makes lexocographic order that same as insertion order Duplicates are ordered as a pair of key plus value so prepending proem to each value changes duplicate ordering. Proem is 33 characters long. With 32 character hex string followed by ‘.’ for essentially unlimited number of values which will be limited by memory.

Does a linear search so not very efficient when not deleting from the front. This is hack for supporting escrow which needs to delete individual dup. The problem is that escrow is not fixed buts stuffs gets added and deleted which just adds to the value of the proem. 2**16 is an impossibly large number so the proem will not max out practically. But its not and elegant solution. So maybe escrows need to use a different approach. But really didn’t want to add another database just for escrows.

Parameters:

• dupsort=False (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

• proem (val is bytes of value to be deleted without intersion ordering)

delIoVals(db, key)

Deletes all values at key in db if key present. Returns True If key exists

Parameters:

• dupsort=True (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

delTopVal(db, key=b'')

Deletes all values in branch of db given top key.

Returns:

True if values were deleted at key. False otherwise

if no values at key

Return type:

result (bool)

Parameters:

• db (lmdb._Database) – instance of named sub db with dupsort==False

• key (bytes) – truncated top key, a key space prefix to get all the items from multiple branches of the key space. If top key is empty then gets all items in database

Works for both dupsort==False and dupsort==True Because cursor.iternext() advances cursor after returning item its safe to delete the item within the iteration loop.

Raises StopIteration Error when empty.

delVal(db, key)

Deletes value at key in db. Returns True If key exists in database Else False

Parameters:

• dupsort=False (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

delVals(db, key, val=b'')

Deletes all values at key in db if val=b’’ else deletes the dup that equals val Returns True If key (and val if not empty) exists in db Else False

Parameters:

• dupsort=True (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

• delete (val is bytes of dup val at key to)

getAllItemIter(db, key=b'', split=True, sep=b'.')

Returns iterator of item duple (key, val), at each key over all keys in db. If split is true then the key is split at sep and instead of returing duple it results tuple with one entry for each key split as well as the value.

Works for both dupsort==False and dupsort==True

Raises StopIteration Error when empty.

Parameters:

• dupsort=False (db is opened named sub db with)

• replay (key is key location in db to resume) – If empty then start at first key in database

:param : If empty then start at first key in database :param split: True means split key at sep before returning :type split: bool :param sep: separator char for key :type sep: bytes

getAllOrdItemAllPreIter(db, key=b'')

Returns iterator of triple item, (pre, on, dig), at each key over all ordinal numbered keys for all prefixes in db. Values are sorted by onKey(pre, on) where on is ordinal number int. Each returned item is triple (pre, on, dig) where pre is identifier prefix, on is ordinal number int and dig is event digest for lookup in .evts sub db.

Raises StopIteration Error when empty.

Parameters:

• dupsort=False (db is opened named sub db with)

• replay (key is key location in db to resume) – If empty then start at first key in database

:param : If empty then start at first key in database

getAllOrdItemPreIter(db, pre, on=0)

Returns iterator of duple item, (on, dig), at each key over all ordinal numbered keys with same prefix, pre, in db. Values are sorted by onKey(pre, on) where on is ordinal number int. Returned items are duples of (on, dig) where on is ordinal number int and dig is event digest for lookup in .evts sub db.

Raises StopIteration Error when empty.

Parameters:

• dupsort=False (db is opened named sub db with)

• prefix (pre is bytes of itdentifier)

• replay (on is int ordinal number to resume)

getIoItemsNext(db, key=b'', skip=True)

Return list of all dup items at next key after key in db in insertion order. Item is (key, val) with proem stripped from val stored in db. If key == b’’ then returns list of dup items at first key in db. If skip is False and key is not empty then returns dup items at key Returns empty list if no entries at next key after key

If key is empty then gets io items (key, io value) at first key in db Use the return key from items as next key for next call to function in order to iterate through the database

Assumes DB opened with dupsort=True

Parameters:

• dupsort=True (db is opened named sub db with)

• string (skip is Boolean If True skips to next key if key is not empty)

• string – Othewise don’t skip for first pass

getIoItemsNextIter(db, key=b'', skip=True)

Return iterator of all dup items at next key after key in db in insertion order. Item is (key, val) with proem stripped from val stored in db. If key = b’’ then returns list of dup items at first key in db. If skip is False and key is not empty then returns dup items at key Raises StopIteration Error when no remaining dup items = empty.

If key is empty then gets io items (key, io value) at first key in db Use the return key from items as next key for next call to function in order to iterate through the database

Assumes DB opened with dupsort=True

Parameters:

• dupsort=True (db is opened named sub db with)

• empty (key is bytes of key within sub db's keyspace or)

• string (skip is Boolean If True skips to next key if key is not empty) – Othewise don’t skip for first pass

getIoSetItems(db, key, *, ion=0, sep=b'.')

Returns:

list of tuples (iokey, val) of entries in set of with

same apparent effective key. iokey includes the ordinal key suffix

Uses hidden ordinal key suffix for insertion ordering.

Return type:

items (list)

Parameters:

• db (lmdb._Database) – instance of named sub db with dupsort==False

• key (bytes) – Apparent effective key

• ion (int) – starting ordinal value, default 0

getIoSetItemsIter(db, key, *, ion=0, sep=b'.')

Returns:

iterator over insertion ordered set of values at same apparent effective key where each iteration returns tuple (iokey, val). iokey includes the ordinal key suffix. Uses hidden ordinal key suffix for insertion ordering.

Return type:

items (abc.Iterator)

Raises StopIteration Error when empty.

Parameters:

• db (lmdb._Database) – instance of named sub db with dupsort==False

• key (bytes) – Apparent effective key

• ion (int) – starting ordinal value, default 0

getIoSetValLast(db, key, *, sep=b'.')

Returns:

last added empty at apparent effective key if any,

otherwise None if no entry

Return type:

val (bytes)

Uses hidden ordinal key suffix for insertion ordering.

The suffix is appended and stripped transparently.

Parameters:

• db (lmdb._Database) – instance of named sub db with dupsort==False

• key (bytes) – Apparent effective key

getIoSetVals(db, key, *, ion=0, sep=b'.')

Returns:

the insertion ordered set of values at same apparent effective key. Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.

Return type:

ioset (oset)

Parameters:

• db (lmdb._Database) – instance of named sub db with dupsort==False

• key (bytes) – Apparent effective key

• ion (int) – starting ordinal value, default 0

getIoSetValsIter(db, key, *, ion=0, sep=b'.')

Returns:

iterator over insertion ordered set of values at same apparent effective key. Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.

Return type:

ioset (abc.Iterator)

Raises StopIteration Error when empty.

Parameters:

• db (lmdb._Database) – instance of named sub db with dupsort==False

• key (bytes) – Apparent effective key

• ion (int) – starting ordinal value, default 0

getIoValLast(db, key)

Return last added dup value at key in db in insertion order Returns None no entry at key Removes prepended proem ordinal from val before returning Assumes DB opened with dupsort=True

Parameters:

• dupsort=True (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

getIoValLastAllPreIter(db, pre, on=0)

Returns iterator of last only of dup vals of each key in insertion order for all entries with same prefix across all sequence numbers in increasing order without gaps starting with on (default = 0). Stops if gap or different pre. Assumes that key is combination of prefix and sequence number given by .snKey(). Removes prepended proem ordinal from each val before returning

Raises StopIteration Error when empty.

Duplicates are retrieved in insertion order.

Because lmdb is lexocographic an insertion ordering proem is prepended to all values that makes lexocographic order that same as insertion order Duplicates are ordered as a pair of key plus value so prepending prefix to each value changes duplicate ordering. Proem is 17 characters long. With 16 character hex string followed by ‘.’.

Parameters:

• dupsort=True (db is opened named sub db with)

• key (pre is bytes of itdentifier prefix prepended to sn in) – within sub db’s keyspace

• on (int) – ordinal number to being iteration

getIoVals(db, key)

Return list of duplicate values at key in db in insertion order Returns empty list if no entry at key Removes prepended proem ordinal from each val before returning Assumes DB opened with dupsort=True

Because lmdb is lexocographic an insertion ordering proem is prepended to all values that makes lexocographic order that same as insertion order Duplicates are ordered as a pair of key plus value so prepending prefix to each value changes duplicate ordering. Proem is 17 characters long. With 16 character hex string followed by ‘.’.

Parameters:

• dupsort=True (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

getIoValsAllPreBackIter(db, pre, on=0)

Returns iterator of all dup vals in insertion order for all entries with same prefix across all sequence numbers in decreasing order without gaps between ordinals at a given pre. Starting with on (default = 0) as begining ordinal number or sequence number. Stops if gap or different pre. Assumes that key is combination of prefix and sequence number given by .snKey(). Removes prepended proem ordinal from each val before returning

Raises StopIteration Error when empty.

Duplicates are retrieved in insertion order.

Because lmdb is lexocographic an insertion ordering proem is prepended to all values that makes lexocographic order that same as insertion order Duplicates are ordered as a pair of key plus value so prepending prefix to each value changes duplicate ordering. Proem is 17 characters long. With 16 character hex string followed by ‘.’.

Parameters:

• dupsort=True (db is opened named sub db with)

• key (pre is bytes of identifier prefix prepended to sn in) – within sub db’s keyspace

• on (int) – is ordinal number to begin iteration

getIoValsAllPreIter(db, pre, on=0)

Returns iterator of all dup vals in insertion order for all entries with same prefix across all ordinal numbers in increasing order without gaps between ordinal numbers starting with on, default 0. Stops if gap or different pre. Assumes that key is combination of prefix and sequence number given by .snKey(). Removes prepended proem ordinal from each val before returning

Raises StopIteration Error when empty.

Duplicates are retrieved in insertion order.

Because lmdb is lexocographic an insertion ordering proem is prepended to all values that makes lexocographic order that same as insertion order Duplicates are ordered as a pair of key plus value so prepending prefix to each value changes duplicate ordering. Proem is 17 characters long. With 16 character hex string followed by ‘.’.

Parameters:

• dupsort=True (db is opened named sub db with)

• pre (bytes | str) – of itdentifier prefix prepended to sn in key within sub db’s keyspace

• on (int) – ordinal number to begin iteration at

getIoValsAnyPreIter(db, pre, on=0)

Returns iterator of all dup vals in insertion order for any entries with same prefix across all ordinal numbers in order including gaps between ordinals at a given pre. Staring with on (default = 0). Stops when pre is different.

Duplicates that may be deleted such as duplicitous event logs need to be able to iterate across gaps in ordinal number.

Assumes that key is combination of prefix and sequence number given by .snKey(). Removes prepended proem ordinal from each val before returning

Raises StopIteration Error when empty.

Duplicates are retrieved in insertion order. Because lmdb is lexocographic an insertion ordering proem is prepended to all values that makes lexocographic order that same as insertion order Duplicates are ordered as a pair of key plus value so prepending prefix to each value changes duplicate ordering. Proem is 17 characters long. With 16 character hex string followed by ‘.’.

Parameters:

• dupsort=True (db is opened named sub db with)

• key (pre is bytes of itdentifier prefix prepended to sn in) – within sub db’s keyspace

• on (int) – beginning ordinal number to start iteration

getIoValsIter(db, key)

Return iterator of all duplicate values at key in db in insertion order Raises StopIteration Error when no remaining dup items = empty. Removes prepended proem ordinal from each val before returning Assumes DB opened with dupsort=True

Because lmdb is lexocographic an insertion ordering proem is prepended to all values that makes lexocographic order that same as insertion order Duplicates are ordered as a pair of key plus value so prepending prefix to each value changes duplicate ordering. Proem is 17 characters long. With 16 character hex string followed by ‘.’.

Parameters:

• dupsort=True (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

getTopItemIter(db, key=b'')

Iterates over branch of db given by key

Returns:

iterator of (full key, val) tuples over a

branch of the db given by top key where: full key is full database key for val not truncated top key

Return type:

items (abc.Iterator)

Works for both dupsort==False and dupsort==True Because cursor.iternext() advances cursor after returning item its safe to delete the item within the iteration loop.

Raises StopIteration Error when empty.

Parameters:

• db (lmdb._Database) – instance of named sub db with dupsort==False

• key (bytes) – truncated top key, a key space prefix to get all the items from multiple branches of the key space. If top key is empty then gets all items in database

getVal(db, key)

Return val at key in db Returns None if no entry at key

Parameters:

• dupsort=False (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

getValLast(db, key)

Return last dup value at key in db in lexicographic order Returns None no entry at key Assumes DB opened with dupsort=True

Parameters:

• dupsort=True (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

getVals(db, key)

Return list of values at key in db Returns empty list if no entry at key

Duplicates are retrieved in lexocographic order not insertion order.

Parameters:

• dupsort=True (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

getValsIter(db, key)

Return iterator of all dup values at key in db Raises StopIteration error when done or if empty

Duplicates are retrieved in lexocographic order not insertion order.

Parameters:

• dupsort=True (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

putIoSetVals(db, key, vals, *, sep=b'.')

Add each val in vals to insertion ordered set of values all with the same apparent effective key for each val that is not already in set of vals at key. Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.

Returns:

True is added to set. False if already in set.

Return type:

result (bool)

Parameters:

• db (lmdb._Database) – instance of named sub db with dupsort==False

• key (bytes) – Apparent effective key

• vals (abc.Iterable) – serialized values to add to set of vals at key

putIoVals(db, key, vals)

Write each entry from list of bytes vals to key in db in insertion order Adds to existing values at key if any Returns True If at least one of vals is added as dup, False otherwise Assumes DB opened with dupsort=True

Duplicates at a given key preserve insertion order of duplicate. Because lmdb is lexocographic an insertion ordering proem is prepended to all values that makes lexocographic order that same as insertion order Duplicates are ordered as a pair of key plus value so prepending proem to each value changes duplicate ordering. Proem is 33 characters long. With 32 character hex string followed by ‘.’ for essentiall unlimited number of values which will be limited by memory. With prepended proem ordinal must explicity check for duplicate values before insertion. Uses a python set for the duplicate inclusion test. Set inclusion scales with O(1) whereas list inclusion scales with O(n).

Parameters:

• dupsort=False (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

• written (vals is list of bytes of values to be)

putVal(db, key, val)

Write serialized bytes val to location key in db Does not overwrite. Returns True If val successfully written Else False Returns False if val at key already exitss

Parameters:

• dupsort=False (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

• written (val is bytes of value to be)

putVals(db, key, vals)

Write each entry from list of bytes vals to key in db Adds to existing values at key if any Returns True If only one first written val in vals Else False Apparently always returns True (is this how .put works with dupsort=True)

Duplicates are inserted in lexocographic order not insertion order. Lmdb does not insert a duplicate unless it is a unique value for that key.

Parameters:

• dupsort=True (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

• written (vals is list of bytes of values to be)

reopen(readonly=False, **kwa)

Open if closed or close and reopen if opened or create and open if not if not preexistent, directory path for lmdb at .path and then Open lmdb and assign to .env

Parameters:

• temp (bool) – assign to .temp True means open in temporary directory, clear on close False means open persistent directory, do not clear on close

• headDirPath (str) – optional head directory pathname for main database Default .HeadDirpath

• perm (int) – optional numeric os dir permissions for database directory and database files. Default .Perm

• clear (bool) – True means remove directory upon close False means do not remove directory upon close

• reuse (bool) – True means reuse self.path if already exists False means do not reuse but remake self.path

• clean (bool) – True means path uses clean tail variant False means path uses normal tail variant

• mode (str) – file open mode when .filed

• fext (str) – File extension when .filed

• readonly (bool) – True means open database in readonly mode False means open database in read/write mode

setIoSetVals(db, key, vals, *, sep=b'.')

Erase all vals at key and then add unique vals as insertion ordered set of values all with the same apparent effective key. Uses hidden ordinal key suffix for insertion ordering. The suffix is appended and stripped transparently.

Returns:

True is added to set.

Return type:

result (bool)

Parameters:

• db (lmdb._Database) – instance of named sub db with dupsort==False

• key (bytes) – Apparent effective key

• vals (abc.Iterable) – serialized values to add to set of vals at key

setVal(db, key, val)

Write serialized bytes val to location key in db Overwrites existing val if any Returns True If val successfully written Else False

Parameters:

• dupsort=False (db is opened named sub db with)

• keyspace (key is bytes of key within sub db's)

• written (val is bytes of value to be)

keri.db.dbing.clearDatabaserDir(path)

Remove directory path

keri.db.dbing.dgKey(pre, dig)

Returns bytes DB key from concatenation of ‘.’ with qualified Base64 prefix bytes pre and qualified Base64 bytes digest of serialized event If pre or dig are str then converts to bytes

keri.db.dbing.dtKey(pre, dts)

Returns bytes DB key from concatenation of ‘|’ qualified Base64 prefix bytes pre and bytes dts datetime string of extended tz aware ISO8601 datetime of event

‘2021-02-13T19:16:50.750302+00:00’

keri.db.dbing.fnKey(pre, sn)

Returns bytes DB key from concatenation with ‘.’ of qualified Base64 prefix bytes pre and int ordinal number of event, such as sequence number or first seen order number.

keri.db.dbing.onKey(pre, sn)

Returns bytes DB key from concatenation with ‘.’ of qualified Base64 prefix bytes pre and int ordinal number of event, such as sequence number or first seen order number.

keri.db.dbing.openLMDB(*, cls=None, name='test', temp=True, **kwa)

Context manager wrapper LMDBer instances. Defaults to temporary databases. Context ‘with’ statements call .close on exit of ‘with’ block

Parameters:

• instance (cls is Class instance of subclass)

• databasers (name is str name of LMDBer dirPath so can have multiple) – at different directory path names thar each use different name

• Boolean (temp is) – Otherwise open in persistent directory, do not clear on close

• directory (True means open in temporary) – Otherwise open in persistent directory, do not clear on close

• close (clear on) – Otherwise open in persistent directory, do not clear on close

Usage:

with openDatabaser(name=”gen1”) as baser1:

baser1.env ….

with openDatabaser(name=”gen2, cls=Baser)

wl.close(clear=True if wl.temp else False)

keri.db.dbing.snKey(pre, sn)

Returns bytes DB key from concatenation with ‘.’ of qualified Base64 prefix bytes pre and int ordinal number of event, such as sequence number or first seen order number.

keri.db.dbing.splitKey(key, sep=b'.')

Returns duple of pre and either dig or on, sn, fn str or dts datetime str by splitting key at bytes sep Accepts either bytes or str key and returns same type Raises ValueError if key does not split into exactly two elements

Parameters:

• sep (key is database key with split at)

• b'.' (sep is bytes separator character. default is)

keri.db.dbing.splitKeyDT(key)

Returns list of pre and dts converted to datetime from key dts is TZ aware Iso8601 ‘2021-02-13T19:16:50.750302+00:00’

Accepts either bytes or str key

keri.db.dbing.splitKeyFN(key)

Returns list of pre and int on from key Accepts either bytes or str key ordinal number appears in key in hex format

keri.db.dbing.splitKeyON(key)

Returns list of pre and int on from key Accepts either bytes or str key ordinal number appears in key in hex format

keri.db.dbing.splitKeySN(key)

Returns list of pre and int on from key Accepts either bytes or str key ordinal number appears in key in hex format

keri.db.dbing.suffix(key: bytes | str | memoryview, ion: int, *, sep: bytes | str = b'.')

Returns:

actual DB key after concatenating suffix as hex version of insertion ordering ordinal int ion using separator sep.

Return type:

iokey (bytes)

Parameters:

• key (Union[bytes, str]) – apparent effective database key (unsuffixed)

• ion (int)) – insertion ordering ordinal for set of vals

• sep (bytes) – separator character(s) for concatenating suffix

keri.db.dbing.unsuffix(iokey: bytes | str | memoryview, *, sep: bytes | str = b'.')

Returns:

(key, ion) by splitting iokey at rightmost separator sep

strip off suffix, where key is bytes apparent effective DB key and ion is the insertion ordering int converted from stripped of hex suffix

Return type:

result (tuple)

Parameters:

• iokey (Union[bytes, str]) – apparent effective database key (unsuffixed)

• sep (bytes) – separator character(s) for concatenating suffix

keri.db.escrowing

keri.core.escrowing module

keri.db.koming

KERI keri.db.koming module

class keri.db.koming.DupKomer(db: LMDBer, *, subkey: str = 'recs.', schema: Type[dataclass], kind: str = 'JSON', **kwa)

Duplicate Keyspace Object Mapper factory class that supports multiple entries a given database key (lmdb dupsort == True).

Do not use if Komer schema instance serialized is greater than 511 bytes. This is a limitation of dupsort==True sub dbs in LMDB

__init__(db: LMDBer, *, subkey: str = 'recs.', schema: Type[dataclass], kind: str = 'JSON', **kwa)

Parameters:

• db (dbing.LMDBer) – base db

• schema (Type[dataclass]) – reference to Class definition for dataclass sub class

• subkey (str) – LMDB sub database key

• kind (str) – serialization/deserialization type

add(keys: str | Iterable, val: dataclass)

Add val to vals at key made from keys. Does not overwrite. Adds to existing dup values at key if any. Duplicate means another entry at the same key but the entry is still a unique value. Duplicates are inserted in lexocographic order not insertion order. Lmdb does not insert a duplicate unless it is a unique value for that key.

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• val (dataclass) – instance of type self.schema

Returns:

True means unique value among duplications,

False means duplicte of same value already exists.

Return type:

result (bool)

cnt(keys: str | Iterable)

Return count of dup values at key made from keys, zero otherwise

Parameters:

keys (tuple) – of key strs to be combined in order to form key

get(keys: str | Iterable)

Gets dup vals list at key made from keys

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

each item in list is instance of type self.schema

empty list if no entry at keys

Return type:

vals (list)

getIter(keys: str | Iterable)

Gets dup vals iterator at key made from keys

Duplicates are retrieved in lexocographic order not insertion order.

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

vals each of type self.schema. Raises StopIteration when done

Return type:

iterator

getLast(keys: str | Iterable)

Gets last dup val at key made from keys

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

instance of type self.schema

None if no entry at keys

Return type:

val (Type[dataclass])

pin(keys: str | Iterable, vals: list)

Pins (sets) vals at key made from keys. Overwrites. Removes all pre-existing dup vals and replaces them with vals

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• vals (list) – dataclass instances each of type self.schema as values

Returns:

True If successful, False otherwise.

Return type:

result (bool)

put(keys: str | Iterable, vals: list)

Puts all vals at key made from keys. Does not overwrite. Adds to existing dup values at key if any. Duplicate means another entry at the same key but the entry is still a unique value. Duplicates are inserted in lexocographic order not insertion order. Lmdb does not insert a duplicate unless it is a unique value for that key.

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• vals (list) – dataclass instances each of type self.schema as values

Returns:

True If successful, False otherwise.

Return type:

result (bool)

Apparently always returns True (how .put works with dupsort=True)

rem(keys: str | Iterable, val=None)

Removes entry at keys

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• val (dataclass) – instance of dup val at key to delete if val is None then remove all values at key

Returns:

True if key exists so delete successful. False otherwise

Return type:

result (bool)

class keri.db.koming.IoSetKomer(db: LMDBer, *, subkey: str = 'recs.', schema: Type[dataclass], kind: str = 'JSON', **kwa)

Insertion Ordered Set Keyspace Object Mapper factory class that supports a set of distinct entries at a given effective database key but with dupsort==False. Effective data model is that there are multiple values in a set of values where every member of the set has the same key (duplicate key). The set of values is an ordered set using insertion order. Any given value may appear only once in the set (not a list).

This works similarly to the IO value duplicates for the LMDBer class with a sub db of LMDB (dupsort==True) but without its size limitation of 511 bytes for each value when dupsort==True. Here the key is augmented with a hidden numbered suffix that provides a an ordered set of values at each effective key (duplicate key). The suffix is appended and stripped transparently. The set of multiple items with duplicate keys are retrieved in insertion order when iterating or as a list of the set elements.

db

instance of LMDB database manager class

Type:

dbing.LMDBer

sdb

instance of named sub db lmdb for this Komer

Type:

lmdb._Database

schema

class reference of dataclass subclass

Type:

Type[dataclass]

kind

serialization/deserialization type from coring.Serials

Type:

str

serializer

serializer method

Type:

types.MethodType

deserializer

deserializer method

Type:

types.MethodType

sep

separator for combining keys tuple of strs into key bytes

Type:

str

__init__(db: LMDBer, *, subkey: str = 'recs.', schema: Type[dataclass], kind: str = 'JSON', **kwa)

Parameters:

• db (dbing.LMDBer) – base db

• schema (Type[dataclass]) – reference to Class definition for dataclass sub class

• subkey (str) – LMDB sub database key

• kind (str) – serialization/deserialization type

add(keys: str | Iterable, val: dataclass)

Add val to vals at effective key made from keys and hidden ordinal suffix. that is not already in set of vals at key. Does not overwrite.

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• val (dataclass) – instance of type self.schema

Returns:

True means unique value among duplications,

False means duplicte of same value already exists.

Return type:

result (bool)

cnt(keys: str | Iterable)

Return count of effective dup values at key made from keys, zero otherwise

Parameters:

keys (tuple) – of key strs to be combined in order to form key

get(keys: str | Iterable)

Gets dup vals list at key made from keys

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

each item in list is instance of type self.schema

empty list if no entry at keys

Return type:

vals (list)

getIoItemIter(keys: str | Iterable = b'')

Returns:

tuple (key, val) over the all the items in subdb whose key startswith effective key made from keys. Keys may be keyspace prefix to return branches of key space. When keys is empty then returns all items in subdb.

Return type:

items (Iterator)

Parameters:

keys (Iterable) – tuple of bytes or strs that may be a truncation of a full keys tuple in in order to get all the items from multiple branches of the key space. If keys is empty then gets all items in database. Append “” to end of keys Iterable to ensure get properly separated top branch key.

getIoSetItem(keys: str | Iterable)

Gets (iokeys, val) ioitems list at key made from keys where key is apparent effective key and ioitems all have same apparent effective key

Parameters:

keys (Iterable) – of key strs to be combined in order to form key

Returns:

each item in list is tuple (iokeys, val) where each

iokeys is actual key tuple including hidden suffix and each val is str empty list if no entry at keys

Return type:

ioitems (Iterable)

getIoSetItemIter(keys: str | Iterable)

Gets (iokeys, val) ioitems iterator at key made from keys where key is apparent effective key and items all have same apparent effective key

Parameters:

keys (Iterable) – of key strs to be combined in order to form key

Returns:

each item iterated is tuple (iokeys, val) where

each iokeys is actual keys tuple including hidden suffix and each val is str empty list if no entry at keys. Raises StopIteration when done

Return type:

ioitems (Iterator)

getItemIter(keys: str | Iterable = b'')

Get items iterator :returns: of (key, val) tuples over the all the items in

subdb whose effective key startswith key made from keys. Keys may be keyspace prefix in order to return branches of key space. When keys is empty then returns all items in subdb. Returned key in each item has ordinal suffix removed.

Return type:

items (Iterator)

Parameters:

keys (Iterator) – tuple of bytes or strs that may be a truncation of a full keys tuple in in order to get all the items from multiple branches of the key space. If keys is empty then gets all items in database. Append “” to end of keys Iterable to ensure get properly separated top branch key.

getIter(keys: str | Iterable)

Gets vals iterator at effecive key made from keys and hidden ordinal suffix. All vals in set of vals that share same effecive key are retrieved in insertion order.

Parameters:

keys (Iterable) – of key strs to be combined in order to form key

Returns:

str values. Raises StopIteration when done

Return type:

vals (Iterator)

getLast(keys: str | Iterable)

Gets last effective dup val at effective dup key made from keys

Parameters:

keys (tuple) – of key strs to be combined to form effective key

Returns:

instance of type self.schema

None if no entry at keys

Return type:

val (Type[dataclass])

pin(keys: str | Iterable, vals: list)

Pins (sets) vals at effective key made from keys and hidden ordinal suffix. Overwrites. Removes all pre-existing vals that share same effective keys and replaces them with vals

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• vals (list) – dataclass instances each of type self.schema as values

Returns:

True If successful, False otherwise.

Return type:

result (bool)

put(keys: str | Iterable, vals: list)

Puts all vals at key made from keys. Does not overwrite. Puts all vals at effective key made from keys and hidden ordinal suffix. that are not already in set of vals at key. Does not overwrite.

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• vals (list) – dataclass instances each of type self.schema as values

Returns:

True If successful, False otherwise.

Return type:

result (bool)

Apparently always returns True (how .put works with dupsort=True)

rem(keys: str | Iterable, val=None)

Removes entry at keys

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• val (dataclass) – instance of effective dup val at key to delete if val is None then remove all values at key

Returns:

True if key exists so delete successful. False otherwise

Return type:

result (bool)

remIokey(iokeys: str | bytes | memoryview | Iterable)

Removes entry at iokeys

Parameters:

iokeys (tuple) – of key str or tuple of key strs to be combined in order to form key

Returns:

True if key exists so delete successful. False otherwise

Return type:

result (bool)

class keri.db.koming.Komer(db: LMDBer, *, subkey: str = 'docs.', schema: Type[dataclass], kind: str = 'JSON', **kwa)

Keyspace Object Mapper factory class.

__init__(db: LMDBer, *, subkey: str = 'docs.', schema: Type[dataclass], kind: str = 'JSON', **kwa)

Parameters:

• db (dbing.LMDBer) – base db

• schema (Type[dataclass]) – reference to Class definition for dataclass sub class

• subkey (str) – LMDB sub database key

• kind (str) – serialization/deserialization type

cntAll()

Return iterator over the all the items in subdb

Returns:

of tuples of keys tuple and val dataclass instance for each entry in db. Raises StopIteration when done

Return type:

iterator

Example

if key in database is “a.b” and val is serialization of dataclass

with attributes x and y then returns ((“a”,”b”), dataclass(x=1,y=2))

get(keys: str | Iterable)

Gets val at keys

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

None if no entry at keys

Return type:

val (dataclass)

Usage:

Use walrus operator to catch and raise missing entry if (val := mydb.get(keys)) is None:

raise ExceptionHere

use val here

getDict(keys: str | Iterable)

Gets dictified val at keys

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

None if no entry at keys

Return type:

val (dict)

Usage:

Use walrus operator to catch and raise missing entry if (val := mydb.get(keys)) is None:

raise ExceptionHere

use val here

pin(keys: str | Iterable, val: dataclass)

Pins (sets) val at key made from keys. Overwrites.

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• val (dataclass) – instance of dataclass of type self.schema as value

Returns:

True If successful. False otherwise.

Return type:

result (bool)

put(keys: str | Iterable, val: dataclass)

Puts val at key made from keys. Does not overwrite

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• val (dataclass) – instance of dataclass of type self.schema as value

Returns:

True If successful, False otherwise, such as key

already in database.

Return type:

result (bool)

rem(keys: str | Iterable)

Removes entry at keys

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

True if key exists so delete successful. False otherwise

Return type:

result (bool)

trim(keys: str | Iterable = b'')

Removes all entries whose keys startswith keys. Enables removal of whole branches of db key space. To ensure that proper separation of a branch include empty string as last key in keys. For example (“a”,””) deletes ‘a.1’and ‘a.2’ but not ‘ab’

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

True if key exists so delete successful. False otherwise

Return type:

result (bool)

class keri.db.koming.KomerBase(db: LMDBer, *, subkey: str = 'docs.', schema: Type[dataclass], kind: str = 'JSON', dupsort: bool = False, sep: str | None = None, **kwa)

KomerBase is a base class for Komer (Keyspace Object Mapper) subclasses that each use a dataclass as the object mapped via serialization to an dber LMDB database subclass. Each Komer .schema is a dataclass class reference that is used to define the fields in each database entry. The base class is not meant to be instantiated. Use an instance of one of the subclasses instead.

db

instance of LMDB database manager class

Type:

dbing.LMDBer

sdb

instance of named sub db lmdb for this Komer

Type:

lmdb._Database

schema

class reference of dataclass subclass

Type:

Type[dataclass]

kind

serialization/deserialization type from coring.Serials

Type:

str

serializer

serializer method

Type:

types.MethodType

deserializer

deserializer method

Type:

types.MethodType

sep

separator for combining keys tuple of strs into key bytes

Type:

str

__init__(db: LMDBer, *, subkey: str = 'docs.', schema: Type[dataclass], kind: str = 'JSON', dupsort: bool = False, sep: str | None = None, **kwa)

Parameters:

• db (dbing.LMDBer) – base db

• schema (Type[dataclass]) – reference to Class definition for dataclass sub class

• subkey (str) – LMDB sub database key

• kind (str) – serialization/deserialization type

• dupsort (bool) – True means enable duplicates at each key False (default) means do not enable duplicates at each key

• sep (str) – separator to convert keys iterator to key bytes for db key default is self.Sep == ‘.’

getItemIter(keys: str | Iterable = b'')

Returns:

of (key, val) tuples over the all the items in subdb whose key startswith key made from keys. Keys may be keyspace prefix to return branches of key space. When keys is empty then returns all items in subdb

Return type:

items (Iterator)

Parameters:

keys (Iterator) – tuple of bytes or strs that may be a truncation of a full keys tuple in in order to get all the items from multiple branches of the key space. If keys is empty then gets all items in database.

keri.db.subing

KERI keri.db.subing module

Provide variety of mixin classes for LMDB sub-dbs with various behaviors.

Principally:

Suber class provides put, pin, get, rem and getItemIter method for managing a serialized value in a sub db with an iterable set of keys defining the key space

CesrSuber class extends Suber for values that are serializations of CESR serializable object instances. Ducktyped subclasses of Matter, Indexer, and Counter or the like.

IoSetSuber class extends Suber to allow a set of values to be stored in insertion order at each effective key. Only one copy of a unique value is allowed in the set at a given effective key. The effective key suffixes an ordinal to the key space to track insertion ordering. IoSetSuber adds additional methods to manage IoSets of values.

CatCesrSuber adds the ability to store multiple concatenated serializations at a value

CatCesrIoSetSuber combines the capabilities

Other special classer for special values

SerderSuber stores Serialized Serder Instances of in JSON, CBOR, or MGPK

Also for Secrets private keys SignerSuber CryptSignerSuber

Also for using the dupsort==true mechanism is DupSuber CesrDupSuber

class keri.db.subing.CatCesrIoSetSuber(*pa, **kwa)

Sub class of CatSuberBase and IoSetSuber where values stored in db are a concatenation of .qb64b property from one or more Cesr compatible subclass instances that automatically serializes and deserializes to/from qb64b . (qb64b is bytes of fully qualified serialization).

Extends IoSetSuber with mixin methods ._ser and ._des from CatSuberBase so that all IoSetSuber methods now work with an Iterable of CESR subclass for each val.

IoSetSuber stores at each effective key a set of distinct values that share that same effective key where each member of the set is retrieved in insertion order (dupsort==False) The methods allows an Iterable (set valued) of Iterables of Matter subclass instances to be stored at a given effective key in insertion order.

Actual keys include a hidden ordinal key suffix that tracks insertion order. The suffix is appended and stripped transparently from the keys. The set of items with duplicate effective keys are retrieved in insertion order when iterating or as a list of the set elements. The actual iokey for any item includes the ordinal suffix.

db

base LMDB db

Type:

dbing.LMDBer

sdb

instance of lmdb named sub db for this Suber

Type:

lmdb._Database

sep

separator for combining keys tuple of strs into key bytes

Type:

str

klas

of Class references to subclasses of Matter, each of to Type[coring.Matter]

Type:

Iterable

__init__(*pa, **kwa)

Parameters:

• db (dbing.LMDBer) – base db

• subkey (str) – LMDB sub database key

• dupsort (bool) – True means enable duplicates at each key False (default) means do not enable duplicates at each key

• sep (str) – separator to convert keys iterator to key bytes for db key default is self.Sep == ‘.’

• klas (Iterable) – of Class references to subclasses of Matter, each of to Type[coring.Matter]

class keri.db.subing.CatCesrSuber(*pa, **kwa)

Class whose values stored in db are a concatenation of the .qb64b property from one or more subclass instances (qb64b is bytes of fully qualified serialization) that support CESR encode/decode ducktyped subclass instance such as Matter, Indexer, Counter Automatically serializes and deserializes from qb64b to/from CESR instances

Attributes:

db (dbing.LMDBer): base LMDB db sdb (lmdb._Database): instance of lmdb named sub db for this Suber sep (str): separator for combining keys tuple of strs into key bytes klas (Iterable): of Class references to subclasses of CESR compatible

, each of to Type[coring.Matter etc]

__init__(*pa, **kwa)

Parameters:

• db (dbing.LMDBer) – base db

• subkey (str) – LMDB sub database key

• dupsort (bool) – True means enable duplicates at each key False (default) means do not enable duplicates at each key

• sep (str) – separator to convert keys iterator to key bytes for db key default is self.Sep == ‘.’

• klas (Iterable) – of Class references to subclasses of Matter, each of to Type[coring.Matter]

class keri.db.subing.CatCesrSuberBase(*pa, klas: Iterable | None = None, **kwa)

Base Class whose values stored in db are a concatenation of the .qb64b property from one or more subclass instances (qb64b is bytes of fully qualified serialization) that support CESR encode/decode ducktyped subclass instance such as Matter, Indexer, Counter Automatically serializes and deserializes from qb64b to/from CESR instances

Attributes:

db (dbing.LMDBer): base LMDB db sdb (lmdb._Database): instance of lmdb named sub db for this Suber sep (str): separator for combining keys tuple of strs into key bytes klas (Iterable): of Class references to subclasses of CESR compatible

, each of to Type[coring.Matter etc]

__init__(*pa, klas: Iterable | None = None, **kwa)

Parameters:

• db (dbing.LMDBer) – base db

• subkey (str) – LMDB sub database key

• dupsort (bool) – True means enable duplicates at each key False (default) means do not enable duplicates at each key

• sep (str) – separator to convert keys iterator to key bytes for db key default is self.Sep == ‘.’

• klas (Iterable) – of Class references to subclasses of Matter, each of to Type[coring.Matter]

class keri.db.subing.CesrDupSuber(*pa, klas: ~typing.Type[~keri.core.coring.Matter] = <class 'keri.core.coring.Matter'>, **kwa)

Sub class of DupSuber that supports multiple entries at each key (duplicates) with dupsort==True, where data where data is Matter.qb64b property which is a fully qualified serialization of matter subclass instance Automatically serializes and deserializes from qb64b to/from Matter instances

Do not use if serialized value is greater than 511 bytes. This is a limitation of dupsort==True sub dbs in LMDB

__init__(*pa, klas: ~typing.Type[~keri.core.coring.Matter] = <class 'keri.core.coring.Matter'>, **kwa)

Parameters:

• db (dbing.LMDBer) – base db

• subkey (str) – LMDB sub database key

• klas (Type[coring.Matter]) – Class reference to subclass of Matter

add(keys: str | Iterable, val: Matter)

Add val to vals at key made from keys. Does not overwrite. Adds to existing dup values at key if any. Duplicate means another entry at the same key but the entry is still a unique value. Duplicates are inserted in lexocographic order not insertion order. Lmdb does not insert a duplicate unless it is a unique value for that key.

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• val (coring.Matter) – instance (subclass)

Returns:

True means unique value among duplications,

False means duplicte of same value already exists.

Return type:

result (bool)

get(keys: str | Iterable)

Gets dup vals list at key made from keys

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

each item in list is instance of self.klas

empty list if no entry at keys

Return type:

vals (list)

getItemIter(keys: str | Iterable = b'')

Returns:

tuple (key, val) over the all the items in subdb whose key startswith key made from keys. Keys may be keyspace prefix to return branches of key space. When keys is empty then returns all items in subdb

Return type:

iterator (Iteratore

Parameters:

keys (Iterator) – tuple of bytes or strs that may be a truncation of a full keys tuple in in order to get all the items from multiple branches of the key space. If keys is empty then gets all items in database.

getIter(keys: str | Iterable)

Gets dup vals iterator at key made from keys

Duplicates are retrieved in lexocographic order not insertion order.

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

vals each of self.klas. Raises StopIteration when done

Return type:

iterator

getLast(keys: str | Iterable)

Gets last dup val at key made from keys

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

instance of self.klas else None if no value at key

Return type:

val (str)

pin(keys: str | Iterable, vals: list)

Pins (sets) vals at key made from keys. Overwrites. Removes all pre-existing dup vals and replaces them with vals

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• vals (list) – instances of coring.Matter (subclass)

Returns:

True If successful, False otherwise.

Return type:

result (bool)

put(keys: str | Iterable, vals: list)

Puts all vals at key made from keys. Does not overwrite. Adds to existing dup values at key if any. Duplicate means another entry at the same key but the entry is still a unique value. Duplicates are inserted in lexocographic order not insertion order. Lmdb does not insert a duplicate unless it is a unique value for that key.

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• vals (list) – instances of coring.Matter (subclass)

Returns:

True If successful, False otherwise.

Return type:

result (bool)

Apparently always returns True (how .put works with dupsort=True)

rem(keys: str | Iterable, val=None)

Removes entry at keys

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• val (coring.Matter) – instance of coring.Matter subclass dup val at key to delete if val is None then remove all values at key

Returns:

True if key exists so delete successful. False otherwise

Return type:

result (bool)

class keri.db.subing.CesrIoSetSuber(*pa, **kwa)

Subclass of CesrSuber and IoSetSuber. Class whose values stored in db are a concatenation of the .qb64b property from one or more subclass instances (qb64b is bytes of fully qualified serialization) that support CESR encode/decode ducktyped subclass instance such as Matter, Indexer, Counter Automatically serializes and deserializes from qb64b to/from CESR instances

Extends IoSetSuber with mixin methods ._ser and ._des from CesrSuberBase so that all IoSetSuber methods now work with CESR subclass for each val.

IoSetSuber stores at each effective key a set of distinct values that share that same effective key where each member of the set is retrieved in insertion order (dupsort==False) The methods allows an Iterable (set valued) of Iterables of Matter subclass instances to be stored at a given effective key in insertion order.

Actual keys include a hidden ordinal key suffix that tracks insertion order. The suffix is appended and stripped transparently from the keys. The set of items with duplicate effective keys are retrieved in insertion order when iterating or as a list of the set elements. The actual iokey for any item includes the ordinal suffix.

Attributes:

db (dbing.LMDBer): base LMDB db sdb (lmdb._Database): instance of lmdb named sub db for this Suber sep (str): separator for combining keys tuple of strs into key bytes klas (Iterable): of Class references to subclasses of CESR compatible

, each of to Type[coring.Matter etc]

__init__(*pa, **kwa)

Parameters:

• db (dbing.LMDBer) – base db

• subkey (str) – LMDB sub database key

• dupsort (bool) – True means enable duplicates at each key False (default) means do not enable duplicates at each key

• sep (str) – separator to convert keys iterator to key bytes for db key default is self.Sep == ‘.’

• klas (Iterable) – of Class references to subclasses of Matter, each of to Type[coring.Matter]

class keri.db.subing.CesrSuber(*pa, **kwa)

Sub class of Suber where data is CESR encode/decode ducktyped subclass instance such as Matter, Indexer, Counter with .qb64b property when provided as fully qualified serialization. Extents Suber to support val that are ducktyped CESR serializable .qb64 .qb64b subclasses such as coring.Matter, coring.Indexer, coring.Counter. Automatically serializes and deserializes from qb64b to/from CESR instances

__init__(*pa, **kwa)

Parameters:

• db (dbing.LMDBer) – base db

• subkey (str) – LMDB sub database key

• klas (Type[coring.Matter]) – Class reference to subclass of Matter or Indexer or Counter or any ducktyped class of Matter

class keri.db.subing.CesrSuberBase(*pa, klas: ~typing.Type[~keri.core.coring.Matter] = <class 'keri.core.coring.Matter'>, **kwa)

Sub class of Suber where data is CESR encode/decode ducktyped subclass instance such as Matter, Indexer, Counter with .qb64b property when provided as fully qualified serialization Automatically serializes and deserializes from qb64b to/from CESR instances

__init__(*pa, klas: ~typing.Type[~keri.core.coring.Matter] = <class 'keri.core.coring.Matter'>, **kwa)

Parameters:

• db (dbing.LMDBer) – base db

• subkey (str) – LMDB sub database key

• klas (Type[coring.Matter]) – Class reference to subclass of Matter or Indexer or Counter or any ducktyped class of Matter

class keri.db.subing.CryptSignerSuber(*pa, klas: ~typing.Type[~keri.core.coring.Signer] = <class 'keri.core.coring.Signer'>, **kwa)

Sub class of SignerSuber where data is Signer subclass instance .qb64b property that has been encrypted if encrypter provided. which is a fully qualified serialization and uses the key which is the qb64b of the signer.verfer to get the transferable property of the verfer Automatically serializes and deserializes from qb64b to/from Signer instances

Assumes that last or only element of db key from keys for all entries is the qb64 of a public key for the associated Verfer instance. This allows returned Signer instance to have its .transferable property set correctly.

get(keys: str | Iterable, decrypter: Decrypter | None = None)

Gets Signer instance at keys. If decrypter then assumes value in db was encrypted and so decrypts value in db before converting to Signer.

Returns:

transferable determined by key which is verfer None if no entry at keys

Return type:

val (Signer)

Parameters:

• keys (Union[str, iterable]) – key strs to be combined in order to form key. Last element of keys is verkey used to determin .transferable for Signer

• decrypter (coring.Decrypter) – optional. If provided assumes value in db was encrypted and so decrypts before converting to Signer.

Usage:

Use walrus operator to catch and raise missing entry if (signer := mydb.get(keys)) is None:

raise ExceptionHere

use signer here

getItemIter(keys: str | Iterable = b'', decrypter: Decrypter | None = None)

Returns:

of tuples (key, val) over the all the items in subdb whose key startswith key made from keys. Keys may be keyspace prefix to return branches of key space. When keys is empty then returns all items in subdb

Return type:

iterator (Iterator)

decrypter (coring.Decrypter): optional. If provided assumes value in

db was encrypted and so decrypts before converting to Signer.

Parameters:

keys (Iterator) – tuple of bytes or strs that may be a truncation of a full keys tuple in in order to get all the items from multiple branches of the key space. If keys is empty then gets all items in database.

pin(keys: str | Iterable, val: Matter, encrypter: Encrypter | None = None)

Pins (sets) qb64 of Matter instance val at key made from keys. Overwrites. If encrypter provided then encrypts first

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• val (Signer) – instance of self.klas

• encrypter (coring.Encrypter) – optional

Returns:

True If successful. False otherwise.

Return type:

result (bool)

put(keys: str | Iterable, val: Matter, encrypter: Encrypter | None = None)

Puts qb64 of Matter instance val at key made from keys. Does not overwrite If encrypter provided then encrypts first

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• val (Signer) – instance of self.klas

• encrypter (coring.Encrypter) – optional

Returns:

True If successful, False otherwise, such as key

already in database.

Return type:

result (bool)

class keri.db.subing.DupSuber(db: Type[LMDBer], *, subkey: str = 'docs.', dupsort: bool = True, **kwa)

Sub DB of LMDBer. Subclass of SuberBase that supports multiple entries at each key (duplicates) with dupsort==True

Do not use if serialized value is greater than 511 bytes. This is a limitation of dupsort==True sub dbs in LMDB

__init__(db: Type[LMDBer], *, subkey: str = 'docs.', dupsort: bool = True, **kwa)

Parameters:

• db (dbing.LMDBer) – base db

• subkey (str) – LMDB sub database key

add(keys: str | Iterable, val: bytes | str)

Add val to vals at key made from keys. Does not overwrite. Adds to existing dup values at key if any. Duplicate means another entry at the same key but the entry is still a unique value. Duplicates are inserted in lexocographic order not insertion order. Lmdb does not insert a duplicate unless it is a unique value for that key.

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• val (Union[str, bytes]) – value

Returns:

True means unique value among duplications,

False means duplicte of same value already exists.

Return type:

result (bool)

cnt(keys: str | Iterable)

Return count of dup values at key made from keys, zero otherwise

Parameters:

keys (tuple) – of key strs to be combined in order to form key

get(keys: str | Iterable)

Gets dup vals list at key made from keys

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

each item in list is str

empty list if no entry at keys

Return type:

vals (list)

getIter(keys: str | Iterable)

Gets dup vals iterator at key made from keys

Duplicates are retrieved in lexocographic order not insertion order.

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

vals each of str. Raises StopIteration when done

Return type:

iterator

getLast(keys: str | Iterable)

Gets last dup val at key made from keys

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

value else None if no value at key

Return type:

val (str)

pin(keys: str | Iterable, vals: list)

Pins (sets) vals at key made from keys. Overwrites. Removes all pre-existing dup vals and replaces them with vals

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• vals (list) – str or bytes values

Returns:

True If successful, False otherwise.

Return type:

result (bool)

put(keys: str | Iterable, vals: list)

Puts all vals at key made from keys. Does not overwrite. Adds to existing dup values at key if any. Duplicate means another entry at the same key but the entry is still a unique value. Duplicates are inserted in lexocographic order not insertion order. Lmdb does not insert a duplicate unless it is a unique value for that key.

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• vals (list) – str or bytes of each value to be written at key

Returns:

True If successful, False otherwise.

Return type:

result (bool)

Apparently always returns True (how .put works with dupsort=True)

rem(keys: str | Iterable, val=b'')

Removes entry at keys

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• val (Union[str, bytes]) – instance of dup val at key to delete if val is None then remove all values at key

Returns:

True if key exists so delete successful. False otherwise

Return type:

result (bool)

class keri.db.subing.IoSetSuber(db: LMDBer, *, subkey: str = 'docs.', dupsort: bool = False, **kwa)

Insertion Ordered Set Suber factory class that supports a set of distinct entries at a given effective database key but with dupsort==False. Effective data model is that there are multiple values in a set of values where every member of the set has the same key (duplicate key). The set of values is an ordered set using insertion order. Any given value may appear only once in the set (not a list).

This works similarly to the IO value duplicates for the LMDBer class with a sub db of LMDB (dupsort==True) but without its size limitation of 511 bytes for each value when dupsort==True. Here the key is augmented with a hidden numbered suffix that provides a an ordered set of values at each effective key (duplicate key). The suffix is appended and stripped transparently. The set of multiple items with duplicate keys are retrieved in insertion order when iterating or as a list of the set elements.

db

base LMDB db

Type:

dbing.LMDBer

sdb

instance of lmdb named sub db for this Suber

Type:

lmdb._Database

sep

separator for combining keys tuple of strs into key bytes

Type:

str

__init__(db: LMDBer, *, subkey: str = 'docs.', dupsort: bool = False, **kwa)

Parameters:

• db (dbing.LMDBer) – base db

• subkey (str) – LMDB sub database key

• dupsort (bool) – True means enable duplicates at each key False (default) means do not enable duplicates at each key

• sep (str) – separator to convert keys iterator to key bytes for db key default is self.Sep == ‘.’

add(keys: str | Iterable, val: bytes | str | memoryview)

Add val to vals at effective key made from keys and hidden ordinal suffix. that is not already in set of vals at key. Does not overwrite.

Parameters:

• keys (Iterable) – of key strs to be combined in order to form key

• val (Union[bytes, str]) – serialization

Returns:

True means unique value among duplications,

False means duplicte of same value already exists.

Return type:

result (bool)

cnt(keys: str | Iterable)

Return count of values at effective key made from keys and hidden ordinal suffix. Zero otherwise

Parameters:

keys (Iterable) – of key strs to be combined in order to form key

get(keys: str | Iterable)

Gets vals set list at key made from effective keys

Parameters:

keys (Iterable) – of key strs to be combined in order to form key

Returns:

each item in list is str

empty list if no entry at keys

Return type:

vals (Iterable)

getIoItemIter(keys: str | Iterable = b'')

Returns:

tuple (key, val) over the all the items in subdb whose key startswith effective key made from keys. Keys may be keyspace prefix to return branches of key space. When keys is empty then returns all items in subdb.

Return type:

items (Iterator)

Parameters:

keys (Iterable) – tuple of bytes or strs that may be a truncation of a full keys tuple in in order to get all the items from multiple branches of the key space. If keys is empty then gets all items in database. Append “” to end of keys Iterable to ensure get properly separated top branch key.

getIoSetItem(keys: str | Iterable)

Gets (iokeys, val) ioitems list at key made from keys where key is apparent effective key and ioitems all have same apparent effective key

Parameters:

keys (Iterable) – of key strs to be combined in order to form key

Returns:

each item in list is tuple (iokeys, val) where each

iokeys is actual key tuple including hidden suffix and each val is str empty list if no entry at keys

Return type:

ioitems (Iterable)

getIoSetItemIter(keys: str | Iterable)

Gets (iokeys, val) ioitems iterator at key made from keys where key is apparent effective key and items all have same apparent effective key

Parameters:

keys (Iterable) – of key strs to be combined in order to form key

Returns:

each item iterated is tuple (iokeys, val) where

each iokeys is actual keys tuple including hidden suffix and each val is str empty list if no entry at keys. Raises StopIteration when done

Return type:

ioitems (Iterator)

getItemIter(keys: str | Iterable = b'')

Return iterator over all the items in top branch defined by keys where keys may be truncation of full branch.

Returns:

of (key, val) tuples over the all the items in subdb whose effective key startswith key made from keys. Keys may be keyspace prefix in order to return branches of key space. When keys is empty then returns all items in subdb. Returned key in each item has ordinal suffix removed.

Return type:

items (Iterator)

Parameters:

keys (Iterator) – tuple of bytes or strs that may be a truncation of a full keys tuple in in order to get all the items from multiple branches of the key space. If keys is empty then gets all items in database. Append “” to end of keys Iterable to ensure get properly separated top branch key.

getIter(keys: str | Iterable)

Gets vals iterator at effecive key made from keys and hidden ordinal suffix. All vals in set of vals that share same effecive key are retrieved in insertion order.

Parameters:

keys (Iterable) – of key strs to be combined in order to form key

Returns:

str values. Raises StopIteration when done

Return type:

vals (Iterator)

getLast(keys: str | Iterable)

Gets last val inserted at effecive key made from keys and hidden ordinal suffix.

Parameters:

keys (Iterable) – of key strs to be combined in order to form key

Returns:

value str, None if no entry at keys

Return type:

val (str)

pin(keys: str | Iterable, vals: Iterable)

Pins (sets) vals at effective key made from keys and hidden ordinal suffix. Overwrites. Removes all pre-existing vals that share same effective keys and replaces them with vals

Parameters:

• keys (Iterable) – of key strs to be combined in order to form key

• vals (Iterable) – str serializations

Returns:

True If successful, False otherwise.

Return type:

result (bool)

put(keys: str | Iterable, vals: Iterable)

Puts all vals at effective key made from keys and hidden ordinal suffix. that are not already in set of vals at key. Does not overwrite.

Parameters:

• keys (Iterable) – of key strs to be combined in order to form key

• vals (Iterable) – of str serializations

Returns:

True If successful, False otherwise.

Return type:

result (bool)

rem(keys: str | Iterable, val: str | bytes | memoryview = b'')

Removes entry at effective key made from keys and hidden ordinal suffix that matches val if any. Otherwise deletes all values at effective key.

Parameters:

• keys (Iterable) – of key strs to be combined in order to form key

• val (str) – value at key to delete if val is empty then remove all values at key

Returns:

True if effective key with val exists so delete successful.

False otherwise

Return type:

result (bool)

remIokey(iokeys: str | bytes | memoryview | Iterable)

Removes entry at keys

Parameters:

iokeys (Iterable) – of key str or tuple of key strs to be combined in order to form key

Returns:

True if key exists so delete successful. False otherwise

Return type:

result (bool)

class keri.db.subing.SchemerSuber(*pa, **kwa)

Sub class of Suber where data is serialized Schemer instance Automatically serializes and deserializes using Schemer methods

__init__(*pa, **kwa)

Parameters:

• db (dbing.LMDBer) – base db

• subkey (str) – LMDB sub database key

get(keys: str | Iterable)

Gets Serder at keys

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

None: if no entry at keys

Return type:

Schemer

Usage:

Use walrus operator to catch and raise missing entry if (srder := mydb.get(keys)) is None:

raise ExceptionHere

use srdr here

getItemIter(keys: str | Iterable = b'')

Returns:

tuple (key, val) over the all the items in subdb whose key startswith key made from keys. Keys may be keyspace prefix to return branches of key space. When keys is empty then returns all items in subdb

Return type:

iterator (Iterator)

Parameters:

keys (Iterator) – tuple of bytes or strs that may be a truncation of a full keys tuple in in order to get all the items from multiple branches of the key space. If keys is empty then gets all items in database.

pin(keys: str | Iterable, val: Schemer)

Pins (sets) val at key made from keys. Overwrites.

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• val (Schemer) – instance

Returns:

True If successful. False otherwise.

Return type:

result (bool)

put(keys: str | Iterable, val: Schemer)

Puts val at key made from keys. Does not overwrite

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• val (Schemer) – instance

Returns:

True If successful, False otherwise, such as key

already in database.

Return type:

result (bool)

rem(keys: str | Iterable)

Removes entry at keys

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

True if key exists so delete successful. False otherwise

Return type:

result (bool)

class keri.db.subing.SerderSuber(*pa, klas: ~typing.Type[~keri.core.serdering.Serder] = <class 'keri.core.serdering.SerderKERI'>, **kwa)

Sub class of Suber where data is serialized Serder Subclass instance given by .klas Automatically serializes and deserializes using .klas Serder methods

__init__(*pa, klas: ~typing.Type[~keri.core.serdering.Serder] = <class 'keri.core.serdering.SerderKERI'>, **kwa)

Inherited Parameters:

db (dbing.LMDBer): base db subkey (str): LMDB sub database key

Parameters:

klas (Type[serdering.Serder]) – Class reference to subclass of Serder

get(keys: str | Iterable)

Gets Serder at keys

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

None: if no entry at keys

Return type:

Serder

Usage:

Use walrus operator to catch and raise missing entry if (srder := mydb.get(keys)) is None:

raise ExceptionHere

use srdr here

getItemIter(keys: str | Iterable = b'')

Returns:

tuple (key, val) over the all the items in subdb whose key startswith key made from keys. Keys may be keyspace prefix to return branches of key space. When keys is empty then returns all items in subdb

Return type:

iterator (Iterator)

Parameters:

keys (Iterator) – tuple of bytes or strs that may be a truncation of a full keys tuple in in order to get all the items from multiple branches of the key space. If keys is empty then gets all items in database.

pin(keys: str | Iterable, val: SerderKERI)

Pins (sets) val at key made from keys. Overwrites.

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• val (Serder) – instance

Returns:

True If successful. False otherwise.

Return type:

result (bool)

put(keys: str | Iterable, val: SerderKERI)

Puts val at key made from keys. Does not overwrite

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• val (Serder) – instance

Returns:

True If successful, False otherwise, such as key

already in database.

Return type:

result (bool)

rem(keys: str | Iterable)

Removes entry at keys

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

True if key exists so delete successful. False otherwise

Return type:

result (bool)

class keri.db.subing.SignerSuber(*pa, klas: ~typing.Type[~keri.core.coring.Signer] = <class 'keri.core.coring.Signer'>, **kwa)

Sub class of CesrSuber where data is Signer subclass instance .qb64b propery which is a fully qualified serialization and uses the key which is the qb64b of the signer.verfer to get the transferable property of the verfer Automatically serializes and deserializes from qb64b to/from Signer instances

Assumes that last or only element of db key from keys for all entries is the qb64 of a public key for the associated Verfer instance. This allows returned Signer instance to have its .transferable property set correctly.

__init__(*pa, klas: ~typing.Type[~keri.core.coring.Signer] = <class 'keri.core.coring.Signer'>, **kwa)

Parameters:

• db (dbing.LMDBer) – base db

• subkey (str) – LMDB sub database key

• klas (Type[coring.Matter]) – Class reference to subclass of Matter

get(keys: str | Iterable)

Gets Signer instance at keys

Returns:

transferable determined by key which is verfer None if no entry at keys

Return type:

val (Signer)

Parameters:

keys (Union[str, iterable]) – key strs to be combined in order to form key. Last element of keys is verkey used to determin .transferable for Signer

Usage:

Use walrus operator to catch and raise missing entry if (signer := mydb.get(keys)) is None:

raise ExceptionHere

use signer here

getItemIter(keys: str | Iterable = b'')

Returns:

tuple (key, val) over the all the items in subdb whose key startswith key made from keys. Keys may be keyspace prefix to return branches of key space. When keys is empty then returns all items in subdb

Return type:

iterator (Iteratore

Parameters:

keys (Iterator) – tuple of bytes or strs that may be a truncation of a full keys tuple in in order to get all the items from multiple branches of the key space. If keys is empty then gets all items in database.

class keri.db.subing.Suber(db: LMDBer, *, subkey: str = 'docs.', dupsort: bool = False, **kwa)

Sub DB of LMDBer. Subclass of SuberBase

__init__(db: LMDBer, *, subkey: str = 'docs.', dupsort: bool = False, **kwa)

Parameters:

• db (dbing.LMDBer) – base db

• subkey (str) – LMDB sub database key

get(keys: str | Iterable)

Gets val at keys

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

decoded as utf-8 None if no entry at keys

Return type:

data (str)

Usage:

Use walrus operator to catch and raise missing entry if (data := mydb.get(keys)) is None:

raise ExceptionHere

use data here

pin(keys: str | Iterable, val: bytes | str)

Pins (sets) val at key made from keys. Overwrites.

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• val (bytes) – value

Returns:

True If successful. False otherwise.

Return type:

result (bool)

put(keys: str | Iterable, val: bytes | str | any)

Puts val at key made from keys. Does not overwrite

Parameters:

• keys (tuple) – of key strs to be combined in order to form key

• val (bytes) – value

Returns:

True If successful, False otherwise, such as key

already in database.

Return type:

result (bool)

rem(keys: str | Iterable)

Removes entry at keys

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

True if key exists so delete successful. False otherwise

Return type:

result (bool)

class keri.db.subing.SuberBase(db: LMDBer, *, subkey: str = 'docs.', dupsort: bool = False, sep: str | None = None, **kwa)

Base class for Sub DBs of LMDBer Provides common methods for subclasses Do not instantiate but use a subclass

db

base LMDB db

Type:

dbing.LMDBer

sdb

instance of lmdb named sub db for this Suber

Type:

lmdb._Database

sep

separator for combining keys tuple of strs into key bytes

Type:

str

__init__(db: LMDBer, *, subkey: str = 'docs.', dupsort: bool = False, sep: str | None = None, **kwa)

Parameters:

• db (dbing.LMDBer) – base db

• subkey (str) – LMDB sub database key

• dupsort (bool) – True means enable duplicates at each key False (default) means do not enable duplicates at each key

• sep (str) – separator to convert keys iterator to key bytes for db key default is self.Sep == ‘.’

getItemIter(keys: str | Iterable = b'')

Returns:

if (key, val) tuples over the all the items in subdb whose key startswith key made from keys. Keys may be keyspace prefix to return branches of key space. When keys is empty then returns all items in subdb

Return type:

items (Iterator)

Parameters:

keys (Iterator) – tuple of bytes or strs that may be a truncation of a full keys tuple in in order to get all the items from multiple branches of the key space. If keys is empty then gets all items in database.

trim(keys: str | Iterable = b'')

Removes all entries whose keys startswith keys. Enables removal of whole branches of db key space. To ensure that proper separation of a branch include empty string as last key in keys. For example (“a”,””) deletes ‘a.1’and ‘a.2’ but not ‘ab’

Parameters:

keys (tuple) – of key strs to be combined in order to form key

Returns:

True if key exists so delete successful. False otherwise

Return type:

result (bool)