Java SDK

Requires Java 11+ and Maven 3.8+ (for building from source).

Installation

<dependency>
    <groupId>io.uverify</groupId>
    <artifactId>uverify-sdk</artifactId>
    <version>0.1.0</version>
</dependency>

Quick Start

import io.uverify.sdk.UVerifyClient;
import io.uverify.sdk.model.CertificateResponse;
import java.util.List;
 
UVerifyClient client = new UVerifyClient();
 
List<CertificateResponse> certs = client.verify("a3b4c5d6...");
certs.forEach(c -> System.out.println(c.getTransactionHash()));

Creating the client

// Connect to the public API (default)
UVerifyClient client = new UVerifyClient();
 
// Connect to a self-hosted instance
UVerifyClient client = UVerifyClient.builder()
    .baseUrl("http://localhost:9090")
    .build();
 
// Register default signing callbacks so you don't pass them on every call
UVerifyClient client = UVerifyClient.builder()
    .signMessage(message -> wallet.signData(address, message))
    .signTx(unsignedTx -> wallet.signTx(unsignedTx))
    .build();

Verify a certificate

// By data hash
List<CertificateResponse> certs = client.verify("sha256-or-sha512-hex-hash");
 
// By transaction hash + data hash
CertificateResponse cert = client.verifyByTransaction("cardano-tx-hash", "data-hash");

Issue certificates

issueCertificates handles the full flow — build, sign, submit — in one call.

metadata must be a JSON string; use your preferred JSON library to serialise objects.

import com.fasterxml.jackson.databind.ObjectMapper;
import io.uverify.sdk.model.CertificateData;
import java.util.List;
import java.util.Map;
 
ObjectMapper mapper = new ObjectMapper();
 
String metadata = mapper.writeValueAsString(Map.of(
    "issuer", "Acme Corp",
    "description", "Proof of existence",
    "date", "2024-01-01"
));
 
client.issueCertificates(
    "addr1...",
    List.of(new CertificateData("sha256-hash-of-document", "SHA-256", metadata)),
    unsignedTx -> wallet.signTx(unsignedTx)  // omit if set in constructor
);

Optionally pass a stateId to issue under a specific state:

client.issueCertificates(
    "addr1...",
    "my-state-id",
    List.of(new CertificateData("sha256-hash", "SHA-256"))
    // uses constructor signTx
);

User state management

import io.uverify.sdk.model.ExecuteUserActionResponse;
 
ExecuteUserActionResponse response = client.getUserInfo("addr1...");
System.out.println("Certificates remaining: " + response.getState().getCountdown());
 
client.invalidateState("addr1...", "state-id");
client.optOut("addr1...", "state-id");

A per-call signing callback can be passed as the last argument to any of these methods if you didn’t register one in the constructor.

Low-level access via `.core`

import io.uverify.sdk.model.BuildTransactionRequest;
import io.uverify.sdk.model.BuildTransactionResponse;
 
// Build
BuildTransactionResponse response = client.core.buildTransaction(
    BuildTransactionRequest.defaultRequest(
        "addr1...", "your-state-id",
        new CertificateData("sha256-hash", "SHA-256")
    )
);
 
// Sign with your wallet, then submit
String witnessSet = wallet.signTx(response.getUnsignedTransaction());
client.core.submitTransaction(response.getUnsignedTransaction(), witnessSet);

import io.uverify.sdk.model.UserActionRequest;
import io.uverify.sdk.model.UserActionRequest.UserAction;
import io.uverify.sdk.model.UserActionRequestResponse;
import io.uverify.sdk.model.ExecuteUserActionRequest;
 
// Two-step user state action (manual)
UserActionRequestResponse challenge = client.core.requestUserAction(
    new UserActionRequest("addr1...", UserAction.USER_INFO)
);
 
DataSignature sig = wallet.signData(address, challenge.getMessage());
 
ExecuteUserActionResponse result = client.core.executeUserAction(
    new ExecuteUserActionRequest(challenge, sig.getSignature(), sig.getKey())
);
System.out.println(result.getState());

Error handling

import io.uverify.sdk.exception.UVerifyException;
import io.uverify.sdk.exception.UVerifyValidationException;
 
try {
    client.issueCertificates("addr1...", certs);
} catch (UVerifyException e) {
    System.err.println("API error " + e.getStatusCode() + ": " + e.getMessage());
} catch (UVerifyValidationException e) {
    System.err.println(e.getMessage());
}

Building from source

cd java/
mvn clean package

API Reference

High-level helpers

Method	Description
`verify(hash)`	Look up all on-chain certificates for a data hash
`verifyByTransaction(txHash, dataHash)`	Fetch a specific certificate by tx hash + data hash
`issueCertificates(address, certificates, signTx?)`	Build, sign, and submit a certificate transaction
`issueCertificates(address, stateId, certificates, signTx?)`	Same, scoped to a state
`getUserInfo(address, signMessage?)`	Retrieve the current user state
`invalidateState(address, stateId, signMessage?)`	Mark a state as invalid
`optOut(address, stateId, signMessage?)`	Remove the user’s state entirely

Low-level core (`.core`)

Method	Endpoint
`core.buildTransaction(request)`	`POST /api/v1/transaction/build`
`core.submitTransaction(tx, witnessSet?)`	`POST /api/v1/transaction/submit`
`core.requestUserAction(request)`	`POST /api/v1/user/request/action`
`core.executeUserAction(request)`	`POST /api/v1/user/state/action`

Python Team