Overview
This quickstart guide will walk you through creating attestations using the Stellar SDK. You’ll learn how to:
- Install and initialize the Stellar client
- Create schemas for structured credentials
- Issue basic attestations
- Use BLS delegation for off-chain signing
- Query attestations from the Horizon indexer
This guide uses Stellar testnet for safe experimentation. Switch to mainnet when ready for production with actual deployed contracts.
Prerequisites
- Node.js 18+ installed
- TypeScript familiarity recommended
- Stellar wallet (testnet account with XLM for gas)
- Basic understanding of Soroban smart contracts
Step 1: Installation
Install the Stellar SDK and dependencies:
npm install @attestprotocol/stellar-sdk @stellar/stellar-sdk
Get Testnet Account
Create a Stellar testnet account with Friendbot:
curl "https://friendbot.stellar.org?addr=YOUR_PUBLIC_KEY"
Step 2: Initialize the Client
Initialize the Stellar attestation client with your configuration:
import { StellarAttestationClient } from '@attestprotocol/stellar-sdk';
import { Keypair } from '@stellar/stellar-sdk';
// Initialize client
const client = new StellarAttestationClient({
rpcUrl: 'https://soroban-testnet.stellar.org',
network: 'testnet',
publicKey: 'GBXXXXXXXXXXXXXXXXXXXXX',
// Optional: specify custom contract ID
contractId: 'CDBWGWEZ3P4DZ3YUZSCEUKOVV2UGF2PYQEPW3E5OKNLYS5SNW4SQLDUA'
});
// Create signer from secret key
const signer = Keypair.fromSecret(process.env.STELLAR_SECRET_KEY);
console.log('Client initialized for testnet');
Never commit private keys to version control. Always use environment variables for secrets.
Network Configuration
The client automatically uses the correct contract addresses for testnet and mainnet based on your network parameter.
Step 3: Register as Authority
Before issuing attestations, register your wallet as an authority:
const authority = await sdk.registerAuthority();
if (authority.error) {
console.error('Registration failed:', authority.error);
process.exit(1);
}
console.log('Authority registered successfully');
Authority registration is a one-time process per wallet. You can check your status with sdk.fetchAuthority().
Step 4: Create or Select Schema
Schemas define the structure of your attestations:
// Use pre-built KYC schema
const schemaUID = 'kyc-basic-v1';
console.log('Using existing schema:', schemaUID);
Step 5: Issue Your First Attestation
Create an attestation for a user:
const attestation = await sdk.attest({
schemaUID: 'kyc-basic-v1',
subject: '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHv1', // Target wallet
value: 'verified:true,level:enhanced,score:95,timestamp:1704067200',
reference: 'kyc-session-2024-001' // Optional reference
});
if (attestation.data) {
console.log('Attestation issued!');
console.log('UID:', attestation.data.attestationUID);
} else {
console.error('Attestation failed:', attestation.error);
}
The value field must match your schema definition. Each field is separated by commas in fieldName:value format.
Step 6: Verify Attestations
Check if a user has valid attestations:
const result = await sdk.fetchAttestation({
schemaUID: 'kyc-basic-v1',
subject: '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHv1'
});
if (result.data && !result.data.revoked) {
console.log('User has valid KYC attestation');
} else {
console.log('No valid attestation found');
}
Step 7: Complete Example
Here’s a complete working example:
<<<<<<< HEAD
import { AttestSDK } from '@attestprotocol/sdk';
=======
import { AttestProtocol } from '@attestprotocol/sdk';
>>>>>>> canary
import dotenv from 'dotenv';
dotenv.config();
async function main() {
try {
// Initialize SDK
<<<<<<< HEAD
const sdk = await AttestSDK.initializeStellar({
=======
const sdk = await AttestProtocol.initializeStellar({
>>>>>>> canary
secretKeyOrCustomSigner: process.env.STELLAR_SECRET_KEY,
publicKey: process.env.STELLAR_PUBLIC_KEY,
url: 'https://soroban-testnet.stellar.org'
});
console.log('✅ SDK initialized');
// Register authority (if needed)
const authority = await sdk.fetchAuthority();
if (authority.error) {
await sdk.registerAuthority();
console.log('✅ Authority registered');
}
// Issue attestation
const attestation = await sdk.attest({
schemaUID: 'kyc-basic-v1',
subject: '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHv1',
value: 'verified:true,level:basic,score:85,timestamp:' + Date.now(),
reference: 'demo-' + Date.now()
});
if (attestation.data) {
console.log('✅ Attestation created:', attestation.data.attestationUID);
}
// Verify attestation
const verification = await sdk.fetchAttestation({
schemaUID: 'kyc-basic-v1',
subject: '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHv1'
});
if (verification.data) {
console.log('✅ Attestation verified');
}
} catch (error) {
console.error('❌ Error:', error.message);
}
}
main();
Environment Setup
Create a .env file in your project root:
# Stellar
STELLAR_SECRET_KEY=your_stellar_secret_key
STELLAR_PUBLIC_KEY=your_stellar_public_key
# Solana
SOLANA_SECRET_KEY=your_solana_secret_key
# Optional: Custom RPC endpoints
STELLAR_RPC_URL=https://soroban-testnet.stellar.org
SOLANA_RPC_URL=https://api.devnet.solana.com
Next Steps
Great! You’ve created your first attestation. Here’s what to explore next:
Troubleshooting
SDK Initialization Failed
- Check your secret key format and permissions
- Verify RPC endpoint is accessible
- Ensure you have sufficient balance for transactions
- Try using testnet first before mainnet
Authority Registration Failed
- Confirm wallet has sufficient balance for gas fees
- Check if authority is already registered with
fetchAuthority()
- Verify network connectivity to blockchain RPC
- Review error message for specific failure reason
Attestation Creation Failed
- Ensure you’re registered as an authority first
- Verify schema exists or create it before use
- Check that value format matches schema definition
- Confirm target address format is correct for your blockchain
- Double-check the schema UID and subject address
- Confirm you’re querying the correct network (testnet vs mainnet)
- Wait a few seconds for blockchain confirmation
- Verify the attestation wasn’t revoked
