Transaction Types Reference

All state changes on ULedger are effected through signed transactions. This document catalogs every transaction type, its required fields, who can submit it, and what it does.

Every transaction shares a common envelope:

{
    "type": "<TRANSACTION_TYPE>",
    "sender": "<wallet-address>",
    "blockchainId": "<chain-id>",
    "signature": "<hex-signature-of-payload>",
    "payload": { ... }
}

Wallet Transactions

`TX_CREATE_WALLET`

Creates a new wallet on-chain.

Field	Type	Description
`publicKey`	string	Compressed hex public key of the new wallet.
`keyType`	string	Key algorithm: `secp256k1`, `ed25519`, `mldsa87`, `bls12377`.
`authGroups`	map	`{ "admin": {...}, "wallet": {...} }` with CRUD booleans.
`capabilities`	array	Optional initial capabilities (must be ⊆ parent's capabilities).

Who can submit: Any registered wallet with wallet.Create == true in its auth groups. The submitting wallet becomes the new wallet's Parent.

Processing rules:

Derive new wallet address as SHA256(lowercase(publicKey)).
Validate parent exists and has CanCreateWallets() permission.
Validate capability inheritance (child caps ⊆ parent caps).
Create wallet, set Parent = sender.
Add new wallet address to sender's SatelliteWallets array.

`ALTER_WALLET`

Modifies an existing wallet: enable/disable, update auth groups, update capabilities.

Field	Type	Description
`walletAddress`	string	Address of the wallet to alter.
`enabled`	bool	Enable or disable the wallet.
`authGroups`	map	Replacement auth groups (optional).
`capabilities`	array	Replacement capabilities (optional).

Who can submit: The wallet's parent, or any wallet with admin authority over the wallet.

Processing rules for disable: BFS cascade: all wallets in SatelliteWallets (recursively) are also disabled. This is atomic.

Processing rules for capabilities: Replacement must be a subset of the parent wallet's capabilities.

Entity Transactions

`CREATE_ENTITY`

Creates a new organizational entity.

Field	Type	Description
`name`	string	3–64 chars, lowercase, alphanumeric + dash.
`entityType`	string	`ORGANIZATION`, `DEPARTMENT`, `PERSONAL`, `SERVICE`, `DEVICE`, `AGENT`.
`parent`	string	Parent entity address (empty for root).
`metadata`	map	Optional key-value metadata.

Who can submit: For root entity: a root wallet (wallet.Parent == ""). For child entity: a wallet with ManageChildren == true on the parent entity.

Processing rules:

Parent must exist, be enabled, and support the requested child type.
Root wallet creating a root entity must not already have a wallet.Entity affiliation.
Sender becomes entity owner; auto-linked as admin-role with full permissions.
wallet.Entity backlink set on the creating wallet.

`ALTER_ENTITY`

Updates entity metadata or enabled state.

Field	Type	Description
`entityAddress`	string	Entity to alter.
`metadata`	map	Replacement or merged metadata.
`enabled`	bool	Enable or disable the entity.

Who can submit: Wallet with ManageMetadata == true (for metadata) or entity owner (for enable/disable).

`TRANSFER_ENTITY`

Changes the entity owner to a new wallet.

Field	Type	Description
`entityAddress`	string	Entity to transfer.
`newOwnerAddress`	string	Address of the new owner wallet.

Who can submit: Any wallet with TransferOwnership == true on the entity.

Processing rules: Old owner's wallet.Entity backlink is cleared; new owner's backlink is set.

`LINK_WALLET_TO_ENTITY`

Links a wallet to an entity with a role and permission set.

Field	Type	Description
`entityAddress`	string	Entity to link to.
`walletAddress`	string	Wallet to link.
`role`	string	`"admin"` or `"member"` (stored, not consulted for auth).
`permissions`	object	`EntityPermission` bits.

Who can submit: Wallet with ManageWallets == true on the entity.

Processing rules: If role == "admin", sets wallet.Entity backlink on the linked wallet.

`UNLINK_WALLET_FROM_ENTITY`

Removes a wallet from an entity's member list.

Field	Type	Description
`entityAddress`	string	Entity to unlink from.
`walletAddress`	string	Wallet to remove.

Who can submit: Wallet with ManageWallets == true on the entity.

`SET_ENTITY_ACCESS_LIST`

Modifies the entity's blacklist or trusted list.

Field	Type	Description
`entityAddress`	string	Entity whose access list to modify.
`operation`	string	`ADD_BLACKLIST`, `REMOVE_BLACKLIST`, `ADD_TRUSTED`, `REMOVE_TRUSTED`.
`targetAddress`	string	Wallet address to add or remove.

Who can submit: Wallet with ManageAccessList == true on the entity.

Entity Recovery Transactions

`CONFIGURE_ENTITY_RECOVERY`

Sets the recovery wallet configuration for an entity.

Field	Type	Description
`entityAddress`	string	Entity to configure.
`recoveryWallets`	array	Wallet addresses authorized to approve recovery.
`threshold`	int	Number of approvals required to execute recovery.

Who can submit: Entity owner only.

Processing rules: Staged as PendingRecoveryConfig with a delay period before activation.

`REQUEST_ENTITY_RECOVERY`

Initiates a recovery process for an entity.

Field	Type	Description
`entityAddress`	string	Entity to recover.
`newOwnerAddress`	string	Proposed new owner wallet.

Who can submit: Any wallet. (The recovery wallets must then approve.)

`APPROVE_ENTITY_RECOVERY`

Casts an approval vote on an in-progress recovery.

Field	Type	Description
`entityAddress`	string	Entity under recovery.

Who can submit: A wallet in the entity's RecoveryConfig.recoveryWallets list.

`EXECUTE_ENTITY_RECOVERY`

Executes a recovery after the threshold of approvals is met.

Field	Type	Description
`entityAddress`	string	Entity to recover.

Who can submit: Any wallet (after threshold is met).

Processing rules: Entity owner changes to the newOwnerAddress from the recovery request. Old owner's backlink cleared; new owner's backlink set.

`CANCEL_ENTITY_RECOVERY`

Cancels an in-progress recovery.

Field	Type	Description
`entityAddress`	string	Entity whose recovery to cancel.

Who can submit: Entity owner or recovery wallets.

Smart Contract Transactions

`DEPLOY_SMART_CONTRACT`

Deploys a new WASM contract.

Field	Type	Description
`sourceCode`	bytes	WASM binary (or WAT text).
`gasLimit`	uint64	Gas budget for deployment execution.
`isUpgradeable`	bool	Whether the contract can be upgraded.
`governanceMode`	string	Optional governance mode label.

Who can submit: Any registered wallet.

Processing rules: Contract address = transaction ID. Owner = deploying wallet. Version = 1.

`INVOKE_SMART_CONTRACT`

Calls a function in a deployed contract.

Field	Type	Description
`contractAddress`	string	Target contract address.
`function`	string	Function name to call.
`args`	array	Function arguments.
`gasLimit`	uint64	Gas budget for execution.

Who can submit: Any wallet with a valid contract:invoke capability (or any wallet if no capabilities are set on the chain).

Processing rules: Execution is sandboxed. Storage changes are rolled back on failure. Gas is consumed regardless of success.

`UPGRADE_SMART_CONTRACT`

Replaces a contract's bytecode.

Field	Type	Description
`contractAddress`	string	Contract to upgrade.
`sourceCode`	bytes	New WASM binary.
`gasLimit`	uint64	Gas budget.

Who can submit: Contract owner (or wallet with upgrade permission). Contract must have IsUpgradeable == true.

Processing rules: PreviousVersion = current version. Version incremented. Old bytecode preserved for rollback.

`ROLLBACK_SMART_CONTRACT`

Reverts a contract to its previous bytecode version.

Field	Type	Description
`contractAddress`	string	Contract to roll back.

Who can submit: Contract owner.

Processing rules: Version decremented. Bytecode restored to PreviousVersion state.

Token Transactions (Native)

Fungible Token (ERC-20 equivalent)

Transaction	Description
`CREATE_TOKEN`	Deploy a new fungible token. Fields: `name`, `symbol`, `decimals`, `initialSupply`.
`MINT_TOKEN`	Mint new supply. Fields: `tokenAddress`, `amount`, `recipient`. Owner-only.
`BURN_TOKEN`	Burn supply. Fields: `tokenAddress`, `amount`. Holder only.
`TRANSFER_TOKEN`	Transfer tokens. Fields: `tokenAddress`, `recipient`, `amount`.
`APPROVE_TOKEN`	Approve a spender. Fields: `tokenAddress`, `spender`, `amount`.
`TRANSFER_FROM_TOKEN`	Spender transfers on behalf of approver. Fields: `tokenAddress`, `from`, `to`, `amount`.

Non-Fungible Token (ERC-721 equivalent)

Transaction	Description
`MINT_NFT`	Mint a single NFT. Fields: `collectionAddress`, `tokenId`, `metadata`.
`TRANSFER_NFT`	Transfer NFT ownership. Fields: `collectionAddress`, `tokenId`, `recipient`.
`APPROVE_NFT`	Approve a spender for a specific NFT.
`SET_APPROVAL_FOR_ALL`	Approve an operator for all NFTs in a collection.

Multi-Token (ERC-1155 equivalent)

Transaction	Description
`MINT_MULTI_TOKEN`	Mint multiple token types in one transaction.
`TRANSFER_MULTI_TOKEN`	Batch transfer multiple token types.
`CONVERT_TOKEN`	Convert a fungible token balance into a non-fungible token.

Data and System Transactions

`TX_DATA`

Submits arbitrary data to the chain. Used for:

Recording off-chain events with an on-chain timestamp and signature.
Submitting data blobs whose hash must be provable.
Driving block production (no-op data transactions advance chain height for testing).

Field	Type	Description
`payload`	bytes	Arbitrary data (up to 64 KiB).

Who can submit: Any wallet with data:submit capability (or no capability restriction).

Processing rules: Payload is stored in the transaction record. No state changes are made beyond recording the transaction.

`CHECKPOINT_MARKER`

System transaction written by the Helix sidecar when a STARK checkpoint is finalized.

Not submitted by users or agents. Written by the Helix sidecar process. Marks the block at which a checkpoint proof was anchored. The embedded proof is verifiable by the checkpoint_verify tool.

Authentication Transactions

`AUTHENTICATE_INTERNAL`

Authenticates a wallet using an on-chain challenge-response flow. Used to prove control of a wallet without submitting a state-changing transaction.

`AUTHENTICATE_EXTERNAL`

Extends external credentials (off-chain identities) by anchoring them to an on-chain authentication event.

Wallet Transactions​

TX_CREATE_WALLET​

ALTER_WALLET​

Entity Transactions​

CREATE_ENTITY​

ALTER_ENTITY​

TRANSFER_ENTITY​

LINK_WALLET_TO_ENTITY​

UNLINK_WALLET_FROM_ENTITY​

SET_ENTITY_ACCESS_LIST​

Entity Recovery Transactions​

CONFIGURE_ENTITY_RECOVERY​

REQUEST_ENTITY_RECOVERY​

APPROVE_ENTITY_RECOVERY​

EXECUTE_ENTITY_RECOVERY​

CANCEL_ENTITY_RECOVERY​

Smart Contract Transactions​

DEPLOY_SMART_CONTRACT​

INVOKE_SMART_CONTRACT​

UPGRADE_SMART_CONTRACT​

ROLLBACK_SMART_CONTRACT​

Token Transactions (Native)​

Fungible Token (ERC-20 equivalent)​

Non-Fungible Token (ERC-721 equivalent)​

Multi-Token (ERC-1155 equivalent)​

Data and System Transactions​

TX_DATA​

CHECKPOINT_MARKER​

Authentication Transactions​

AUTHENTICATE_INTERNAL​

AUTHENTICATE_EXTERNAL​