Metadata-Version: 2.4
Name: algovoi-pef-keystone
Version: 0.1.0
Summary: AlgoVoi Payment Evidence Frame (PEF), the signed-transport layer over the Keystone. Wraps and pins a keystone reference so the frame_id commits to it; chains frames into one trust_query_ref-capped audit chain. Open, content-addressed, unsigned (signing is the commercial tier). Runs on any algovoi-substrate version (v0/v1); uses only JCS RFC 8785 canonicalisation.
Author-email: AlgoVoi <chopmob@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://api.algovoi.co.uk
Project-URL: Documentation, https://docs.algovoi.co.uk/keystone
Keywords: x402,ap2,a2a,mpp,jcs,rfc8785,canonicalisation,agentic-payments,payment-evidence-frame,pef,keystone,audit-chain,execution_ref
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: algovoi-substrate>=0.3.0
Requires-Dist: algovoi-execution-ref>=0.1.0
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: pytest-cov>=4; extra == "test"
Dynamic: license-file

# 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

```python
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`](https://pypi.org/project/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`](https://www.npmjs.com/package/@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 chopmob@gmail.com 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`.
