Types Reference¶

This page documents the shared data types used across all Dilithia SDK methods. Each type has a canonical structure that is represented idiomatically in each language.

Branded / Named Types¶

v0.3.0 introduces strongly typed wrappers for common primitives. These prevent accidentally passing an address where a transaction hash is expected, and carry domain-specific formatting/validation.

Address¶

A Dilithia address string with checksum validation.

TypeScriptPythonRustGoJavaC#

// Branded type -- a string at runtime, but distinct at compile time
type Address = string & { readonly __brand: "Address" };

const addr = Address("dili1abc...");  // validates + brands

@dataclass(frozen=True, slots=True)
class Address:
    value: str

    @classmethod
    def of(cls, raw: str) -> "Address": ...

// Rust SDK continues to use plain String for addresses

type Address string

func NewAddress(raw string) (Address, error)

public record Address(String value) {
    public static Address of(String raw) { ... }
}

public sealed record Address(string Value)
{
    public static Address Of(string raw) => ...;
}

TxHash¶

A transaction hash string.

TypeScriptPythonGoJavaC#

type TxHash = string & { readonly __brand: "TxHash" };

@dataclass(frozen=True, slots=True)
class TxHash:
    value: str

type TxHash string

public record TxHash(String value) {
    public static TxHash of(String raw) { ... }
}

public sealed record TxHash(string Value)
{
    public static TxHash Of(string raw) => ...;
}

PublicKey / SecretKey¶

Hex-encoded ML-DSA-65 key strings with length validation.

TypeScriptPythonGoJavaC#

type PublicKey = string & { readonly __brand: "PublicKey" };
type SecretKey = string & { readonly __brand: "SecretKey" };

@dataclass(frozen=True, slots=True)
class PublicKey:
    value: str

@dataclass(frozen=True, slots=True)
class SecretKey:
    value: str

type PublicKey string
type SecretKey string

public record PublicKey(String value) { ... }
public record SecretKey(String value) { ... }

public sealed record PublicKey(string Value);
public sealed record SecretKey(string Value);

TokenAmount¶

Represents a token amount with full precision.

TypeScriptPythonGoJavaC#

// BigInt-backed for lossless arithmetic
type TokenAmount = bigint & { readonly __brand: "TokenAmount" };

@dataclass(frozen=True, slots=True)
class TokenAmount:
    value: Decimal  # decimal.Decimal for lossless arithmetic

// Uses *big.Int for token amounts

public record TokenAmount(BigDecimal value) {
    public static TokenAmount of(String raw) { ... }
    public static TokenAmount of(BigDecimal amount) { ... }
}

public sealed record TokenAmount(decimal Value)
{
    public static TokenAmount Dili(string amount) => ...;
    public static TokenAmount Dili(long amount) => ...;
    public static TokenAmount FromRaw(string raw, int decimals) => ...;
}

Typed Response Objects¶

Balance¶

Returned by getBalance / get_balance.

TypeScriptPythonGoJavaC#

type Balance = {
  address: Address;
  available: TokenAmount;
  staked: TokenAmount;
  locked: TokenAmount;
};

@dataclass(frozen=True, slots=True)
class Balance:
    address: Address
    available: TokenAmount
    staked: TokenAmount
    locked: TokenAmount

type Balance struct {
    Address   Address  `json:"address"`
    Available *big.Int `json:"available"`
    Staked    *big.Int `json:"staked"`
    Locked    *big.Int `json:"locked"`
}

public record Balance(
    Address address,
    TokenAmount available,
    TokenAmount staked,
    TokenAmount locked
) {}

public sealed record Balance(
    Address Address,
    TokenAmount Available,
    TokenAmount Staked,
    TokenAmount Locked
);

Nonce¶

Returned by getNonce / get_nonce.

TypeScriptPythonGoJavaC#

type Nonce = { address: Address; value: number };

@dataclass(frozen=True, slots=True)
class Nonce:
    address: Address
    value: int

type Nonce struct {
    Address Address `json:"address"`
    Value   uint64  `json:"value"`
}

public record Nonce(Address address, long value) {}

public sealed record Nonce(Address Address, long Value);

Receipt¶

Returned by getReceipt / get_receipt and waitForReceipt.

