KERI Peer API

keri.peer.exchanging

keri.peer.exchanging module

class keri.peer.exchanging.Exchanger(hby, handlers, cues=None, delta=datetime.timedelta(seconds=300))

Peer to Peer KERI message Exchanger.

__init__(hby, handlers, cues=None, delta=datetime.timedelta(seconds=300))

Initialize instance

Parameters:

• hby (Haberyu) – database environment

• handlers (list) – list of Handlers capable of responding to exn messages

• cues (Deck) – of Cues i.e. notices of requests needing response

• delta (timedelta) – message timeout window

complete(said)

Parameters:

said (str) – qb64 said of exchange message to check status

Returns:

True means exchange message is has been saved

Return type:

bool

escrowPSEvent(serder, tsgs, pathed, cigars=None, sourceSeals=None, nests=None)

Escrow event that does not have enough signatures.

Parameters:

• serder (Serder) – instance of event

• tsgs (list) – quadlet of prefixer seqner, saider, sigers

• pathed (list) – list of bytes of attached paths

• cigars (list | None) – nontransferable signatures to preserve

• sourceSeals (list | None) – source seal triples to preserve

• nests (list | None) – parsed V2 nested substreams to preserve

lead(hab, said)

Determines is current member represented by hab is the lead of an exn message

Lead is the signer of the exn with the lowest signing index

Parameters:

• hab (Hab) – Habitat for sending of exchange message represented by SAID

• said (str) – qb64 SAID of exchange message

Returns:

True means hab is the lead

Return type:

bool

processEscrow()

Process all escrows for exn messages

processEscrowPartialSigned()

Process escrow of partially signed messages

processEvent(serder, tsgs=None, cigars=None, ptds=None, essrs=None, **kwa)

Process one serder event with attached indexed signatures representing a Peer to Peer exchange message.

Parameters:

• serder (Serder) – instance of event to process

• tsgs (list) – tuples (quadruples) of form (prefixer, seqner, diger, [sigers]) where: prefixer is pre of trans endorser seqner is sequence number of trans endorser’s est evt for keys for sigs diger is digest of trans endorser’s est evt for keys for sigs [sigers] is list of indexed sigs from trans endorser’s keys from est evt

• cigars (list) – of Cigar instances of attached non-trans sigs

• ptds (list[bytes]) – pathed Cesr Streams

• essrs (list[Texter]) – ESSR streams as Texters

• kwa (dict) – optional parsed attachment groups: nests contains parsed V2 nested substreams lsgs contains last-establishment signature groups ulgs contains unresolved foreign signer prefixes sscs contains sender-implied source seal couples ssts contains explicit source seal triples

Returns:

True when the exchange verified and was persisted,

False when behavior verification failed permanently, or None when the message was escrowed for retry because it is waiting on external evidence such as TEL proof material.

Return type:

bool | None

keri.peer.exchanging.cloneMessage(hby, said)

Load and verify signatures on message exn

Parameters:

• hby (Habery) – database environment from which to clone message

• said (str) – qb64 SAID of message exn to load

Returns:

(serder, list) of message exn and pathed signatures on embedded attachments

Return type:

tuple

keri.peer.exchanging.exchangeOld(*, sender='', receiver='', xid='', prior='', route='', modifiers=None, attributes=None, diger=None, embeds=None, stamp=None, version=(2, 0), pvrsn=None, gvrsn=None, kind='JSON')

Create an exn message with the specified route and payload

Parameters:

• sender (str) – qb64 of sender identifier (AID)

• receiver (str) – qb64 of receiver identifier (AID)

• xid (str) – qb64 of exchange ID which is SAID of exchange inception ‘xip’ if any

• prior (str) – qb64 of prior exchange event including ‘xip” if any

• route (str) – ‘/’ delimited path identifier of data flow handler (behavior) to processs the reply if any (equivalent of url path to resource)

• modifiers (dict) – modifiers field map (equvalent of http query string)

• attributes (dict) – attributes field map (payload body)

• stamp (str) – date-time-stamp RFC-3339 profile of ISO-8601 datetime of creation of message or data, default is now.

• version (Versionage) – KERI protocol default version if psvrsn is None

• pvrsn (Versionage) – KERI protocol version

