@sonabuild/kit
Advanced tools
Client SDK for Sona attested Solana transaction builders
A secure protocol toolkit for building and verifying attested Solana transactions using Trusted Execution Environments (TEEs). This SDK provides end-to-end encryption, integrity verification via Ed25519 signatures, and dynamic routing to protocol-specific transaction builders.
npm install @sonabuild/kit
import { Sona } from '@sonabuild/kit';
// Create client (uses defaults: api.sona.build, 30s timeout)
const sona = new Sona({
wallet: 'your-wallet-pubkey'
});
// Build attested transaction
const intent = await sona.solend.deposit({
amount: 1000000,
userPubkey: 'your-wallet-pubkey'
});
// Verify integrity signature
const isValid = await intent.verify();
console.log('Transaction verified:', isValid);
// Confirm transaction (sign and send)
const result = await intent.confirm(async (intents) => {
// Your signing logic here
const tx = intents[0].getTransaction(); // base64 serialized message
// Sign and send...
});
src/
├── index.js # Main Sona class and exports
├── client.js # Dynamic Proxy-based API client
├── session.js # Encryption session management
├── crypto.js # X25519 + XSalsa20-Poly1305 sealed box encryption
├── intent.js # Transaction intent with Ed25519 verification
├── internal-call.js # Route executor with encryption & retry logic
├── meta.js # API metadata caching
└── logger.js # Debug logging utilities
Client Enclave
│ │
├─── GET /session ───────────────────────► │
│ │
│ ◄──── encryptionPubKey, integrityPubKey ┤
│ │
├─── Generate ephemeral X25519 keypair │
├─── ECDH shared secret │
├─── Derive key via HSalsa20 │
├─── BLAKE2b nonce derivation │
├─── XSalsa20-Poly1305 encryption │
│ │
├─── POST /protocol/action {ctB64} ──────► │
│ │
│ Decrypt │
│ Build tx│
│ Sign tx │
│ │
│ ◄──── serializedMessage + integritySig ──┤
│ │
├─── Verify Ed25519 signature │
└─── Return Intent │
Sona Class// Minimal configuration
const sona = new Sona({ wallet: 'your-wallet-pubkey' });
// Advanced configuration
const sona = new Sona({
baseUrl: 'https://api.sona.build', // API base URL (default)
apiKey: 'your-api-key', // Optional API key
wallet: 'your-wallet-pubkey', // Wallet public key for context
origin: 'https://sona.build', // Origin for enclave validation (default)
timeout: 30000, // Request timeout in ms (default)
headers: { // Custom headers (optional)
'x-app-version': '1.0.0'
},
debug: false // Enable debug logging (default: false)
});
Options:
wallet (string, optional): Wallet public key for contextbaseUrl (string): API base URL (default: 'https://api.sona.build')apiKey (string, optional): API authentication keyorigin (string, optional): Origin for enclave validation (default: window.location.origin or 'https://sona.build')timeout (number): Request timeout in milliseconds (default: 30000)headers (object, optional): Custom headers to include in all requestsdebug (boolean): Enable debug logging (default: false)The client uses JavaScript Proxy to create dynamic method chains:
// Pattern: sona.{protocol}.{action}(payload)
await sona.solend.deposit({ amount: 1000000 })
await sona.marinade.stake({ amount: 5000000 })
await sona.jupiter.swap({ inputMint: 'SOL', outputMint: 'USDC', amount: 100 })
Routes are auto-discovered from /.well-known/config.json endpoint and validated at runtime.
dispose(): Cleanup method (currently no-op as keys are persistent)Intent ClassRepresents an attested transaction with integrity verification.
serializedMessageB64 (string): Base64-encoded Solana transactionintegritySigB64 (string): Base64-encoded Ed25519 signatureintegrityPubkeyB64 (string): Base64-encoded Ed25519 public keyawait intent.verify()
Verifies Ed25519 signature over the serialized transaction. Returns boolean.
await intent.confirm(sendFn)
Verifies integrity then calls sendFn([intent]) to sign and send the transaction.
intent.getTransaction()
Returns the base64-encoded serialized transaction for signing.
import { clearMetaCache, clearSessionCache, setDebug } from '@sonabuild/kit';
clearMetaCache(); // Force refresh of route metadata
clearSessionCache(); // Force refresh of encryption session
setDebug(true); // Enable debug logging
Routes with attested: true in metadata use full encryption flow:
ctB64 + paramsHintIntent object for verificationRoutes with attested: false send plain JSON POST requests with optional wallet context.
Sessions contain:
encryptionPubKeyB64: X25519 public key for sealed box encryptionintegrityPubkeyB64: Ed25519 public key for signature verificationmode: Enclave mode indicatorSessions are cached indefinitely (keys are persistent until enclave restart). Use clearSessionCache() to force refresh.
The SDK automatically retries on "stale ciphertext" errors by clearing the session cache and refetching keys.
try {
const intent = await sona.protocol.action(payload);
} catch (error) {
if (error.message.includes('stale ciphertext')) {
// Automatic retry with fresh session
}
console.error('Request failed:', error.message);
}
When debug: true, the SDK logs detailed performance metrics:
[Sona:Perf] Request completed in 245.67ms {
route: 'solend/deposit',
total_ms: 245.67,
meta: 1.23,
session: 0.45,
encrypt: 2.34,
api: 240.12,
parse: 1.53,
server_context_ms: 45.67,
server_enclave_ms: 180.23,
server_total_ms: 225.9,
api_overhead_ms: 14.22
}
Breakdown shows:
Compatible with libsodium's crypto_box_seal():
Integrity signatures use standard Ed25519 with SHA-512:
const isValid = await ed.verify(signature, message, publicKey);
npm test
Tests include:
Production:
@noble/ciphers (^1.0.0): XSalsa20-Poly1305, HSalsa20@noble/curves (^1.7.0): X25519 ECDH@noble/ed25519 (^2.0.0): Ed25519 signatures@noble/hashes (^1.3.0): BLAKE2b, SHA-512Dev:
mocha (^10.2.0): Test runnerchai (^4.3.10): AssertionsThe SDK is designed for both Node.js and modern browsers:
fetch API (polyfill required for Node < 18)The SDK validates all configuration options at construction time:
Invalid configuration will throw descriptive errors immediately.
All requests have configurable timeouts (default: 30 seconds):
const sona = new Sona({
timeout: 10000 // 10 second timeout
});
Include custom headers in all requests:
const sona = new Sona({
headers: {
'x-app-version': '1.0.0',
'x-environment': 'production'
}
});
All requests automatically include a unique x-request-id header for tracing requests through the system. This helps with debugging and correlating client logs with server logs.
origin option)# No build step required - pure ES modules
npm run test
Enable comprehensive logging:
import { Sona, setDebug } from '@sonabuild/kit';
setDebug(true); // Or pass debug: true to constructor
const sona = new Sona({
baseUrl: 'http://localhost:8080',
debug: true
});
Debug categories:
[Sona:Session]: Session fetch and caching[Sona:Crypto]: Encryption operations[Sona:Request]: API requests[Sona:Attestation]: Signature verification[Sona:Perf]: Performance metricsSee package.json for license information.
Publish a new version using semantic versioning:
npm run patch # 1.0.0 -> 1.0.1 (bug fixes)
npm run minor # 1.0.0 -> 1.1.0 (new features)
npm run major # 1.0.0 -> 2.0.0 (breaking changes)
Each command runs tests, builds the bundled dist/index.js (65KB minified), bumps version, and publishes to npm.
Test before publishing:
npm test # Run tests
npm run build # Build dist/index.js
npm pack --dry-run # Preview package contents
First time setup:
npm login
npm access ls-packages @sonabuild # Verify access
The prepublishOnly hook automatically runs tests before any publish to prevent broken releases.
This is an internal protocol toolkit. For issues or questions, contact the Sona development team.
FAQs
Protocol toolkit for Sona attested Solana transaction builders
We found that @sonabuild/kit demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.