97 lines
4.0 KiB
Markdown
97 lines
4.0 KiB
Markdown
# @aere/cloud
|
|
|
|
The official 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). Zero dependencies; runs in Node 18+ and modern
|
|
browsers.
|
|
|
|
## Install
|
|
|
|
```
|
|
npm install @aere/cloud
|
|
```
|
|
|
|
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
|
|
|
|
```js
|
|
import { AereCloud } from '@aere/cloud';
|
|
|
|
const aere = new AereCloud({ apiKey: process.env.AERE_KEY });
|
|
|
|
// chain data
|
|
const head = await aere.dataHead();
|
|
const anchors = await aere.anchors(5); // post-quantum anchor certificates
|
|
const set = await aere.validators(); // live QBFT validator set
|
|
|
|
// JSON-RPC
|
|
const block = await aere.blockNumber();
|
|
|
|
// post-quantum verification, computed by the chain's own precompiles
|
|
const { valid } = await aere.pqVerify({
|
|
scheme: 'ml-dsa-44', publicKey: '0x…', signature: '0x…', message: '0x…',
|
|
});
|
|
|
|
// notarize a document hash — Aere pays the gas
|
|
const receipt = await aere.notarize('0x' + sha256Hex);
|
|
const proof = await aere.proofOf('0x' + sha256Hex); // { notarized, firstSeenAt, … }
|
|
|
|
// 1.2.0 (2026-09-17): the proof with its post-quantum finality: first appearance from the contract log,
|
|
// the anchor that covers it, a verdict, and how to verify every claim without Aere Cloud
|
|
const full = await aere.proof('0x' + sha256Hex); // { block, txHash, finality: 'post-quantum', pqAnchor: {…}, verify: {…} }
|
|
|
|
// quantum readiness of a domain's public TLS edge (free, no key); attest:true notarizes the report digest on chain
|
|
const scan = await aere.readiness('example.com'); // { score, verdict, summary, findings, … }
|
|
const attested = await aere.readiness('example.com', { attest: true }); // + attestation: { reportHash, txHash, proof, … }
|
|
|
|
// pqVerify: pass interface:'external' to verify a standard FIPS 204/205 signature (the precompile implements the
|
|
// internal interface; the gateway builds M' = 0x00 || len(ctx) || ctx || message for you)
|
|
const v = await aere.pqVerify({ scheme: 'ml-dsa-44', interface: 'external', publicKey, signature, message });
|
|
|
|
// transfer history for an address (token from genesis, native from launch)
|
|
const tx = await aere.transfers('0xYourAddress', 50);
|
|
|
|
// a smart account with a POST-QUANTUM owner (Falcon-512), gas sponsored:
|
|
const acct = await aere.sponsorCreatePqAccount('0x09' + falconPkHex, 0);
|
|
// -> { txHash, account: '0x…', alreadyDeployed: false }
|
|
```
|
|
|
|
A Python mirror of this client lives in `sdk/python/` (`pip install aere-cloud`): same routes,
|
|
same semantics, snake_case names.
|
|
|
|
Every method throws `AereCloudError` on a non-2xx response, carrying `.status` and the server's
|
|
JSON `.body` so you can act on the exact error.
|
|
|
|
## Webhooks
|
|
|
|
Create a webhook and verify every delivery — never trust a webhook payload without checking its
|
|
signature:
|
|
|
|
```js
|
|
import { AereCloud, verifyWebhook } from '@aere/cloud';
|
|
|
|
const aere = new AereCloud({ apiKey: process.env.AERE_KEY });
|
|
const wh = await aere.createWebhook({ type: 'pq-anchors', url: 'https://you.example/hook' });
|
|
// store wh.secret now — it is shown once
|
|
|
|
// in your webhook handler (raw body, not re-serialized):
|
|
app.post('/hook', async (req, res) => {
|
|
const ok = await verifyWebhook(req.rawBody, req.headers['x-aere-signature'], WEBHOOK_SECRET);
|
|
if (!ok) return res.status(401).end();
|
|
handle(JSON.parse(req.rawBody));
|
|
res.status(200).end();
|
|
});
|
|
```
|
|
|
|
Webhook types: `pq-anchors` (every 32nd-block certificate), `address-activity` (transactions
|
|
touching a watched address, pass `watch`), `subscription-events` (your billing events).
|
|
|
|
## Reference
|
|
|
|
Full API reference and OpenAPI spec: [aere.network/cloud-docs.html](https://aere.network/cloud-docs.html)
|
|
· live status you compute in your own browser: [aere.network/cloud-status.html](https://aere.network/cloud-status.html)
|
|
|
|
MIT licensed.
|