TypeScriptPythonGoJavaC#

type Receipt = {
  txHash: TxHash;
  status: "success" | "failure";
  blockHeight: number;
  gasUsed: number;
  events: unknown[];
};

@dataclass(frozen=True, slots=True)
class Receipt:
    tx_hash: TxHash
    status: str
    block_height: int
    gas_used: int
    events: list[dict]

type Receipt struct {
    TxHash      TxHash `json:"tx_hash"`
    Status      string `json:"status"`
    BlockHeight uint64 `json:"block_height"`
    GasUsed     uint64 `json:"gas_used"`
    Events      []any  `json:"events"`
}

public record Receipt(
    TxHash txHash,
    String status,
    long blockHeight,
    long gasUsed,
    List<Map<String, Object>> events
) {}

public sealed record Receipt(
    TxHash TxHash,
    string Status,
    long BlockHeight,
    long GasUsed,
    IReadOnlyList<Dictionary<string, object>> Events
);

NetworkInfo¶

Returned by chain info queries.

TypeScriptPythonGoJavaC#

type NetworkInfo = {
  chainId: string;
  blockHeight: number;
  tps: number;
};

@dataclass(frozen=True, slots=True)
class NetworkInfo:
    chain_id: str
    block_height: int
    tps: float

type NetworkInfo struct {
    ChainID     string `json:"chain_id"`
    BlockHeight uint64 `json:"block_height"`
    TPS         float64 `json:"tps"`
}

public record NetworkInfo(String chainId, long blockHeight, double tps) {}

public sealed record NetworkInfo(string ChainId, long BlockHeight, double Tps);

GasEstimate¶

Returned by getGasEstimate / get_gas_estimate.

TypeScriptPythonGoJavaC#

type GasEstimate = {
  gasLimit: number;
  gasPrice: TokenAmount;
};

@dataclass(frozen=True, slots=True)
class GasEstimate:
    gas_limit: int
    gas_price: TokenAmount

type GasEstimate struct {
    GasLimit uint64   `json:"gas_limit"`
    GasPrice *big.Int `json:"gas_price"`
}

public record GasEstimate(long gasLimit, TokenAmount gasPrice) {}

public sealed record GasEstimate(long GasLimit, TokenAmount GasPrice);

SubmitResult¶

Returned by sendCall / send_call and deploy/upgrade operations.

TypeScriptPythonGoJavaC#

type SubmitResult = {
  txHash: TxHash;
};

@dataclass(frozen=True, slots=True)
class SubmitResult:
    tx_hash: TxHash

type SubmitResult struct {
    TxHash TxHash `json:"tx_hash"`
}

public record SubmitResult(TxHash txHash) {}

public sealed record SubmitResult(TxHash TxHash);

QueryResult¶

Returned by queryContract / query_contract.

TypeScriptPythonGoJavaC#

type QueryResult = {
  data: unknown;
  gasUsed: number;
};

@dataclass(frozen=True, slots=True)
class QueryResult:
    data: Any
    gas_used: int

type QueryResult struct {
    Data    any    `json:"data"`
    GasUsed uint64 `json:"gas_used"`
}

public record QueryResult(Object data, long gasUsed) {}

public sealed record QueryResult(object Data, long GasUsed);

NameRecord¶

Returned by resolveName / resolve_name.

TypeScriptPythonGoJavaC#

type NameRecord = {
  name: string;
  address: Address;
  owner: Address;
  expiry: number;
};

@dataclass(frozen=True, slots=True)
class NameRecord:
    name: str
    address: Address
    owner: Address
    expiry: int

type NameRecord struct {
    Name    string  `json:"name"`
    Address Address `json:"address"`
    Owner   Address `json:"owner"`
    Expiry  uint64  `json:"expiry"`
}

public record NameRecord(String name, Address address, Address owner, long expiry) {}

public sealed record NameRecord(string Name, Address Address, Address Owner, long Expiry);

RegistrationCost¶

Result of querying the cost to register a name.

TypeScriptPythonRustGoJavaC#

type RegistrationCost = {
  name: string;
  cost: number;
  duration?: number;
};

@dataclass(frozen=True, slots=True)
class RegistrationCost:
    name: str
    cost: int
    duration: int | None = None

