Wallet Connection

Connect wallets to the PrivChain SDK for signing transactions.

Connection Methods

Keypair (Backend/Agents)

For server-side agents and automated systems:

import { PrivChain } from '@privchain/sdk';
import { Keypair, Connection } from '@solana/web3.js';
import bs58 from 'bs58';

const privchain = new PrivChain({
  connection: new Connection('https://api.mainnet-beta.solana.com'),
  network: 'mainnet-beta'
});

// From base58 private key
const secretKey = bs58.decode(process.env.WALLET_PRIVATE_KEY!);
const wallet = Keypair.fromSecretKey(secretKey);

// From Uint8Array
const wallet2 = Keypair.fromSecretKey(new Uint8Array([...]));

// Generate new wallet
const newWallet = Keypair.generate();
console.log('New address:', newWallet.publicKey.toBase58());
console.log('Private key:', bs58.encode(newWallet.secretKey));

// Connect to PrivChain
await privchain.connect(wallet);
console.log('Connected:', privchain.publicKey);

File-Based Key

Load from Solana CLI wallet file:

import { Keypair } from '@solana/web3.js';
import fs from 'fs';

// Solana CLI default location
const keyfile = `${process.env.HOME}/.config/solana/id.json`;
const secretKey = Uint8Array.from(JSON.parse(fs.readFileSync(keyfile, 'utf-8')));
const wallet = Keypair.fromSecretKey(secretKey);

await privchain.connect(wallet);

Browser Wallets

For frontend applications with Phantom, Solflare, etc.:

import { PrivChain } from '@privchain/sdk';
import { Connection } from '@solana/web3.js';

const privchain = new PrivChain({
  connection: new Connection('https://api.mainnet-beta.solana.com'),
  network: 'mainnet-beta'
});

// Connect to browser wallet
async function connectPhantom() {
  const { solana } = window as any;
  
  if (!solana?.isPhantom) {
    throw new Error('Phantom wallet not found');
  }
  
  const response = await solana.connect();
  
  // Create wallet adapter
  await privchain.connectBrowserWallet({
    publicKey: response.publicKey,
    signTransaction: solana.signTransaction.bind(solana),
    signAllTransactions: solana.signAllTransactions.bind(solana)
  });
  
  console.log('Connected:', response.publicKey.toBase58());
}

Wallet Adapter (React)

Using Solana Wallet Adapter:

import { useWallet } from '@solana/wallet-adapter-react';
import { usePrivChain } from '@privchain/react';

function WalletConnect() {
  const { publicKey, signTransaction, signAllTransactions, connected } = useWallet();
  const privchain = usePrivChain();
  
  useEffect(() => {
    if (connected && publicKey && signTransaction) {
      privchain.connectBrowserWallet({
        publicKey,
        signTransaction,
        signAllTransactions
      });
    }
  }, [connected, publicKey]);
  
  return (
    <WalletMultiButton />
  );
}

Wallet Operations

Check Connection

// Check if connected
if (privchain.isConnected) {
  console.log('Connected as:', privchain.publicKey?.toBase58());
}

// Get connection status
const status = privchain.getConnectionStatus();
// { connected: true, publicKey: '...', network: 'mainnet-beta' }

Get Balances

// Get PRIV balance
const privBalance = await privchain.getBalance();
console.log(`PRIV: ${privBalance}`);

// Get SOL balance (for fees)
const solBalance = await privchain.getSolBalance();
console.log(`SOL: ${solBalance}`);

// Get all balances
const balances = await privchain.getAllBalances();
console.log(balances);
// { priv: 1000, sol: 0.5 }

Switch Wallet

// Disconnect current wallet
await privchain.disconnect();

// Connect new wallet
const newWallet = Keypair.generate();
await privchain.connect(newWallet);

Security Best Practices

Environment Variables

Never hardcode private keys

Always use environment variables or secure key management.

// ✅ Good
const key = process.env.WALLET_PRIVATE_KEY;

// ❌ Bad
const key = '5K3j8f...'; // Never do this!

Key Rotation

Rotate keys regularly for agents:

import { Keypair } from '@solana/web3.js';
import fs from 'fs';

// Generate new key
const newKey = Keypair.generate();

// Save securely (example - use proper secret management)
fs.writeFileSync(
  '/secure/location/new-key.json',
  JSON.stringify(Array.from(newKey.secretKey))
);

// Transfer funds from old to new
const oldKey = loadOldKey();
await privchain.connect(oldKey);
await privchain.transfer({
  to: newKey.publicKey.toBase58(),
  amount: await privchain.getBalance() - 1 // Leave 1 PRIV for fees
});

// Switch to new key
await privchain.connect(newKey);

Hardware Security Modules (HSM)

For production agents:

import { HsmWallet } from '@privchain/hsm';

// Connect to HSM-backed wallet
const hsmWallet = new HsmWallet({
  keyId: 'privchain-agent-key',
  region: 'us-east-1' // AWS KMS example
});

await privchain.connect(hsmWallet);

Multi-Wallet Management

Multiple Agents

class AgentPool {
  private agents: Map<string, PrivChain> = new Map();
  
  async addAgent(name: string, privateKey: string) {
    const privchain = new PrivChain({
      connection: this.connection,
      network: 'mainnet-beta'
    });
    
    const wallet = Keypair.fromSecretKey(bs58.decode(privateKey));
    await privchain.connect(wallet);
    
    this.agents.set(name, privchain);
  }
  
  getAgent(name: string): PrivChain {
    return this.agents.get(name)!;
  }
  
  async getTotalBalance(): Promise<number> {
    let total = 0;
    for (const agent of this.agents.values()) {
      total += await agent.getBalance();
    }
    return total;
  }
}

Delegation

Create sub-wallets with limited permissions:

// Main wallet creates delegation
const mainWallet = await privchain.connect(mainKey);

const delegation = await privchain.identity.delegate({
  to: subAgentPublicKey,
  permissions: ['transfer'],
  maxAmount: 100,  // Max 100 PRIV per transaction
  expiry: Date.now() + 86400000 // 24 hours
});

// Sub-agent uses delegation
const subAgent = new PrivChain({ /* config */ });
await subAgent.connectWithDelegation({
  wallet: subAgentKey,
  delegation: delegation
});

// Sub-agent can now transfer up to 100 PRIV
await subAgent.transfer({ to: '...', amount: 50 });

Error Handling

import { WalletError, ConnectionError } from '@privchain/sdk';

try {
  await privchain.connect(wallet);
} catch (error) {
  if (error instanceof ConnectionError) {
    console.error('Failed to connect to Solana:', error.message);
  } else if (error instanceof WalletError) {
    console.error('Wallet error:', error.message);
  } else {
    throw error;
  }
}

Next Steps

• Token Operations - Transfer and manage PRIV
• Privacy Operations - Use privacy pools
• API Reference - Full API docs