Private evidence commitments and issuer-status verification on Stellar testnet.
An organization can share a ProofGrid record and signed manifest privately with another organization. The recipient can check the record's integrity, apply its own issuer trust policy, and look up the issuer's current public status without sharing a private storage system.
Status: functional testnet developer preview. Synthetic issuance, verification, supersession and revocation have been exercised on live testnet. This adapter verifies commitments and current issuer status; it does not verify physical events, manufacturer approval or permanent revocation. Production readiness remains future work.
ProofGrid Core defines the evidence schemas and assessment CLI/SDK. ProofGrid Registry supplies source-backed manufacturer packs. This optional adapter adds signatures, private salted commitments and public status through native Stellar account data.
Core and registry work without Stellar. This repository includes its own pinned core artifact and installs without sibling checkouts. Only testnet is supported; no custom Soroban contract is deployed.
Requires Node.js 24+, npm and Git.
git clone https://github.com/proofgrid-energy/proofgrid-stellar.git
cd proofgrid-stellar
npm ci
npm test
npm run demoExpected: 23 tests pass for the September 5, 2026 preview. The demo prints two results: verified, then revoked, both explicitly labeled offline simulated ledger (not live verification). After installing dependencies, these checks need no live ledger or wallet.
Windows PowerShell: use npm.cmd in place of npm. If Node is installed in C:\Program Files\nodejs but commands are not found:
$env:Path = "C:\Program Files\nodejs;$env:Path"
node --version
npm.cmd --versionThis adjusts only the current terminal. Run each command separately and let it finish; copy commands without terminal prompts.
This opt-in command needs internet access. It creates an ephemeral account, requests test funds from Friendbot and publishes only synthetic commitments and status metadata. It uses no real funds or customer records.
npm run demo:testnetExpected progress:
Funding a new ephemeral TESTNET account; no real funds or private evidence.
Issued first commitment.
Issued successor commitment.
Independent lookup confirms supersession.
Independent lookup confirms revocation.
The final JSON report includes transaction hashes and confirms active verification, supersession, revocation, tampering rejection and unknown-issuer rejection. Each successful run writes .local-checks/testnet-result.json (ignored by Git). The temporary signing key is neither logged nor saved and is discarded when the process exits.
An earlier successful run is preserved in docs/testnet-result.json. A separate maintainer-run lifecycle on September 5, 2026 also passed at ledgers 4519308–4519311. These are historical testnet observations; the network can reset. CI runs offline tests and the simulated demo, not live transactions.
An error such as getaddrinfo ENOENT friendbot.stellar.org means the funding hostname could not be resolved. That run stops before issuing ProofGrid commitments. In PowerShell, check DNS and Node lookup separately:
Resolve-DnsName friendbot.stellar.org -Type A
node -e "require('node:dns').lookup('friendbot.stellar.org', console.log)"When Node returns an address without an error, retry npm.cmd run demo:testnet. Successful DNS resolution alone does not guarantee the service is reachable. Preserve certificate verification; package reinstallation does not fix DNS lookup failures.
- Validate a synthetic or privately held record against the core evidence schema.
- Canonicalize it with RFC 8785, bind it to the protocol/network/schema/issuer and random identifier, and create a SHA-256 commitment using a random 256-bit salt.
- Sign the commitment and retain the record and manifest privately.
- Publish the commitment and current status in the issuer's native Stellar account data.
- The recipient checks the signature, recomputes the commitment, applies an explicit manufacturer/schema-scoped trust policy, and queries current status.
| Private material | Public metadata |
|---|---|
| Record, salt and signed manifest | Issuer account and random attestation ID |
| Invoices, serial numbers, photos, logs and storage pointers | Commitment, status and optional successor ID |
Issuer activity, transaction timing and successor links remain correlatable. Random salts prevent identical records from automatically producing stable public commitments; they do not remove all metadata leakage.
See the runnable offline example and testnet example for record and trust-policy construction.
| Export | Purpose |
|---|---|
createAttestation(record, keypair) |
Create a private salted and signed manifest for a valid record |
verifyAttestation(record, manifest, trustPolicy, lookup) |
Verify integrity, consumer trust and supplied current status |
testnetLookup(issuer, id) |
Read current status from the fixed testnet Horizon gateway |
submitTestnetStatus(manifest, keypair, state?, successorId?) |
Issue or update status using the issuer's key |
buildStatusTransaction(account, manifest, state?, successorId?) |
Build an unsigned testnet transaction for external signing |
encodeStatus(manifest, state?, successorId?) / decodeStatus(bytes) |
Encode or decode the public status entry |
Verification returns verified, invalid, unknown, untrusted_issuer, revoked or superseded. Missing or unavailable ledger state remains unknown. Owning a signing key alone does not authorize a manufacturer: the consumer must explicitly enable the issuer for the record's manufacturer and schema version.
The package is a private development artifact, not an npm release. The source entry point exports the API; the pinned core tarball and its provenance live in vendor/.
Native account data is mutable by its controller. The submission helper rejects reuse/reactivation and requires an active same-issuer successor, but an issuer can bypass the helper. This does not enforce irreversible revocation or preserve an independently verified history.
Current-status verification trusts the configured Horizon gateway. It is not a light-client proof. Custody, key rotation, multisig, gateway redundancy and AttestProtocol interoperability require further work. Record integrity also does not establish accurate measurements, authentic document contents or physical truth.
See design and alternatives, the backlog and security guidance. Keep signing keys, manifest salts and customer evidence out of Git and public reports.
Start with CONTRIBUTING.md. Current work includes detecting or preventing issuer reactivation, explicit rotation/custody policy, gateway failure handling and interoperability research. Contributions need precise trust assumptions and tests for tampered, missing, revoked and untrusted inputs. Live tests remain opt-in and use synthetic data only.
New ProofGrid source uses MPL-2.0. LICENSING.md preserves earlier Apache grants and third-party notices. The vendored core artifact carries its own notices and source/hash provenance.
See the submission brief, verification record, maintainers, and focused contributor backlog.
The synthetic live Testnet lifecycle passed at ledgers 5072870–5072873: transaction hashes and observed checks. The original September evidence is preserved. These are dated observations, not physical-event verification or a permanent-revocation guarantee.