pub struct RegistrationCost {
    pub name: String,
    pub cost: u64,
    pub duration: Option<u64>,
}

type RegistrationCost struct {
    Name     string  `json:"name"`
    Cost     uint64  `json:"cost"`
    Duration *uint64 `json:"duration,omitempty"`
}

public record RegistrationCost(String name, long cost, Long duration) {}

public sealed record RegistrationCost(string Name, long Cost, long? Duration);

Credential¶

An on-chain credential with issuer, holder, schema hash, and status.

TypeScriptPythonRustGoJavaC#

type Credential = {
  id: string;
  issuer: Address;
  holder: Address;
  schemaHash: string;
  issuedAt: number;
  revoked: boolean;
};

@dataclass(frozen=True, slots=True)
class Credential:
    id: str
    issuer: Address
    holder: Address
    schema_hash: str
    issued_at: int
    revoked: bool

pub struct Credential {
    pub id: String,
    pub issuer: String,
    pub holder: String,
    pub schema_hash: String,
    pub issued_at: u64,
    pub revoked: bool,
}

type Credential struct {
    ID         string  `json:"id"`
    Issuer     Address `json:"issuer"`
    Holder     Address `json:"holder"`
    SchemaHash string  `json:"schema_hash"`
    IssuedAt   uint64  `json:"issued_at"`
    Revoked    bool    `json:"revoked"`
}

public record Credential(
    String id,
    Address issuer,
    Address holder,
    String schemaHash,
    long issuedAt,
    boolean revoked
) {}

public sealed record Credential(
    string Id,
    Address Issuer,
    Address Holder,
    string SchemaHash,
    long IssuedAt,
    bool Revoked
);

CredentialSchema¶

A registered credential schema with typed attributes.

TypeScriptPythonRustGoJavaC#

type CredentialSchema = {
  hash: string;
  name: string;
  version: number;
  attributes: { name: string; type: string }[];
  creator: Address;
};

@dataclass(frozen=True, slots=True)
class SchemaAttribute:
    name: str
    type: str

@dataclass(frozen=True, slots=True)
class CredentialSchema:
    hash: str
    name: str
    version: int
    attributes: list[SchemaAttribute]
    creator: Address

pub struct SchemaAttribute {
    pub name: String,
    pub r#type: String,
}

pub struct CredentialSchema {
    pub hash: String,
    pub name: String,
    pub version: u32,
    pub attributes: Vec<SchemaAttribute>,
    pub creator: String,
}

type SchemaAttribute struct {
    Name string `json:"name"`
    Type string `json:"type"`
}

type CredentialSchema struct {
    Hash       string            `json:"hash"`
    Name       string            `json:"name"`
    Version    uint32            `json:"version"`
    Attributes []SchemaAttribute `json:"attributes"`
    Creator    Address           `json:"creator"`
}

public record SchemaAttribute(String name, String type) {}

public record CredentialSchema(
    String hash,
    String name,
    int version,
    List<SchemaAttribute> attributes,
    Address creator
) {}

public sealed record SchemaAttribute(string Name, string Type);

public sealed record CredentialSchema(
    string Hash,
    string Name,
    int Version,
    IReadOnlyList<SchemaAttribute> Attributes,
    Address Creator
);

MultisigWallet¶

A multisig wallet with signers and threshold.

TypeScriptPythonRustGoJavaC#

type MultisigWallet = {
  address: Address;
  signers: Address[];
  threshold: number;
  nonce: number;
};

@dataclass(frozen=True, slots=True)
class MultisigWallet:
    address: Address
    signers: list[Address]
    threshold: int
    nonce: int

pub struct MultisigWallet {
    pub address: String,
    pub signers: Vec<String>,
    pub threshold: u32,
    pub nonce: u64,
}

type MultisigWallet struct {
    Address   Address   `json:"address"`
    Signers   []Address `json:"signers"`
    Threshold uint32    `json:"threshold"`
    Nonce     uint64    `json:"nonce"`
}

public record MultisigWallet(
    Address address,
    List<Address> signers,
    int threshold,
    long nonce
) {}

public sealed record MultisigWallet(
    Address Address,
    IReadOnlyList<Address> Signers,
    int Threshold,
    long Nonce
);

