@saw-protocol/core

The foundational interface contracts and data types for the SAW Protocol (Solana Agentic Wallet Protocol).

This package is completely dependency-free (aside from @solana/web3.js for strict cryptographic typing) and serves as the architectural blueprint for any SAWP implementation.

Installation

npm install @saw-protocol/core

DID & Identity System

This package provides utilities for generating and managing agent identities.

Generate DID

import { generateDID, generateAgentDID, resolveDID, isValidDID } from "@saw-protocol/core";
import { Keypair } from "@solana/web3.js";

// Generate random agent identity
const { did, keypair, document } = generateDID();
// did: "did:sol:8x7Y9X2..."

// Convenience function
const { did, keypair } = generateAgentDID();

// With existing keypair
const existing = Keypair.generate();
const { did } = generateDID(existing);

// Deterministic from seed
const { did, keypair } = generateDeterministicDID(new Uint8Array(32).fill(1));

DID Resolution & Validation

// Extract public key from DID
const pubkey = resolveDID("did:sol:8x7Y9...");

// Validate DID format
const valid = isValidDID("did:sol:8x7Y9...");

Signing & Verification

import * as nacl from "tweetnacl";
import * as bs58 from "bs58";
import { verifyDIDOwnership } from "@saw-protocol/core";

const { did, keypair } = generateAgentDID();

// Sign message
const message = "Transfer 0.1 SOL";
const signature = nacl.sign.detached(
  new TextEncoder().encode(message),
  keypair.secretKey
);
const signatureBase58 = bs58.encode(signature);

// Verify
const isValid = verifyDIDOwnership(did, signatureBase58, message);

Example Usage

You can import any of the strict TypeScript interfaces to implement your own custom SAWP infrastructure elements.

Implementing a Custom Keystore

import { IKeyStore, DID, EncryptedKeyBundle } from "@saw-protocol/core";
import { PublicKey, Transaction, VersionedTransaction } from "@solana/web3.js";

export class MyHardwareKeyStore implements IKeyStore {
  async create(agentId: DID): Promise<PublicKey> {
    // Generate key on hardware device...
    return new PublicKey("...");
  }

  async import(agentId: DID, secretKey: Uint8Array): Promise<PublicKey> {
    // Import key to hardware device...
    return new PublicKey("...");
  }

  async sign(
    walletAddress: PublicKey,
    transaction: Transaction | VersionedTransaction,
  ) {
    // Route signing request to hardware device...
    return transaction; // Signed
  }

  async rotate(walletAddress: PublicKey): Promise<PublicKey> {
    // Rotate implementation...
    return new PublicKey("...");
  }

  async export(
    walletAddress: PublicKey,
    encryptionKey: PublicKey,
  ): Promise<EncryptedKeyBundle> {
    // Export implementation...
    return { algo: "aes-256-gcm", data: "..." };
  }

  async destroy(walletAddress: PublicKey): Promise<void> {
    // Destroy implementation...
  }

  async listWallets(agentId: DID): Promise<PublicKey[]> {
    return [new PublicKey("...")];
  }
}

Type-Safe Protocol Structures

import { TransactionIntent, AgentMessage } from "@saw-protocol/core";

const request: AgentMessage = {
  id: "msg-1234",
  from: "did:sol:agentAlice",
  to: "did:sol:agentBob",
  type: "Request",
  payload: { prompt: "Please transfer 0.05 SOL to Charlie" },
  signature: "...", // Ed25519 signature
  timestamp: Date.now(),
  ttl: 60,
};