83 lines
3.2 KiB
Markdown
83 lines
3.2 KiB
Markdown
# aere-cloud (Python)
|
|
|
|
The official Python client for the [Aere Cloud API](https://aere.network/cloud.html) — one keyed
|
|
endpoint for RPC, post-quantum signature verification, chain data, notarization, webhooks and
|
|
gas sponsorship on Aere Network (chain 2800). Standard library only; Python 3.9+.
|
|
|
|
Mirror of the JavaScript client `@aere/cloud`: same routes, same semantics, snake_case names.
|
|
|
|
## Install
|
|
|
|
```
|
|
pip install "git+https://git.aere.network/aere-network/aere-cloud-sdk.git#subdirectory=python" # not on PyPI yet
|
|
```
|
|
|
|
Get a key: the free trial is self-serve at [aere.network/cloud.html#subscribe](https://aere.network/cloud.html#subscribe).
|
|
A key looks like `ak2800.<your-0x-address>.<secret>`.
|
|
|
|
## Use
|
|
|
|
```python
|
|
import os
|
|
from aere_cloud import AereCloud, AereCloudError, verify_webhook
|
|
|
|
aere = AereCloud(api_key=os.environ["AERE_KEY"])
|
|
|
|
# chain data
|
|
head = aere.data_head()
|
|
anchors = aere.anchors(5) # post-quantum anchor certificates
|
|
vals = aere.validators() # live QBFT validator set
|
|
|
|
# JSON-RPC
|
|
n = aere.block_number()
|
|
|
|
# post-quantum verification, computed by the chain's own precompiles
|
|
out = aere.pq_verify({
|
|
"scheme": "ml-dsa-44", "publicKey": "0x...", "signature": "0x...", "message": "0x...",
|
|
})
|
|
|
|
# notarize a document hash — Aere pays the gas
|
|
receipt = aere.notarize("0x" + sha256_hex)
|
|
|
|
# Trust API (1.6.0): any AERE Proof Protocol (AIP-23) envelope -> VALID / INVALID / PARTIAL, with the levels checked
|
|
r = aere.verify(envelope, chain=2800) # {"verdict", "levels", "verifier", "reproduce"}
|
|
proof = aere.proof_of("0x" + sha256_hex)
|
|
|
|
# a smart account with a POST-QUANTUM owner (Falcon-512), gas sponsored:
|
|
acct = aere.sponsor_create_pq_account("0x09" + falcon_pk_hex, salt=0)
|
|
# -> {"txHash": ..., "account": "0x...", "alreadyDeployed": False}
|
|
```
|
|
|
|
Every method raises `AereCloudError` on a non-2xx response, carrying `.status` and the server's
|
|
JSON `.body` so you can act on the exact error.
|
|
|
|
## Proof with post-quantum finality, quantum readiness (1.2.0, 2026-09-17)
|
|
|
|
```python
|
|
full = aere.proof(digest_hex) # first appearance, covering post-quantum anchor, finality, verification steps
|
|
scan = aere.readiness("example.com") # free, no key: score, verdict, measured TLS facts, findings
|
|
attested = aere.readiness("example.com", attest=True) # + attestation: report digest notarized on chain 2800
|
|
perimeter = aere.readiness_perimeter("example.com", hosts=["api", "mail"]) # 1.3.0: every public host of the domain, one report (keyed)
|
|
# pq_verify: {"interface": "external"} verifies a standard FIPS 204/205 signature (the precompile implements the
|
|
# internal interface; the gateway builds M' = 0x00 || len(ctx) || ctx || message)
|
|
```
|
|
|
|
## Webhooks
|
|
|
|
Never trust a webhook payload without checking its signature (constant-time, HMAC-SHA256):
|
|
|
|
```python
|
|
from aere_cloud import verify_webhook
|
|
|
|
# in your handler; raw_body must be the exact request bytes, not re-serialized JSON
|
|
if not verify_webhook(raw_body, request.headers["x-aere-signature"], stored_secret):
|
|
return 401
|
|
```
|
|
|
|
## Tests
|
|
|
|
```
|
|
python3 test_aere_cloud.py # unit, offline, fake transport
|
|
AERE_KEY=ak2800... python3 test_aere_cloud.py --live # + live probes against production
|
|
```
|