Vexidus Keypair and Recovery Reference

Keypair Generation (Server-Side)

RPC Method: vex_generateKeypair

Generates an Ed25519 keypair:

curl -X POST https://testnet.vexidus.io -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"vex_generateKeypair","params":[],"id":1}'

Returns:

{
  "address": "Vx0...",
  "public_key": "<64 hex chars>",
  "secret_key": "<64 hex chars>",
  "key_type": "Ed25519"
}

How It Works

1. An Ed25519 signing key (32 bytes) and verifying key (32 bytes) are generated
2. Address derived: SHA256(public_key) -> 32 bytes -> base58 with Vx0 prefix
3. EVM-compatible address: last 20 bytes of the 32-byte address -> 0x hex

Dual Key Types

Vexidus accounts support two signature schemes, giving every account a clear path to post-quantum security:

Type	Pubkey Size	Signature Size	Role
Ed25519	32 bytes	64 bytes	Fast, compatible classical signatures used for everyday signing
Dilithium3 (NIST Level 3)	1,952 bytes	3,293 bytes	Post-quantum signatures for long-term quantum hardening

Signature Verification

Current Pipeline

1. Bundle signing: The client signs the Blake3 hash of the bundle with its Ed25519 secret key
2. Verification: During execution, the network:
   • Checks the account's registered signing keys for one authorized to sign transactions
   • Accepts either an Ed25519 (64-byte) or Dilithium3 (3,293-byte) signature
   • Pubkey revelation: The first signed send from a receive-only account includes the sender's public key. The network confirms the key hashes to the account address and registers it for future sends.

Pre-Signed Bundle Submission

curl -X POST https://testnet.vexidus.io -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"vex_submitBundle","params":["<borsh_hex>"],"id":1}'

Guardian Recovery (VSA v2)

Status: Fully Implemented

Guardian recovery is live as a set of native account operations.

Setup

An account owner configures recovery by specifying:

• Guardians -- up to 10 trusted Vx0 addresses
• Threshold -- the M-of-N guardian approvals required to recover
• Timelock -- a delay before recovery can finalize (recommended: 48-72 hours)

Recovery Flow

1. User loses all keys
2. Guardians initiate: M-of-N guardians submit InitiateRecovery with a new public key
3. Timelock starts: The pending recovery is recorded on the account
4. Owner can cancel: If they regain access during the timelock, submit CancelRecovery
5. After timelock: Anyone submits FinalizeRecovery -- replaces all account keys with the recovery key

Operations

Operation	Who Signs	What Happens
SetRecovery	Account owner	Configures guardians, threshold, timelock
InitiateRecovery	Guardian	Starts recovery with new pubkey, records guardian approval
CancelRecovery	Account owner	Cancels pending recovery
FinalizeRecovery	Anyone	After timelock, replaces keys. Requires threshold guardian approvals.

Recovery State

Each account's recovery configuration tracks its guardian set, the approval threshold, the timelock duration, and any in-progress recovery. A pending recovery records the proposed new public key and key type, when it was initiated, and which guardians have approved so far.

Key Management (Also Live)

Operation	Purpose
AddKey	Add an Ed25519 or Dilithium3 key to an account
RemoveKey	Remove a key (must keep at least one)
RotateKey	Atomic swap of one key for another

Quantum Migration Path

• Phase 1 (Now): Ed25519 only. Wallet SDK compatible (Phantom, MetaMask via bridge).
• Phase 2 (~2028): Users add Dilithium3 key alongside Ed25519 via AddKey. Either key signs. Address unchanged.
• Phase 3 (~2032+): High-value ops require Dilithium3. V0-only accounts get warnings.

The infrastructure is ready -- post-quantum key generation works and signature verification already handles both Ed25519 and Dilithium3 signatures, so the migration requires no protocol upgrade.

Security Best Practices

Key Storage

• Store wallet keys with chmod 600
• Never log or print secret keys in production
• Store backups encrypted on offline media
• For web wallets, use the browser's SubtleCrypto API to encrypt keys at rest

Nonce Management

• Nonces are sequential: transaction with nonce=5 only executes after nonce=4
• Always fetch the current nonce immediately before signing
• If a transaction fails, the nonce is not consumed -- retry with the same nonce

Testnet vs Mainnet

Behavior	Testnet	Mainnet
Chain ID	1618032	1618033
vex_generateKeypair	Available	Disabled

Never reuse testnet keys on mainnet. Generate fresh keypairs for production.