Skip to main content

Quick Start Guide

Get up and running with the Vaultys Peer SDK in just a few minutes! This guide will walk you through creating your first peer-to-peer application.

🚀 5-Minute Setup​

Step 1: Install the SDK​

npm install @vaultys/peer-sdk @vaultys/id

Step 2: Create Your First P2P App​

Here's a complete example that demonstrates the core features:

import {
  setupVaultysPeerSDK,
  BrowserStorageProvider,
  SimpleEventBus
} from '@vaultys/peer-sdk';
import { VaultysId } from '@vaultys/id';

async function createP2PApp() {
  // 1. Generate or load identity
  const vaultysId = await VaultysId.generatePerson();
  console.log('My DID:', vaultysId.did);

  // 2. Create event bus for handling events
  const eventBus = new SimpleEventBus();

  // 3. Set up the peer service
  const peerService = setupVaultysPeerSDK({
    vaultysId,
    storageProvider: new BrowserStorageProvider(),
    eventBus: eventBus,
    relay: {
      host: 'peerjs.92k.de',
      port: 443,
      path: '/',
      secure: true
    }
  });

  // 4. Set up event listeners
  peerService.on('relay-connected', (did) => {
    console.log('Connected to relay!');
  });

  peerService.on('message-received', (message) => {
    console.log('New message:', message.content);
    console.log('From:', message.from);
  });

  peerService.on('contact-online', (did) => {
    console.log('Contact online:', did);
  });

  // 5. Initialize the service
  await peerService.initialize();

  // 6. Add a contact
  const contact = await peerService.addContact(
    'did:vaultys:example123',
    { nickname: 'Alice' }
  );

  // 7. Send a message
  await peerService.sendMessage(
    contact.did,
    'Hello, Alice! 👋'
  );

  return peerService;
}

// Run the app
createP2PApp().catch(console.error);

📝 Basic Examples​

Browser Example​

Create an index.html file:

<!DOCTYPE html>
<html>
<head>
  <title>Vaultys P2P Chat</title>
</head>
<body>
  <h1>P2P Chat</h1>

  <div id="status">Connecting...</div>
  <div id="my-did"></div>

  <div>
    <h2>Add Contact</h2>
    <input type="text" id="contact-did" placeholder="Contact DID">
    <button onclick="addContact()">Add</button>
  </div>

  <div>
    <h2>Send Message</h2>
    <select id="contact-list"></select>
    <input type="text" id="message" placeholder="Type a message">
    <button onclick="sendMessage()">Send</button>
  </div>

  <div>
    <h2>Messages</h2>
    <div id="messages"></div>
  </div>

  <script type="module">
    import {
      setupVaultysPeerSDK,
      BrowserStorageProvider
    } from './node_modules/@vaultys/peer-sdk/dist/index.mjs';
    import { VaultysId } from '@vaultys/id';

    let peerService;

    async function init() {
      const vaultysId = await VaultysId.generatePerson();

      peerService = setupVaultysPeerSDK({
        vaultysId,
        storageProvider: new BrowserStorageProvider()
      });

      peerService.on('relay-connected', () => {
        document.getElementById('status').textContent = 'Connected ✓';
        document.getElementById('my-did').textContent = `My DID: ${vaultysId.did}`;
      });

      peerService.on('message-received', (message) => {
        const messagesDiv = document.getElementById('messages');
        messagesDiv.innerHTML += `
          <div>
            <strong>${message.from}:</strong> ${message.content}
            <small>(${new Date(message.timestamp).toLocaleTimeString()})</small>
          </div>
        `;
      });

      await peerService.initialize();
      window.peerService = peerService;
    }

    window.addContact = async () => {
      const did = document.getElementById('contact-did').value;
      if (!did) return;

      const contact = await peerService.addContact(did);

      const select = document.getElementById('contact-list');
      const option = document.createElement('option');
      option.value = contact.did;
      option.textContent = contact.did;
      select.appendChild(option);

      document.getElementById('contact-did').value = '';
    };

    window.sendMessage = async () => {
      const select = document.getElementById('contact-list');
      const messageInput = document.getElementById('message');

      if (!select.value || !messageInput.value) return;

      await peerService.sendMessage(select.value, messageInput.value);

      const messagesDiv = document.getElementById('messages');
      messagesDiv.innerHTML += `
        <div>
          <strong>You:</strong> ${messageInput.value}
          <small>(${new Date().toLocaleTimeString()})</small>
        </div>
      `;

      messageInput.value = '';
    };

    init();
  </script>
</body>
</html>

Node.js Example​

Create a chat.js file:

import {
  setupVaultysPeerSDK,
  NodeFSStorageProvider,
  setupNodeWebRTC
} from '@vaultys/peer-sdk';
import { VaultysId } from '@vaultys/id';
import wrtc from '@roamhq/wrtc';
import readline from 'readline';

// Set up WebRTC for Node.js
setupNodeWebRTC(wrtc);

