Shogun Documentation

Shogun is a client-side Ethereum wallet that uses username and password. This documentation provides a complete overview of the available APIs.

👛 WalletManager

Main class for wallet management and authentication.

Constructor

constructor(options?: { peers?: string[]; localStorage?: boolean; radisk?: boolean; gun?: Gun; })

Creates a new WalletManager instance.

peers: Array of Gun peer URLs (default: predefined peers)
localStorage: Enable/disable localStorage (default: false)
radisk: Enable/disable radisk storage (default: false)
gun: Existing Gun instance to use

Account Methods

createAccount

async createAccount(alias: string, passphrase: string, callback?: (error?: Error) => void): Promise<void>

Creates a new GunDB account.

alias: Account username
passphrase: Account password
callback: Optional callback for error handling

login

async login(alias: string, passphrase: string): Promise<string>

Performs login with specified credentials.

Returns: Public key of authenticated user

Wallet Management

saveWallet

async saveWallet(wallet: Wallet, publicKey: string, storageType?: StorageType): Promise<void>

Saves a wallet to specified storage.

retrieveWallets

async retrieveWallets(publicKey: string): Promise<Wallet[]>

Retrieves all wallets from Gun.

logout

logout(): void

Logs out current user.

loginWithPrivateKey

async loginWithPrivateKey(privateKey: string): Promise<string>

Performs login using an Ethereum private key.

privateKey: Ethereum private key
Returns: Account public key

saveWalletToGun

async saveWalletToGun(wallet: Wallet, publicKey: string): Promise<void>

Saves a wallet to Gun.

wallet: Wallet to save
publicKey: Associated public key

retrieveWalletLocally

async retrieveWalletLocally(publicKey: string): Promise<Wallet | null>

Retrieves a wallet from localStorage.

publicKey: User's public key
Returns: Found wallet or null

deleteWallet

async deleteWallet(publicKey: string, walletAddress: string): Promise<void>

Deletes a specific wallet.

publicKey: User's public key
walletAddress: Address of wallet to delete

convertToEthPk

async convertToEthPk(gunPrivateKey: string): Promise<string>

Converts a Gun private key to Ethereum format.

gunPrivateKey: Gun private key in base64Url format
Returns: Private key in hex format

createWalletObj

static async createWalletObj(gunKeyPair: GunKeyPair): Promise<WalletResult>

Creates a new wallet from a Gun key pair.

gunKeyPair: Gun key pair
Returns: Object containing wallet and entropy

createWalletFromSalt

static async createWalletFromSalt(gunKeyPair: GunKeyPair, salt: string): Promise<Wallet>

Creates a wallet from salt and Gun key pair.

gunKeyPair: Gun key pair
salt: Salt for derivation
Returns: New wallet

Data Management

exportAllData

async exportAllData(publicKey: string): Promise<string>

Exports all user data.

publicKey: User's public key
Returns: JSON containing all data

importAllData

async importAllData(jsonData: string, publicKey: string): Promise<void>

Imports user data.

jsonData: JSON data to import
publicKey: User's public key

checkLocalData

async checkLocalData(publicKey: string): Promise<{hasWallet: boolean, hasStealthKeys: boolean, hasPasskey: boolean}>

Checks user's local data.

publicKey: Public key to check
Returns: Local data status

clearLocalData

async clearLocalData(publicKey: string): Promise<void>

Clears all local data for a user.

publicKey: Public key of data to clear

Utility Methods

getPublicKey

getPublicKey(): string

Gets current user's public key.

Returns: User's public key

getCurrentUserKeyPair

getCurrentUserKeyPair(): GunKeyPair

Gets current user's key pair.

Returns: Gun key pair

exportGunKeyPair

async exportGunKeyPair(): Promise<string>

Exports current user's Gun key pair.

Returns: JSON string of key pair

importGunKeyPair

async importGunKeyPair(keyPairJson: string): Promise<string>

Imports a Gun key pair.

keyPairJson: JSON string of key pair
Returns: Imported account's public key

🕶 StealthChain

Manages stealth address functionality.

generateStealthKeys

generateStealthKeys(cb: Callback<StealthKeyPair>): void

Generates a new stealth key pair.

generateStealthAddress

generateStealthAddress(recipientPublicKey: string, cb: Callback<StealthAddressResult>): void

Generates a stealth address for a recipient.

⛓️ EthereumManager

Manages Ethereum interactions.

setCustomProvider

setCustomProvider(rpcUrl: string, privateKey: string): void

Sets a custom provider.

loginWithEthereum

async loginWithEthereum(): Promise<string | null>

Performs login using an Ethereum account.

📝 Types and Interfaces

StorageType
enum StorageType {
  GUN,    // Decentralized storage
  LOCAL,  // Local storage
  BOTH    // Both storages
}
StealthKeyPair
interface StealthKeyPair {
  pub: string;    // Public key
  priv: string;   // Private key
  epub: string;   // Ephemeral public key
  epriv: string;  // Ephemeral private key
}
StealthAddressResult
interface StealthAddressResult {
  stealthAddress: string;      // Generated stealth address
  ephemeralPublicKey: string;  // Ephemeral public key
  recipientPublicKey: string;  // Recipient public key
}

🔐 WebAuthn

Supporto per l'autenticazione biometrica e passwordless tramite WebAuthn.

isWebAuthnSupported

isWebAuthnSupported(): boolean

Verifica se WebAuthn è supportato nel browser corrente.

Returns: true se WebAuthn è supportato

createAccountWithWebAuthn

async createAccountWithWebAuthn(alias: string): Promise<WalletResult>

Crea un nuovo account utilizzando WebAuthn per l'autenticazione.

alias: Username dell'account
Returns: Oggetto WalletResult contenente il wallet creato

loginWithWebAuthn

async loginWithWebAuthn(alias: string): Promise<string>

Effettua il login utilizzando WebAuthn.

alias: Username dell'account
Returns: Public key dell'utente autenticato

Interfaces

WebAuthnResult
interface WebAuthnResult {
  success: boolean;     // Indica se l'operazione è riuscita
  username?: string;    // Username dell'account
  password?: string;    // Password generata
  credentialId?: string; // ID della credenziale WebAuthn
  error?: string;      // Messaggio di errore se presente
}
WebAuthnVerifyResult
interface WebAuthnVerifyResult {
  success: boolean;                    // Indica se la verifica è riuscita
  authenticatorData?: ArrayBuffer;     // Dati dell'autenticatore
  signature?: ArrayBuffer;             // Firma della verifica
  error?: string;                     // Messaggio di errore se presente
}