Digital Certificates

The Shamwari Digital Certificate System (nxt.digitalcertificates.ShamwariCertificate) provides a post-quantum public-key infrastructure (PKI) for issuing, managing, verifying, and revoking cryptographically signed identity credentials, agent mandates, and data attestations directly on the blockchain.

Extending java.security.cert.Certificate, ShamwariCertificate bridges standard Java security APIs with NIST-standardized post-quantum cryptography (ML-DSA-2 / Dilithium Level 2). By eliminating external Certificate Authority (CA) single points of failure, OCSP latency, and classical RSA/ECDSA vulnerability to quantum decryption (Harvest Now, Decrypt Later), Shamwari establishes an immutable, publicly verifiable web of trust.

Core Capabilities & Architecture

Post-Quantum Native: Signed using ML-DSA-2 (Dilithium Level 2, FIPS 204) signatures ( $2420$ bytes) offering $\ge 128$ -bit post-quantum security.
Java PKI Compatibility: Fully extends java.security.cert.Certificate, enabling seamless integration with Java key stores, TLS contexts, and enterprise security frameworks.
Autonomous AI Agent Attestations: Protocol-native support for AI agent credentials, scope permissions, liability caps, and target audience restrictions.
Deterministic Serialization: Canonical byte representation (getCanonicalContent()) guarantees consistent signature verification across node implementations.
On-Chain Instant Revocation: Real-time status checks via isActive() bypass legacy OCSP/CRL latency while providing dedicated incremental CRL sync endpoints.
Automatic Renewal: In-place update of expiration and scope fields when re-issuing an identical issuer-recipient-name-type tuple on the same BetaChain.

Data Model & Structure

Every certificate record is stored in the versioned relational table public.certificate indexed by block height.

Field	Type	Description
`id`	`long`	Transaction ID of initial issuance; globally unique handle.
`issuerId`	`long`	Account ID of the issuing entity (must hold valid ML-DSA-2 key pair).
`accountId`	`long`	Account ID of the subject entity or autonomous agent being certified.
`betaChain`	`BetaChain`	BetaChain context on which the certificate was issued.
`certificateName`	`String`	Descriptive handle (e.g., `KYC_LEVEL_2`, `SECURITY_AUDIT_2026`).
`certificateType`	`String`	Functional classification (e.g., `IDENTITY`, `AGENT_ATTESTATION`, `MANDATE`).
`signature`	`byte[]`	$2420$ -byte ML-DSA-2 digital signature covering canonical content.
`expirationTimestamp`	`int`	Expiration time in blockchain epoch seconds ( $0 = \text{perpetual}$ ).
`timestamp`	`int`	Block timestamp of issuance or most recent renewal.
`revoked`	`boolean`	Flag set to `true` upon explicit revocation.
`agentDilithiumPublicKey`	`byte[]`	(Agent) Raw Dilithium public key for autonomous software agents.
`scope`	`String`	(Agent) Comma-separated list of permitted action scopes.
`maxLiabilityQNT`	`long`	(Agent) Maximum monetary liability limit in QNT ( $0 = \text{uncapped}$ ).
`audience`	`String`	(Agent) Comma-separated list of target service/counterparty domains.

Canonical Byte Serialization (`getCanonicalContent`)

To verify signatures deterministically, ShamwariCertificate produces a canonical byte array covering all immutable and operational fields.

Standard Certificate Layout:
┌───────────┬───────────┬───────────┬───────────┬──────────────┬───────────┬──────────────┬─────────────────────┐
│ id        │ issuerId  │ accountId │ nameLen   │ nameBytes    │ typeLen   │ typeBytes    │ expirationTimestamp │
│ (8 Bytes) │ (8 Bytes) │ (8 Bytes) │ (4 Bytes) │ (UTF-8 Var)  │ (4 Bytes) │ (UTF-8 Var)  │ (4 Bytes)           │
└───────────┴───────────┴───────────┴───────────┴──────────────┴───────────┴──────────────┴─────────────────────┘

Agent Attestation Extension (Appended if isAgentAttestation() == true):
┌──────────────┬─────────────────────────┬───────────┬────────────┬─────────────────┬─────────────┬───────────────┐
│ agentKeyLen  │ agentDilithiumPublicKey │ scopeLen  │ scopeBytes │ maxLiabilityQNT │ audienceLen │ audienceBytes │
│ (4 Bytes)    │ (Raw Var)               │ (4 Bytes) │ (UTF-8 Var)│ (8 Bytes)       │ (4 Bytes)   │ (UTF-8 Var)   │
└──────────────┴─────────────────────────┴───────────┴────────────┴─────────────────┴─────────────┴───────────────┘