MultisigTx¶

A multisig transaction with approvals and execution status.

TypeScriptPythonRustGoJavaC#

type MultisigTx = {
  id: string;
  wallet: Address;
  to: Address;
  value: TokenAmount;
  data?: string;
  approvals: Address[];
  executed: boolean;
  txHash?: TxHash;
};

@dataclass(frozen=True, slots=True)
class MultisigTx:
    id: str
    wallet: Address
    to: Address
    value: TokenAmount
    data: str | None
    approvals: list[Address]
    executed: bool
    tx_hash: TxHash | None = None

pub struct MultisigTx {
    pub id: String,
    pub wallet: String,
    pub to: String,
    pub value: u64,
    pub data: Option<String>,
    pub approvals: Vec<String>,
    pub executed: bool,
    pub tx_hash: Option<String>,
}

type MultisigTx struct {
    ID        string    `json:"id"`
    Wallet    Address   `json:"wallet"`
    To        Address   `json:"to"`
    Value     *big.Int  `json:"value"`
    Data      *string   `json:"data,omitempty"`
    Approvals []Address `json:"approvals"`
    Executed  bool      `json:"executed"`
    TxHash    *TxHash   `json:"tx_hash,omitempty"`
}

public record MultisigTx(
    String id,
    Address wallet,
    Address to,
    TokenAmount value,
    String data,
    List<Address> approvals,
    boolean executed,
    TxHash txHash
) {}

public sealed record MultisigTx(
    string Id,
    Address Wallet,
    Address To,
    TokenAmount Value,
    string? Data,
    IReadOnlyList<Address> Approvals,
    bool Executed,
    TxHash? TxHash
);

Error Types¶

v0.3.0 introduces a structured exception/error hierarchy across all SDKs.

TypeScriptPythonGoJavaC#

class DilithiaError extends Error { }
class RpcError extends DilithiaError { code: number; data?: unknown; }
class HttpError extends DilithiaError { status: number; }
class TimeoutError extends DilithiaError { }

class DilithiaError(Exception): ...
class RpcError(DilithiaError): code: int; data: Any
class HttpError(DilithiaError): status: int
class TimeoutError(DilithiaError): ...

// Error types support errors.Is and errors.As
type DilithiaError struct { Message string }
type RpcError struct { DilithiaError; Code int; Data any }
type HttpError struct { DilithiaError; Status int }
type TimeoutError struct { DilithiaError }

public class DilithiaException extends RuntimeException { }
public class RpcException extends DilithiaException { int code; }
public class HttpException extends DilithiaException { int status; }
public class TimeoutException extends DilithiaException { }

public class DilithiaException : Exception { }
public class HttpException : DilithiaException { public int StatusCode { get; } public string Body { get; } }
public class RpcException : DilithiaException { public int Code { get; } public string RpcMessage { get; } }
public class DilithiaTimeoutException : DilithiaException { public string Operation { get; } }

DilithiaAccount¶

Represents a fully resolved account with keys, address, and optional wallet file.

TypeScriptPythonRustGoJavaC#

type DilithiaAccount = {
  address: Address;
  publicKey: PublicKey;
  secretKey: SecretKey;
  accountIndex: number;
  walletFile?: WalletFile | null;
};

@dataclass(slots=True)
class DilithiaAccount:
    address: Address
    public_key: PublicKey
    secret_key: SecretKey
    account_index: int
    wallet_file: WalletFile | None = None

pub struct DilithiaAccount {
    pub address: String,
    pub public_key: String,
    pub secret_key: String,
    pub account_index: u32,
    pub wallet_file: Option<serde_json::Value>,
}

type DilithiaAccount struct {
    Address      Address                `json:"address"`
    PublicKey    PublicKey              `json:"public_key"`
    SecretKey    SecretKey              `json:"secret_key"`
    AccountIndex uint32                 `json:"account_index"`
    WalletFile   map[string]interface{} `json:"wallet_file,omitempty"`
}

public record DilithiaAccount(
    Address address,
    PublicKey publicKey,
    SecretKey secretKey,
    int accountIndex,
    Map<String, Object> walletFile
) {}

