Cryptography

This document explains the SDK’s cryptography layer in practical terms, grounded on the headers in include/Cryptography/* and the serialization helpers in include/Utils/*. It is written for engineers who need to generate keys, derive addresses, sign/verify payloads, and serialize/deserialize cryptographic types.

What’s inside

• PrivateKey — secure 32‑byte secret key (guarded reads/writes)

• PhantasmaKeys — convenience holder: private key, public key, and derived address; also provides signing

• Address — canonical on‑chain address with parsing/formatting and validation

• Signature — variant container for signatures (Ed25519 provided by default)

• Hash — 32‑byte hash value with I/O helpers

• (Utils) BinaryReader, BinaryWriter, Serializable, Entropy — used across the types

Include & namespaces

#include "Cryptography/PrivateKey.h"
#include "Cryptography/KeyPair.h"
#include "Cryptography/Address.h"
#include "Cryptography/Signature.h"
#include "Cryptography/Hash.h"
#include "Utils/BinaryReader.h"
#include "Utils/BinaryWriter.h"

using namespace phantasma;

PrivateKey

PrivateKey stores a 32‑byte secret key. The bytes are kept in a secure buffer and can only be accessed via short‑lived reader/writer proxies. Typical flows:

• Generate a random key (recommended: use PhantasmaKeys::Generate())

• Import/export into the secure buffer via Write()/Read() Key members & methods (selection)

• PHANTASMA_EXCEPTION("privateKey should have length 32") → ``

Example — create and access

PrivateKey sk;                   // default-constructed = empty
if (sk.IsNull()) { /* no key material yet */ }

// Fill with strong randomness (low-level)
auto w = sk.Write();             // SecureByteWriter
Byte tmp[PrivateKey::Length];
Entropy::GetRandomBytes(tmp, PrivateKey::Length);
w.Write(tmp, PrivateKey::Length);

// Read back (e.g., for export)
auto r = sk.Read();              // SecureByteReader
Byte out[PrivateKey::Length];
r.Read(out, PrivateKey::Length);

PhantasmaKeys

PhantasmaKeys bundles a private key, the corresponding public key bytes, and the derived Address. It also provides message signing helpers. Public API (selection)

Example — generate, inspect, sign

PhantasmaKeys keys = PhantasmaKeys::Generate();
const PrivateKey& sk = keys.GetPrivateKey();
const ByteArray&  pk = keys.GetPublicKey();
const Address&    addr = keys.GetAddress();

// Produce an Ed25519 signature over arbitrary bytes
ByteArray msg = /* ... */;
Ed25519Signature sig = keys.Sign(msg.data(), (int)msg.size());

Address

Address represents an on‑chain account address. It supports deriving from a public key, parsing from text, validating, and converting to string. Public API (selection)

Example — parse and derive

Address a = Address::FromText("P2K...");  // parse from base58 form
bool ok = a.IsValid();
String text = a.ToString();

// From PhantasmaKeys / public key
Address b = Address::FromKey(keys);

Signature (Ed25519)

Signature is a serializable container that can hold an Ed25519 signature. Verification checks the signature against one or more allowed addresses (derived from public keys). Public API (selection)

Example — verify

const Address allowed[] = { keys.GetAddress() };
bool ok = sig.Verify(message.data(), (int)message.size(), allowed, 1);

Hash

Hash encapsulates a 32‑byte hash with helpers to construct from bytes and to print/compare/serialize. Public API (selection)

Example

Hash h = Hash::FromBytes(bytes, len);
String s = h.ToString(); // typically base16 (hex)

Recipes

Sign & verify an arbitrary message

PhantasmaKeys keys = PhantasmaKeys::Generate();

ByteArray msg = /* your bytes */;
Ed25519Signature sig = keys.Sign(msg.data(), (int)msg.size());

const Address allowed[] = { keys.GetAddress() };
bool ok = sig.Verify(msg.data(), (int)msg.size(), allowed, 1);

Sign a transaction (end-to-end)

// Build a transaction first (see Transaction docs)
Transaction tx("main", "chain", scriptBytes, Timestamp::Now()+Timespan::FromMinutes(5));

// Append your Ed25519 signature. The SDK signs the bytes of ToByteArray(false):
tx.Sign(keys);

// Broadcast (see High-Level API / Workflows)

Serialize / deserialize a signature

BinaryWriter w;
sig.SerializeData(w);
ByteArray raw = w.ToArray();

BinaryReader r(raw);
Signature sig2;
sig2.UnserializeData(r);