The content signature is validated against the issuer's public key using:

$\text{Valid} = \text{Crypto.verify}\Big(\text{signature}, \, \text{getCanonicalContent}(), \, \text{issuerDilithiumPublicKey}\Big)$

Autonomous AI Agent Attestations & Mandates

Shamwari natively supports software agent authentication via two specialized certificate types:

AGENT_ATTESTATION (AgentAttestationConstants.CERTIFICATE_TYPE_AGENT_ATTESTATION)
THIRD_PARTY_MANDATE (AgentAttestationConstants.CERTIFICATE_TYPE_THIRD_PARTY_MANDATE)

Agent Control Parameters

Scope Matching (hasScope): Verifies if a given action string exists in the parsed comma-separated scope set.
Audience Enforcement (hasAudience): Restricts where the agent certificate may be presented. An empty audience allows unrestricted global execution.
Liability Caps (maxLiabilityQNT): Establishes on-chain legal/financial risk boundaries for transactions initiated by the agent.

// Example: Checking active agent status and scope
ShamwariCertificate cert = ShamwariCertificate.getActiveAgentCertificate(agentAccountId);

if (cert != null && cert.isActive() && cert.hasScope("PAYMENT_EXECUTION")) {
    if (cert.hasAudience("merchant.shamwari.network")) {
        // Agent is authorized to execute payment
    }
}

Certificate Lifecycle Management

                 ┌──────────────────────────────────────┐
                 │          issueCertificate()          │
                 └──────────────────┬───────────────────┘
                                    │
                                    ▼
                      ┌──────────────────────────┐
                      │    Active Certificate    │
                      │  (isActive() == true)    │
                      └─────┬──────────────┬─────┘
                            │              │
        Renewal (Same Tuple)│              │ REVOKE_CERTIFICATE
                            ▼              ▼
                      ┌───────────┐  ┌─────────────┐
                      │ Updated   │  │   Revoked   │
                      │ Expiry    │  │ (revoked)   │
                      └───────────┘  └─────────────┘

1. Issuance & Renewal

Certificates are issued via issueCertificate(). If an active certificate already exists with the same (issuerId, recipientId, certificateName, certificateType) on the given BetaChain, the transaction performs an in-place renewal. The expirationTimestamp, scope, maxLiabilityQNT, and audience fields are updated while retaining the original certificate id.

2. Verification

A certificate is considered valid if and only if:

revoked == false
expirationTimestamp == 0 OR expirationTimestamp > currentBlockTimestamp
Dilithium signature verification succeeds over getCanonicalContent().

3. Revocation

Executing a revokeCertificate or revokeAgentCertificate transaction updates revoked = true in the state ledger and triggers the CERTIFICATE_REVOKED event. Subsequent isActive() queries immediately return false.

4. PEM Export

Certificates can be exported to standard Privacy-Enhanced Mail (PEM) DER format via exportToPem():

-----BEGIN CERTIFICATE-----
MIIB... (Base64 Encoded Canonical DER Bytes)
-----END CERTIFICATE-----

API	Description
IssueDigitalCertificate	Issue certificate
GetDigitalCertificate	Get single certificate
GetDigitalCertificates	List certificates
VerifyDigitalCertificate	Verify certificate
DownloadCertificate	Download certificate
RevokeCertificate	Revoke certificate
GetAgentCertificate	Get agent certificate
GetAgentCertificates	List agent certificates
GetActiveAgentCertificate	Get active agent certificate

Key Institutional Use Cases

Portable Sovereign Identity (KYC): Regulated financial institutions issue IDENTITY certificates to pre-verified accounts. Third-party services verify compliance status on-chain without storing PII or re-running KYC pipeline checks.
Autonomous AI Agent Mandates: Human principles grant time-bounded, scope-restricted operational mandates to AI trading bots or autonomous payment processors.
App Store & Developer Provenance: Security auditors issue SECURITY_AUDITED or PENETRATION_TESTED certificates to developer accounts and dApp hashes in the Application Registry.
Asset Backing & Commodity Audits: Commodity verifiers issue ASSET_BACKED certificates against tokenized real-world assets (Totems) on BetaChains.

Core Capabilities & Architecture​

Data Model & Structure​

Canonical Byte Serialization (getCanonicalContent)​

Autonomous AI Agent Attestations & Mandates​

Agent Control Parameters​

Certificate Lifecycle Management​

1. Issuance & Renewal​

2. Verification​

3. Revocation​

4. PEM Export​

Related APIs​

Key Institutional Use Cases​