ULedgerNET Wallet System

Overview

ULedgerNET implements a hierarchical wallet system that supports parent-child relationships, permission-based access control, and cascading wallet management. This architecture enables enterprise-grade identity management while maintaining cryptographic security.

Wallet Architecture

Hierarchical Structure

🔍 click to expand

Wallet Types

Type	Description	Parent Field
Parent Wallet	Root-level wallet with no parent	Empty
Child Wallet	Created by a parent wallet	Parent's address
Satellite Wallet	Term for any descendant wallet	Tracked by parent

Wallet Structure

Core Properties

🔍 click to expand

Property Details

Property	Type	Description
publicKey	string	The wallet's public key (hex-encoded)
address	string	SHA256 hash of the lowercase public key
parent	string	Address of parent wallet (empty for root wallets)
enabled	boolean	Whether the wallet can transact
satelliteWallets	string[]	List of child wallet addresses
authGroups	map	Permission groups for access control
keyType	enum	Cryptographic algorithm (secp256k1, ED25519, BLS12-377, ML-DSA-87)

Permission System

Authorization Groups

ULedgerNET uses a flexible permission system based on authorization groups:

🔍 click to expand

Permission Structure

Each authorization group contains CRUD permissions:

Permission	Description
Create	Create new entries of this type
Read	Read existing entries
Update	Modify existing entries
Delete	Remove entries

Built-in Groups

Group	Purpose
admin	Full administrative access (all CRUD on all resources)
wallet	Wallet management permissions (create, update child wallets)

Admin Check Logic

A wallet is considered an admin if it has the admin group with all four permissions enabled:

🔍 click to expand

Wallet Operations

Creating Wallets

🔍 click to expand

Transaction Payload: Create Wallet

Field	Type	Required	Description
publicKey	string	Yes	Public key for the new wallet
keyType	enum	Yes	Cryptographic key type
authGroups	map	No	Initial permissions for the wallet

Parent Wallet Requirements

For creating a child wallet, the parent must:

1. Exist in the blockchain
2. Be enabled (not disabled)
3. Have permission - either:
   • Be an admin (admin group with full CRUD)
   • Have wallet group with create permission

Wallet Alteration

Alter Wallet Operation

🔍 click to expand

Transaction Payload: Alter Wallet

Field	Type	Required	Description
target	string	Yes	Address of wallet to modify
enabled	boolean	Yes	New enabled status
authGroups	map	No	Updated permissions

Authorization Rules

Scenario	Required Authorization
Parent altering child	Parent must have wallet.update or be admin
Wallet altering itself	Must have wallet.update or be admin
No parent exists	Only the wallet itself can alter

Cascading Disable

Automatic Child Disabling

When a parent wallet is disabled, all descendant wallets are automatically disabled:

🔍 click to expand

Cascade Algorithm

🔍 click to expand

This ensures that:

• No orphaned child wallets remain active
• Enterprise account suspension cascades properly
• Security revocation is comprehensive

Transaction Validation

Pre-Validation Checks

Before processing, transactions are validated against pending transactions:

🔍 click to expand

Validation Requirements

Check	Description
Wallet Exists	Target wallet must exist (for alter)
Wallet Enabled	Wallet must be enabled to transact
Key Type Match	Transaction key type must match wallet
Signature Valid	Cryptographic signature verification
Parent Authorization	Parent must authorize child operations

Wallet Identity

Address Derivation

Wallet addresses are derived deterministically from public keys:

🔍 click to expand

This ensures:

• Consistent address generation across nodes
• No possibility of address collision
• Address can verify public key ownership

Supported Key Types

Key Type	Algorithm	Quantum Safe
secp256k1	ECDSA	❌
ED25519	EdDSA	❌
BLS12-377	BLS Signatures	❌
ML-DSA-87	Dilithium	✅

API Reference

Get Wallet

GET /blockchains/{blockchain_id}/wallets/{address}

Response:

{
  "publicKey": "04a1b2c3...",
  "address": "abc123...",
  "parent": "",
  "enabled": true,
  "satelliteWallets": ["def456...", "ghi789..."],
  "authGroups": {
    "admin": {"create": true, "read": true, "update": true, "delete": true}
  },
  "keyType": 0
}

Create Wallet Transaction

POST /blockchains/{blockchain_id}/transactions

Request Body:

{
  "from": "parent_address",
  "to": "new_wallet_address", 
  "payloadType": "CREATE_WALLET",
  "payload": "{\"publicKey\":\"04abc...\",\"keyType\":0,\"authGroups\":{}}",
  "senderSignature": "signature_hex"
}

Alter Wallet Transaction

POST /blockchains/{blockchain_id}/transactions

Request Body:

{
  "from": "parent_or_self_address",
  "payloadType": "ALTER_WALLET",
  "payload": "{\"target\":\"wallet_address\",\"enabled\":false}",
  "senderSignature": "signature_hex"
}

Enterprise Use Cases

Organizational Hierarchy

🔍 click to expand

Access Revocation

When an employee leaves:

1. Disable the employee's wallet
2. All their child wallets are automatically disabled
3. No further transactions can be initiated
4. Existing confirmed transactions remain on-chain

Department Management

• Department heads can create wallets for their teams
• Team leads can create wallets for team members
• Each level has appropriate permissions

Security Considerations

Key Management

Practice	Recommendation
Root Wallets	Use HSM or secure key storage
Key Rotation	Create new child wallet, disable old
Backup	Secure backup of private keys
Access Logs	Monitor wallet operations

Permission Best Practices

Practice	Recommendation
Least Privilege	Grant minimum required permissions
Admin Sparingly	Limit admin group assignment
Hierarchy Depth	Keep hierarchy manageable
Regular Audits	Review wallet permissions periodically

Disabled Wallet Behavior

• Disabled wallets cannot submit transactions
• Disabled wallets cannot sign for child operations
• Existing transactions remain valid
• Re-enabling requires parent authorization

---

End of Technical Documentation Series