@algovoi/pef-keystone

algovoi-pef-keystone

Payment Evidence Frame (PEF), the signed-transport layer over the AlgoVoi Keystone.

A PEF frame wraps a keystone reference (or any lifecycle receipt) and pins it, so the frame's content-addressed frame_id commits to the exact keystone position it carries. Frames link into an audit chain, each row's prev_hash is the prior row's hash, capped by one trust_query_ref. PEF is the envelope and delivery layer, not a new link in the keystone chain.

This is the open edition: content-addressed and unsigned. The frame is byte-identical to the published pef_v1 / pef_keystone_v1 conformance construction. It runs unchanged on any algovoi-substrate version (v0 and v1), using only JCS (RFC 8785) canonicalisation.

receipt_hash = "sha256:" + SHA-256(JCS(receipt))     # pins the wrapped payload
frame_id     = "sha256:" + SHA-256(JCS(preimage))    # commits to the whole frame

Install

pip install algovoi-pef-keystone

Use

from algovoi_pef_keystone import evidence_frame, audit_chain_of_frames, verify_frame

# wrap a keystone fact (e.g. an execution_binding record) in a signed-transport frame
frame = evidence_frame(
    claim_type="payment_execution",
    receipt_format="execution-binding-v1",
    receipt={"binding_ref": "sha256:...", "canon_version": "urn:x402:canonicalisation:jcs-rfc8785-v1",
             "execution_ref": "sha256:...", "retention_chain_ref": "sha256:...", "settlement_ref": "sha256:..."},
    frame_provider_did="did:web:api.algovoi.co.uk",
    frame_timestamp_ms=1748534600000,
)
frame["frame_id"]        # commits to the exact keystone position carried
verify_frame(frame)      # True

# chain the whole lifecycle (execution -> settlement -> refund) and cap it with one verdict
chain = audit_chain_of_frames([f1_id, f2_id, f3_id], "TRUSTED")
chain["cap"]             # one trust_query_ref over the ordered frames

evidence_frame produces the byte-identical pef_v1 preimage, so frame_id matches the published conformance value for the same inputs. The keystone references themselves come from algovoi-execution-ref (bind_keystone, execution_binding); this package is the transport around them.

Verify it yourself

Offline, from the public conformance corpus, no package import:

git clone https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors
python composition/pef_keystone_v1/verify_pef_keystone.py             # frame wraps + pins a keystone fact
python composition/audit_chain_of_frames_v1/verify_audit_chain_of_frames.py  # lifecycle as chained frames, capped

TypeScript twin: @algovoi/pef-keystone, byte-identical output.

Licensing

Apache-2.0. Frames are content addressed, no signature. The commercial tier adds the cryptographic signature (hybrid Falcon-1024 + ML-DSA-65) and Compliance Command Center ingest over the same frame.

Pinned edition for adopters, with a free key. Pin algovoi-pef-keystone==0.1.0, anchor a pef_keystone_v1 (or audit_chain_of_frames_v1) vector hash, and keep the NOTICE; that four check gate earns a free v0 licence key for algovoi-mandate-auditor (email [e-mail] with your import-by-hash evidence and the NOTICE).

Python and TypeScript produce identical bytes on the same input. Redistribution must retain the NOTICE and the Apache-2.0 LICENSE.