Intents & Attestation

Every protocol method call returns an Intent object containing the attested transaction and verification data.

Intent Structure

const intent = await sona.solend.deposit({
  amount: 100,
  symbol: 'USDC'
});

console.log(intent);
// {
//   transaction: "...",              // Base64-encoded transaction
//   attestation: {
//     signature: "..."               // Ed25519 signature
//   },
//   integrityPubkeyB64: "...",       // Enclave public key
//   verify: async function() { ... } // Verification method
// }

transaction

The Solana transaction ready to be signed, encoded as base64.

// Decode and parse with @solana/web3.js v2
import { getBase64Decoder } from '@solana/codecs-strings';
import { createTransactionMessage } from '@solana/transaction-messages';

const txBytes = getBase64Decoder().decode(intent.getTransaction());
const transaction = createTransactionMessage(txBytes);

attestation.signature

Ed25519 signature over the transaction, generated inside the secure enclave using a sealed private key.

integrityPubkeyB64

The enclave's public key used to verify the signature. This key is persistent for the lifetime of the enclave.

Verifying Attestations

Always verify the attestation before signing:

const intent = await sona.solend.deposit({
  amount: 100,
  symbol: 'USDC'
});

// Verify the attestation
const isValid = await intent.verify();

if (!isValid) {
  throw new Error('Attestation verification failed - do not sign!');
}

// Safe to proceed with signing
const transaction = intent.getTransaction();

Verification Process

The verify() method:

1. Decodes the base64 transaction, signature, and public key
2. Verifies the Ed25519 signature using @noble/ed25519
3. Returns true if signature is valid, false otherwise

import { Intent } from '@sonabuild/kit';

// You can also create intents directly
const intent = new Intent({
  transaction: '...',
  attestation: {
    signature: '...'
  },
  integrityPubkeyB64: '...'
});

const isValid = await intent.verify();

Integration with Wallets

Here's a complete example integrating with Phantom wallet:

import { createSolanaRpc } from '@solana/rpc';
import { getBase64Decoder } from '@solana/codecs-strings';
import { Sona } from '@sonabuild/kit';

const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');
const sona = new Sona({
  wallet: wallet.publicKey.toString()
});

// Generate attested transaction
const intent = await sona.solend.deposit({
  amount: 100_000_000  // 100 USDC
});

// CRITICAL: Verify attestation
if (!await intent.verify()) {
  throw new Error('Attestation verification failed');
}

// Decode transaction
const txBytes = getBase64Decoder().decode(intent.getTransaction());

// Sign with wallet (wallet handles deserialization)
const signedTx = await wallet.signTransaction(txBytes);

// Send transaction
const signature = await rpc.sendTransaction(signedTx, {
  encoding: 'base64'
}).send();

// Confirm transaction
await rpc.confirmTransaction(signature, {
  commitment: 'confirmed'
}).send();

console.log('Transaction confirmed:', signature);

Security Best Practices

Always Verify

Never skip attestation verification:

// ❌ DANGEROUS - Never do this
const intent = await sona.solend.deposit({ amount: 100, symbol: 'USDC' });
const tx = intent.getTransaction();
await wallet.signTransaction(tx);  // No verification!

// ✅ SAFE - Always verify first
const intent = await sona.solend.deposit({ amount: 100, symbol: 'USDC' });
if (!await intent.verify()) {
  throw new Error('Attestation failed');
}
const tx = intent.getTransaction();
await wallet.signTransaction(tx);

Check Public Key

For extra security, verify the enclave's public key matches a known good value:

const KNOWN_ENCLAVE_PUBKEY = 'expected-base64-key...';

const intent = await sona.solend.deposit({ amount: 100, symbol: 'USDC' });

if (intent.integrityPubkeyB64 !== KNOWN_ENCLAVE_PUBKEY) {
  throw new Error('Unknown enclave public key');
}

if (!await intent.verify()) {
  throw new Error('Attestation verification failed');
}

Display Before Signing

Show users what they're signing:

const intent = await sona.solend.deposit({ amount: 100, symbol: 'USDC' });

// Verify attestation
const verified = await intent.verify();

// Show verification status to user
console.log('✓ Transaction attested by secure enclave');
console.log('✓ Signature verified:', verified);
console.log('Action: Deposit 100 USDC to Solend');

// Then proceed with signing