public sealed record DilithiaAccount(
    Address Address,
    PublicKey PublicKey,
    SecretKey SecretKey,
    int AccountIndex,
    Dictionary<string, object>? WalletFile
);

Fields¶

Field	Type	Description
`address`	`string`	The Dilithia address derived from the public key
`publicKey`	`string`	Hex-encoded ML-DSA-65 public key
`secretKey`	`string`	Hex-encoded ML-DSA-65 secret key
`accountIndex`	`uint`	HD derivation index (0 for root account)
`walletFile`	`WalletFile?`	Optional encrypted wallet file data, present when created with a password

Warning

The secretKey field contains sensitive key material. Never log, transmit, or persist it without encryption.

DilithiaSignature¶

Represents a cryptographic signature produced by signMessage.

TypeScriptPythonRustGoJavaC#

type DilithiaSignature = {
  algorithm: string;
  signature: string;
};

@dataclass(slots=True)
class DilithiaSignature:
    algorithm: str
    signature: str

pub struct DilithiaSignature {
    pub algorithm: String,
    pub signature: String,
}

type DilithiaSignature struct {
    Algorithm string `json:"algorithm"`
    Signature string `json:"signature"`
}

public record DilithiaSignature(
    String algorithm,
    String signature
) {}

public sealed record DilithiaSignature(string Algorithm, string Signature);

Fields¶

Field	Type	Description
`algorithm`	`string`	The signing algorithm identifier, always `"mldsa65"`
`signature`	`string`	Hex-encoded signature bytes

DilithiaKeypair¶

Represents a keypair generated by keygen or keygenFromSeed.

TypeScriptPythonRustGoJavaC#

type DilithiaKeypair = {
  secretKey: SecretKey;
  publicKey: PublicKey;
  address: Address;
};

@dataclass(slots=True)
class DilithiaKeypair:
    secret_key: SecretKey
    public_key: PublicKey
    address: Address

pub struct DilithiaKeypair {
    pub secret_key: String,
    pub public_key: String,
    pub address: String,
}

type DilithiaKeypair struct {
    SecretKey SecretKey `json:"secret_key"`
    PublicKey PublicKey `json:"public_key"`
    Address   Address  `json:"address"`
}

public record DilithiaKeypair(
    SecretKey secretKey,
    PublicKey publicKey,
    Address address
) {}

public sealed record DilithiaKeypair(SecretKey SecretKey, PublicKey PublicKey, Address Address);

Fields¶

Field	Type	Description
`secretKey`	`string`	Hex-encoded ML-DSA-65 secret key
`publicKey`	`string`	Hex-encoded ML-DSA-65 public key
`address`	`string`	Dilithia address derived from the public key

WalletFile¶

An encrypted wallet file containing a protected secret key. This is a generic dictionary/map -- the structure is defined by dilithia-core and may vary by version.

TypeScriptPythonRustGoJavaC#

type WalletFile = Record<string, unknown>;

WalletFile = dict[str, Any]

// Represented as serde_json::Value or dilithia_core::wallet::WalletFile

type WalletFile map[string]interface{}

// Represented as Map<String, Object>

// Represented as Dictionary<string, object>

Known Fields¶

The wallet file typically contains these fields, though implementations should treat it as opaque when possible:

Field	Type	Description
`version`	`int`	Wallet format version (currently `1`)
`address`	`string`	The account address
`public_key`	`string`	Hex-encoded public key
`encrypted_sk`	`string`	Encrypted secret key (hex-encoded ciphertext)
`nonce`	`string`	Encryption nonce (hex)
`tag`	`string`	Authentication tag (hex)
`account_index`	`int?`	HD derivation index, if applicable

Note

The wallet file is designed to be serialized as JSON and stored on disk. It can be recovered later using recoverWalletFile with the original mnemonic and password.

DeployPayload¶

Represents the full payload for deploying or upgrading a WASM smart contract. Includes the bytecode, deployer identity, cryptographic signature, and chain metadata.

TypeScriptPythonRustGoJavaC#

type DeployPayload = {
  name: string;
  bytecode: string;
  from: string;
  alg: string;
  pk: string;
  sig: string;
  nonce: number;
  chainId: string;
  version?: number;
};

