aere-cloud-sdk/java/README.md

aere-cloud (Java)

The official Java client for the Aere Cloud API — one keyed endpoint for RPC, post-quantum signature verification, chain data, notarization, webhooks and gas sponsorship on Aere Network (chain 2800). Zero dependencies beyond the standard library: java.net.HttpURLConnection and javax.crypto only. Since 1.6.1 the class uses only the Java 8 API (the tests enforce it with javac --release 8), which is what Android provides; it has not yet been run on an Android device (see below). It does not follow redirects: a 3xx is raised as an error, so your API key is never sent to a host you did not name.

Mirror of @aere/cloud (JS) and aere-cloud (Python): same routes, same semantics. Bodies are raw JSON strings — the client does not force a JSON library on the integrator; parse responses with whatever you already use (Jackson, Gson, org.json, ...).

Use

import network.aere.cloud.AereCloud;

var aere = new AereCloud(System.getenv("AERE_KEY"));

String head = aere.dataHead();          // {"block":...,"chainId":2800,...}
String anchors = aere.anchors(5);       // post-quantum anchor certificates
long n = aere.blockNumber();

// a smart account with a POST-QUANTUM owner (Falcon-512), gas sponsored:
String acct = aere.sponsorCreatePqAccount("0x09" + falconPkHex, 0);

// Trust API (1.6.0): any AERE Proof Protocol (AIP-23) envelope (JSON text) -> VALID / INVALID / PARTIAL with the levels checked
String verdict = aere.verify(envelopeJson, 2800);

// identity and compliance (1.7.0): the request as JSON text, sent as given; read "verdict" (PARTIAL: some rows not judged)
String id = aere.identityVerify("{\"presentation\":" + presentationJson + ",\"audience\":\"https://your.app/verifier\",\"nonce\":\"" + nonce + "\"}");
// payments (1.8.0): the risk step and the receipt, the request as JSON text; USD at the rate you declare; a REFUSE is a verdict
String risk = aere.paymentsRisk("{\"policy\":" + policyJson + ",\"inputs\":" + inputsJson + "}");
String ok = aere.complianceCheck(requestWithPolicyJson);

// verify a webhook delivery (constant-time HMAC) — never trust one without this:
boolean ok = AereCloud.verifyWebhook(rawBodyBytes, request.header("x-aere-signature"), secret);

Non-2xx responses raise AereCloud.AereCloudException with .status, .body (server JSON) and .path.

Since 1.5.0 (same surface as the JS and Python SDKs 1.5.0)

aere.proof("0x" + sha256Hex);                            // a proof under a post-quantum certificate
aere.readiness("example.com", false, false);             // quantum-readiness scan, free, no key sent
aere.readinessPerimeter("example.com", new String[]{"api"}, null, false); // a domain's whole public perimeter
aere.pqFinality("latest", "testnet", "both");         // AIP-21 per-block PQ seal record, both clients

AereCloud.AuditExport day = aere.auditExport("2026-09-24", "jsonl");
// day.bytes are the exact bytes of the day file; day.verified is true only if THEIR sha256 equals the stated digest

aere.auditRetention();                                    // read-only with the API key; set it in the console
AereCloud.KeptCheck k = aere.auditVerifyKept("2026-05-01", keptBytes);
// k.matches: your kept export still matches the day we hold, or the tombstone (digest) a deleted day left behind

auditVerifyKept hashes YOUR bytes locally. An error (rate limit, network) is raised, never returned as "does not match".

Android

Copy src/main/java/network/aere/cloud/AereCloud.java into your app module (package network.aere.cloud) and call it off the main thread, as with any network call on Android. What is measured: the class compiles against the Java 8 API (javac --release 8) and its tests pass on the JDK. What is not: we have not run it on an Android device or emulator.

Tests

javac --release 8 -d out8 src/main/java/network/aere/cloud/AereCloud.java          # the Android gate: Java 8 API only
javac -d out src/main/java/network/aere/cloud/AereCloud.java src/test/java/network/aere/cloud/TestAereCloud.java
java -cp out network.aere.cloud.TestAereCloud                    # unit, offline
AERE_KEY=ak2800... java -cp out network.aere.cloud.TestAereCloud --live   # + live probes

Measured 2026-08-27: 7/7 green, including live probes against production (health, validator set, block number, and the free JSON refusal on the PQ sponsorship route).

Measured 2026-09-28 (1.6.1, JDK 21): 9/9 offline, including a 302 to a second local host that receives zero requests; the negative control (node control-negativ.mjs) turns 8 of 8 planted faults red, among them a followed redirect and two post-Java-8 calls that the JDK tests alone would not catch but --release 8 refuses.

Measured 2026-09-25 (1.5.0): 7/7 offline, the new routes judged against a local JDK HTTP server (what the client sends, what it does with each answer). node control-negativ.mjs breaks five guards in a copy of the class and requires each one's test to fail: 5/5 red, the untouched class green.