Metadata-Version: 2.4
Name: oris-kya-verify
Version: 0.3.0
Summary: Standalone Know-Your-Agent verifier. Reads on-chain EAS attestations + verifies EIP-712 signatures with zero Oris API dependency.
Project-URL: Homepage, https://useoris.xyz
Project-URL: Documentation, https://docs.useoris.xyz/kya-verify
Project-URL: Repository, https://github.com/fluxaventures/oris
Project-URL: Bug Tracker, https://github.com/fluxaventures/oris/issues
Author-email: Fluxa Ventures <engineering@fluxa.ventures>
License: Apache-2.0
Keywords: agent-payments,attestation,compliance,eas,ethereum,kya
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: coincurve>=19
Requires-Dist: eth-abi>=5
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# oris-kya-verify

> Standalone Know-Your-Agent verifier. Reads on-chain EAS
> attestations and verifies EIP-712 signatures with **zero Oris API
> dependency**. Drop into any payment gateway, wallet provider, or
> compliance pipeline to verify the agent on the other side of a
> transaction.

The package implements the public `KYABundle` schema published at
[`docs.useoris.xyz/spec/kya-bundle-v1.json`](https://docs.useoris.xyz/spec/kya-bundle-v1.json).
Any KYA attestation issued by Oris on Base, Ethereum, Arbitrum, or
Optimism mainnet can be verified by this library without ever
hitting an Oris service.

## Why this exists

Oris issues two parallel attestations for every Know-Your-Agent
state transition (promote, demote, suspend):

1. An off-chain **EIP-712** signed message recoverable to the
   Oris MPC key.
2. An on-chain **EAS** attestation on Base + Ethereum (with optional
   replication to Arbitrum / Optimism).

A third party can verify either independently. This library wraps
both checks behind a single `KYAVerifier.verify()` call.

## Install

```bash
pip install oris-kya-verify
```

Dependencies: `httpx`, `coincurve`, `eth-abi`. No web3.py, no
Postgres, no Oris SDK.

## Usage

```python
import asyncio
from oris_kya import KYAVerifier

async def main():
    verifier = KYAVerifier(chain="base")
    bundle = await verifier.verify("did:ethr:8453:0x7f3a9c2d1b4e5f6a7b8c9d0e1f2a3b4c5d6e7c2d")

    print(f"KYA level: {bundle.kya_level}")
    print(f"Risk score: {bundle.risk_score}/100")
    print(f"Status: {bundle.kya_status}")
    print(f"Attestation UID: {bundle.attestation_uid}")
    print(f"Signed by: {bundle.signer_address}")  # Should match the Oris MPC key
    print(f"Issued at: {bundle.issued_at}")
    print(f"Expires at: {bundle.expires_at}")
    print(f"Expired? {bundle.is_expired}")

    if bundle.kya_level >= 3 and not bundle.is_expired:
        # Authorize the payment.
        pass

asyncio.run(main())
```

## Supported chains

| Chain | EAS contract | Default RPC |
|---|---|---|
| `base` | `0x4200000000000000000000000000000000000021` | `https://mainnet.base.org` |
| `ethereum` | `0xA1207F3BBa224E2c9c3c6D5aF63D0eb1582Ce587` | `https://eth.llamarpc.com` |
| `arbitrum` | `0xbD75f629A22Dc1ceD33dDA0b68c546A1c035c458` | `https://arb1.arbitrum.io/rpc` |
| `optimism` | `0x4200000000000000000000000000000000000021` | `https://mainnet.optimism.io` |

Override `rpc_url` in the `KYAVerifier` constructor to point at
your own RPC (recommended for production: Alchemy, Infura, Helius,
etc.).

## Error handling

The library raises typed exceptions you can catch by category:

- `KYANotAttestedError` — no on-chain attestation exists for this agent.
- `KYAExpiredError` — the latest attestation has passed its `expires_at`.
- `KYAInvalidSignatureError` — the EIP-712 signature does not recover
  to the expected Oris MPC signer.
- `KYAVerificationError` — base class for any of the above.

Network failures bubble up as `httpx.HTTPError`. The library never
silently fails: every "yes" answer is cryptographically grounded.

## Schema

The `KYABundle` returned by `verify()` is a frozen dataclass that
mirrors the public JSON schema at
[`docs.useoris.xyz/spec/kya-bundle-v1.json`](https://docs.useoris.xyz/spec/kya-bundle-v1.json).
Use the schema directly if you are implementing your own verifier
in a different language.

## License

Apache-2.0. See [LICENSE](LICENSE).