# Represented as a plain dict built by deploy_contract_body()
deploy_body: dict[str, Any] = {
    "name": str,
    "bytecode": str,
    "from": str,
    "alg": str,
    "pk": str,
    "sig": str,
    "nonce": int,
    "chain_id": str,
    "version": int,  # default 1
}

pub struct DeployPayload {
    pub name: String,
    pub bytecode: String,
    pub from: String,
    pub alg: String,
    pub pk: String,
    pub sig: String,
    pub nonce: u64,
    pub chain_id: String,
    pub version: u8,
}

type DeployPayload struct {
    Name     string `json:"name"`
    Bytecode string `json:"bytecode"`
    From     string `json:"from"`
    Alg      string `json:"alg"`
    PK       string `json:"pk"`
    Sig      string `json:"sig"`
    Nonce    uint64 `json:"nonce"`
    ChainID  string `json:"chain_id"`
    Version  uint8  `json:"version"`
}

public record DeployPayload(
    String name,
    String bytecode,
    String from,
    String alg,
    String pk,
    String sig,
    long nonce,
    String chainId,
    int version
) {}

public sealed record DeployPayload(
    string Name,
    string Bytecode,
    string From,
    string Alg,
    string Pk,
    string Sig,
    long Nonce,
    string ChainId,
    int Version = 1
);

Fields¶

Field	Type	Description
`name`	`string`	Contract name (used as the on-chain identifier)
`bytecode`	`string`	Hex-encoded WASM bytecode
`from`	`string`	Deployer's Dilithia address
`alg`	`string`	Signing algorithm identifier (e.g. `"mldsa65"`)
`pk`	`string`	Hex-encoded public key of the deployer
`sig`	`string`	Hex-encoded signature over the canonical deploy payload
`nonce`	`uint64`	Account nonce at time of deployment
`chainId`	`string`	Target chain identifier (e.g. `"dilithia-mainnet"`)
`version`	`uint8`	Contract version number (default `1`)

Note

The sig field is produced by signing the canonical payload returned by buildDeployCanonicalPayload. The canonical payload contains a hash of the bytecode (not the bytecode itself) to keep the signed message small.

DilithiaClientConfig¶

Configuration for creating a DilithiaClient instance.

TypeScriptPythonRustC#

type DilithiaClientConfig = {
  rpcUrl: string;
  timeoutMs?: number;
  chainBaseUrl?: string;
  indexerUrl?: string;
  oracleUrl?: string;
  wsUrl?: string;
  jwt?: string;
  headers?: Record<string, string>;
};

# Passed as keyword arguments to DilithiaClient.__init__
DilithiaClient(
    rpc_url: str,
    timeout: float = 10.0,
    *,
    chain_base_url: str | None = None,
    indexer_url: str | None = None,
    oracle_url: str | None = None,
    ws_url: str | None = None,
    jwt: str | None = None,
    headers: dict[str, str] | None = None,
)

pub struct DilithiaClientConfig {
    pub rpc_url: String,
    pub chain_base_url: Option<String>,
    pub indexer_url: Option<String>,
    pub oracle_url: Option<String>,
    pub ws_url: Option<String>,
    pub jwt: Option<String>,
    pub headers: Vec<(String, String)>,
    pub timeout_ms: Option<u64>,
}

// Configured via the builder pattern
using var client = DilithiaClient.Create("https://rpc.dilithia.network/rpc")
    .WithTimeout(TimeSpan.FromSeconds(15))
    .WithJwt("my-bearer-token")
    .WithHeader("x-custom", "value")
    .Build();

Fields¶

Field	Type	Default	Description
`rpcUrl`	`string`	required	Base URL of the Dilithia RPC endpoint
`timeoutMs`	`number`	`10000`	HTTP request timeout in milliseconds
`chainBaseUrl`	`string?`	derived	Base URL for REST endpoints; derived from `rpcUrl` if omitted
`indexerUrl`	`string?`	`null`	URL of the indexer service
`oracleUrl`	`string?`	`null`	URL of the oracle service
`wsUrl`	`string?`	derived	WebSocket URL; auto-derived from `chainBaseUrl` if omitted
`jwt`	`string?`	`null`	Bearer token for authenticated requests
`headers`	`Record<string,string>`	`{}`	Additional headers to include in every request