Transactions
A transaction is the atomic unit of change on ULedger. Every mutation to chain state - creating a wallet, invoking a contract, transferring tokens, updating an entity - is a signed transaction.
Transaction Structure
| Field | Description |
|---|---|
type | The transaction type (e.g., CREATE_WALLET, INVOKE_SMART_CONTRACT). Determines which processor handles it. |
sender | The wallet address submitting the transaction. |
signature | Cryptographic signature over the payload using the sender's private key. |
payload | Type-specific fields (contract address, function name, args, token amount, etc.). |
Lifecycle
CONSTRUCT SDK builds payload (type, fields, sender address)
SIGN SDK signs payload with sender private key
SUBMIT HTTP POST to any node → pending pool
GOSSIP Node broadcasts to peers via GossipSub (libp2p)
VALIDATE Authorization checks run during block proposal
EXECUTE Block processor executes: updates wallets, entities, contracts
COMMIT Block finalized, state written to BadgerDB + sidecar files
CONFIRM SDK polls for receipt, cross-node consistency verified
Authorization checks (steps VALIDATE and EXECUTE):
- Sender's entity ancestry chain must be fully enabled.
- Target entity's governing chain honors blacklists.
- Capability-restricted wallets are checked against held capabilities.
- Capability expiry is evaluated at execution time (block height comparison).
Transaction Categories
ULedger supports 60+ transaction types across these domains:
| Domain | Examples |
|---|---|
| Wallet management | CREATE_WALLET, ALTER_WALLET |
| Entity management | CREATE_ENTITY, ALTER_ENTITY, LINK_WALLET_TO_ENTITY |
| Smart contracts | DEPLOY_CONTRACT, INVOKE_SMART_CONTRACT |
| Tokens | MINT_TOKEN, TRANSFER_TOKEN, BURN_TOKEN |
| Identity | CREATE_DID, ISSUE_CREDENTIAL, REVOKE_CREDENTIAL |
| Recovery | CONFIGURE_ENTITY_RECOVERY, APPROVE_ENTITY_RECOVERY |
| Data | DATA_TX (arbitrary payload anchored on-chain) |
| Council governance | ADD_COUNCIL_MEMBER, FINALIZE_PROPOSAL |
Immutability
Once a transaction is committed to a finalized block it cannot be altered or deleted. The block is:
- Merkle-chained to the preceding block.
- Included in the Helix STARK checkpoint proof for its epoch.
- Replicated across every node in the council.
Any attempt to alter the record invalidates both the Merkle chain and the STARK proof.
Detailed References
- Transaction Types reference - complete catalog with all fields and processing rules
- Go SDK transaction operations
- Architecture: Transaction Lifecycle