async function createCLIChat() {
  // Create identity
  const vaultysId = await VaultysId.generateMachine();
  console.log('Your DID:', vaultysId.did);

  // Set up peer service
  const peerService = setupVaultysPeerSDK({
    vaultysId,
    storageProvider: new NodeFSStorageProvider(),
    relay: {
      host: 'peerjs.92k.de',
      port: 443,
      secure: true
    }
  });

  // Event handlers
  peerService.on('message-received', (message) => {
    console.log(`\n💬 ${message.from}: ${message.content}`);
  });

  peerService.on('contact-online', (did) => {
    console.log(`✅ ${did} is online`);
  });

  // Initialize
  await peerService.initialize();

  // Set up CLI interface
  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout
  });

  console.log('\nCommands:');
  console.log('  add <did> - Add a contact');
  console.log('  send <did> <message> - Send a message');
  console.log('  list - List contacts');
  console.log('  exit - Quit\n');

  rl.on('line', async (input) => {
    const [cmd, ...args] = input.split(' ');

    switch (cmd) {
      case 'add':
        await peerService.addContact(args[0]);
        console.log(`Added contact: ${args[0]}`);
        break;

      case 'send':
        const did = args[0];
        const message = args.slice(1).join(' ');
        await peerService.sendMessage(did, message);
        console.log(`Sent to ${did}: ${message}`);
        break;

      case 'list':
        const contacts = peerService.getContacts();
        console.log('Contacts:', contacts.map(c => c.did));
        break;

      case 'exit':
        await peerService.disconnect();
        process.exit(0);
        break;
    }
  });
}

createCLIChat();

🎯 Core Concepts​

1. Identity (DID)​

Every peer needs a unique identifier (DID):

// Generate new identity
const vaultysId = await VaultysId.generatePerson();

// Or load existing
const vaultysId = VaultysId.fromSecret('your-secret-key');

2. Storage Providers​

Choose the right storage for your platform:

// Browser - Auto-selects best available
import { BrowserStorageProvider } from '@vaultys/peer-sdk';
const storage = new BrowserStorageProvider();

// Node.js - File system
import { NodeFSStorageProvider } from '@vaultys/peer-sdk';
const storage = new NodeFSStorageProvider('./data');

// Memory - Temporary storage
import { MemoryStorageProvider } from '@vaultys/peer-sdk';
const storage = new MemoryStorageProvider();

3. Event Handling​

Subscribe to important events:

peerService.on('relay-connected', (did) => {
  // Connected to signaling server
});

peerService.on('message-received', (message) => {
  // New message received
});

peerService.on('peer-status', (did, status) => {
  // Peer connection status changed
});

peerService.on('contact-online', (did) => {
  // Contact came online
});

peerService.on('contact-offline', (did) => {
  // Contact went offline
});

4. Sending Messages​

Send different types of messages:

// Text message
await peerService.sendMessage(contactDid, 'Hello!');

// With metadata
await peerService.sendMessage(
  contactDid,
  'Important message',
  'text',
  null,
  { priority: 'high' }
);

// File message
const fileData = {
  name: 'document.pdf',
  size: 1024,
  type: 'application/pdf',
  data: arrayBuffer
};

await peerService.sendMessage(
  contactDid,
  'Sending document',
  'file',
  fileData
);

🔧 Configuration Options​

const peerService = setupVaultysPeerSDK({
  // Required
  vaultysId: vaultysId,

  // Storage (optional)
  storageProvider: new BrowserStorageProvider(),

  // PeerJS configuration (optional)
  relay: {
    host: 'your-relay-server.com',
    port: 443,
    path: '/',
    secure: true,
    config: {
      iceServers: [
        { urls: 'stun:stun.l.google.com:19302' }
      ]
    }
  },

  // Peer configuration (optional)
  defaultPeerConfig: {
    healthCheckInterval: 30000,
    maxRetryCount: 5,
    reconnectDelay: 5000,
    autoReconnect: true
  },

  // Debug mode (optional)
  debug: true
});

📚 Next Steps​

Now that you have a basic P2P application running:

  1. Learn More: Read the Architecture Overview
  2. Storage Options: Explore Storage Providers
  3. Advanced Features: Check out Advanced Patterns
  4. Full Examples: See the CLI Chat and Web Chat applications

🆘 Troubleshooting​

Connection Issues​

If peers can't connect:

  1. Check firewall settings
  2. Verify both peers are online
  3. Use STUN/TURN servers for NAT traversal

Message Not Delivered​

  1. Verify contact is online
  2. Check peer connection status
  3. Look for errors in console

Storage Errors​

  1. Check browser storage quota
  2. Verify storage permissions
  3. Try different storage provider

💡 Tips​

  • Development: Use debug: true for detailed logs
  • Production: Implement error handlers for all events
  • Security: Validate DIDs before adding contacts
  • Performance: Use OPFS storage in browsers when available
  • Reliability: Implement message acknowledgments for critical messages

Ready to build something amazing? 🚀

Edit this page
Last updated on by François-Xavier Thoorens