• gvrsn (Versionage) –

  CESR Genus version for attachment group codes or nesting group code (useful when serder.gvrsn < 2) gvrsn = max(svrsn, gvrsn) where svrsn = serder.gvrsn

  if serder.gvrsn else serder.pvrsn

• kind (str) – serialization for key event message one of Kinds (“json”,”cbor”,”mgpk”,”cesr”)

• diger (Diger) – qb64 digest of attributes section (payload)

• embeds (dict) – named embeded KERI event CESR stream with attachments

keri.peer.exchanging.loadParsedNestedSubstreams(hby, said)

Load and parse stored nested child substreams for an exchange message.

keri.peer.exchanging.nesting(paths, acc, val)

Nesting Pather parts

Parameters:

paths (list[list]) – list of path parts

keri.peer.exchanging.serializeMessage(hby, said, framed=False)

Fetch message and attachments from hby.db by said and then serialize them

Parameters:

• hby (Habery) – environment with db

• said (str) – of message

• framed (bool) – True means may assume each message plus its attachments is isolated as frame when parsing so do not need attachment group when messagizing

• attachments (False means may not assume eash message plus its) – is isolated as frame when parsing so do need attachment group when messagizing

Returns:

message by said with attachments

Return type:

msg (bytearray)

keri.peer.exchanging.serializeParsedSubstream(parsed, gvrsn=(2, 0))

Serialize a parsed message subtree as a nested CESR substream.

keri.peer.exchanging.specialExchange(*, sender='', receiver='', xid='', prior='', route='', modifiers=None, attributes=None, diger=None, embeds=None, stamp=None, version=(1, 0), pvrsn=None, gvrsn=None, kind='JSON')

Create an exn with either an ESSR attachment or embeds with path attachment as determined by the presence of diger or embeds parameters repectively

Parameters:

• sender (str) – qb64 of sender identifier (AID)

• receiver (str) – qb64 of receiver identifier (AID)

• xid (str) – qb64 of exchange ID which is SAID of exchange inception ‘xip’ if any

• prior (str) – qb64 of prior exchange event including ‘xip” if any

• route (str) – ‘/’ delimited path identifier of data flow handler (behavior) to processs the reply if any (equivalent of url path to resource)

• modifiers (dict) – modifiers field map (equvalent of http query string)

• attributes (dict) – attributes field map (payload body)

• stamp (str) – date-time-stamp RFC-3339 profile of ISO-8601 datetime of creation of message or data, default is now.

• version (Versionage) – KERI protocol default version if psvrsn is None

• pvrsn (Versionage) – KERI protocol version

• gvrsn (Versionage) –

  CESR Genus version for attachment group codes or nesting group code (useful when serder.gvrsn < 2) gvrsn = max(svrsn, gvrsn) where svrsn = serder.gvrsn

  if serder.gvrsn else serder.pvrsn

• kind (str) – serialization for key event message one of Kinds (“json”,”cbor”,”mgpk”,”cesr”)

• diger (Diger) – qb64 digest of attributes section (payload)

• embeds (dict) – named embeded KERI event CESR stream with attachments

Returns:

of form (exchange, attachments) where exchange: serder of exchange message and atc is serialized path

attachments of embeds

Return type:

embedded (SerderKeri, bytearray)

keri.peer.exchanging.verify(hby, serder)

Verify all stored authentication and evidence for an exchange message.

Any invalid stored attachment fails verification. Source seals are verified but omitted from the legacy two-item return tuple; serializeMessage reloads them for wire reconstruction.

Parameters:

• hby (Habery) – database environment from which to verify message

• serder (Serder) – exn serder to load and verify signatures for

Returns:

Transferable signature groups and non-transferable signatures.

Return type:

tuple

keri.peer.exchanging.verifyAttachments(hby, serder, *, tsgs=None, cigars=None, sourceSeals=None)

Cryptographically verify exchange authentication attachments.

Parameters:

• hby (Habery) – database environment with signer key state

• serder (Serder) – exchange message signed or sealed by the attachments

• tsgs (list) – transferable signature groups with establishment references

• cigars (list) – non-transferable signatures

• sourceSeals (list) – source seal triples

Returns:

Valid transferable signature groups, non-transferable signatures,

source seal triples, an invalid attachment flag, and missing KEL coordinates.

Return type:

tuple