SELF Chain Public Interfaces Specification
🚧 BETA NOTICE: These public interfaces are currently in beta and under active development. The specifications described here represent our target API design, but implementation is ongoing. Check back regularly for updates!
This document defines the security-safe public interfaces that can be exposed in SDKs and public repositories without compromising SELF Chain's security.
Overview
SELF Chain maintains strict security boundaries between public and private code. This specification defines what interfaces can be safely made public while protecting our core security mechanisms.
Core Principles
- Read-Only First: Public interfaces should primarily be read-only
- No Validation Logic: Never expose AI validation algorithms or thresholds
- Abstract Consensus: Hide internal consensus mechanisms behind abstractions
- Testnet Safe: All interfaces must be safe for public testnet use
- Security by Design: Default to restrictive, open carefully
Public Interfaces
1. Blockchain Query Interface
Purpose: Allow reading blockchain state without exposing internals
interface IBlockchainQuery {
// Block queries
getBlock(height: number): Promise<Block>;
getBlockByHash(hash: string): Promise<Block>;
getLatestBlock(): Promise<Block>;
getBlockRange(start: number, end: number): Promise<Block[]>;
// Transaction queries
getTransaction(hash: string): Promise<Transaction>;
getTransactionsByBlock(blockHeight: number): Promise<Transaction[]>;
getTransactionsByAddress(address: string, limit?: number): Promise<Transaction[]>;
// Account queries
getAccount(address: string): Promise<Account>;
getBalance(address: string): Promise<Balance>;
getNonce(address: string): Promise<number>;
// Network queries
getNetworkInfo(): Promise<NetworkInfo>;
getValidators(): Promise<ValidatorInfo[]>;
getPeers(): Promise<PeerInfo[]>;
}
Security Notes:
- ✅ Read-only operations
- ✅ No exposure of validation logic
- ✅ Public blockchain data only
2. Transaction Builder Interface
Purpose: Construct transactions without exposing validation rules
interface ITransactionBuilder {
// Basic transactions
transfer(params: TransferParams): UnsignedTransaction;
delegate(params: DelegateParams): UnsignedTransaction;
undelegate(params: UndelegateParams): UnsignedTransaction;
// Transaction helpers
estimateFee(tx: UnsignedTransaction): Promise<Fee>;
validateAddress(address: string): boolean;
generateAddress(): Address;
}
interface TransferParams {
from: string;
to: string;
amount: string;
memo?: string;
// Note: No validation thresholds exposed
}
Security Notes:
- ✅ Transaction construction only
- ✅ Validation happens on-chain
- ✅ No consensus parameters exposed
3. Event Subscription Interface
Purpose: Subscribe to blockchain events in real-time
interface IEventSubscription {
// Block events
onNewBlock(callback: (block: Block) => void): Subscription;
onBlockFinalized(callback: (block: Block) => void): Subscription;
// Transaction events
onTransaction(filter: TxFilter, callback: (tx: Transaction) => void): Subscription;
onTransactionConfirmed(txHash: string, callback: (tx: Transaction) => void): Subscription;
// Network events
onValidatorChange(callback: (validators: ValidatorInfo[]) => void): Subscription;
onNetworkStatus(callback: (status: NetworkStatus) => void): Subscription;
}
interface Subscription {
unsubscribe(): void;
id: string;
}
Security Notes:
- ✅ Public event data only
- ✅ No internal consensus events
- ✅ Rate-limited subscriptions
4. Cryptographic Utilities Interface
Purpose: Provide crypto utilities without exposing secure operations
interface ICryptoUtils {
// Key generation (testnet safe)
generateKeyPair(): KeyPair;
generateMnemonic(): string;
keyPairFromMnemonic(mnemonic: string): KeyPair;
// Public key operations only
publicKeyToAddress(publicKey: string): string;
isValidPublicKey(publicKey: string): boolean;
// Hashing (public algorithms only)
sha256(data: Uint8Array): Uint8Array;
keccak256(data: Uint8Array): Uint8Array;
// Signature verification (not creation)
verifySignature(message: Uint8Array, signature: Uint8Array, publicKey: string): boolean;
}
Security Notes:
- ✅ Public crypto operations only
- ✅ No private key operations in SDK
- ✅ Standard algorithms only
5. Smart Contract Interface (Future)
Purpose: Interact with smart contracts when available
interface ISmartContract {
// Deployment (testnet)
deploy(bytecode: Uint8Array, params?: any[]): Promise<ContractAddress>;
// Interaction
call(address: string, method: string, params: any[]): Promise<any>;
query(address: string, method: string, params: any[]): Promise<any>;
// Events
getContractEvents(address: string, filter?: EventFilter): Promise<Event[]>;
subscribeToContract(address: string, callback: (event: Event) => void): Subscription;
}
Security Notes:
- ✅ Standard contract ABI only
- ✅ No privileged operations
- ✅ Testnet deployment only initially
Restricted Interfaces (NOT Public)
These interfaces must NEVER be exposed in public code:
❌ AI Validation Interface
// NEVER EXPOSE THIS
interface IAIValidation {
validateTransaction(tx: Transaction): AIValidationResult;
getValidationThreshold(): number;
getPatternRules(): PatternRule[];
trainModel(data: TrainingData): void;
}
❌ Consensus Internal Interface
// NEVER EXPOSE THIS
interface IConsensusInternal {
proposeBlock(transactions: Transaction[]): Block;
voteOnBlock(block: Block): Vote;
getConsensusParams(): ConsensusParameters;
adjustDifficulty(): void;
}
❌ Security Critical Interface
// NEVER EXPOSE THIS
interface ISecurityCritical {
getSecurityThresholds(): SecurityThresholds;
detectAnomalies(data: any): AnomalyReport;
getPrivateKeys(): PrivateKey[];
accessSecureStorage(): SecureStorage;
}
Data Types (Public Safe)
Block Structure
interface Block {
height: number;
hash: string;
previousHash: string;
timestamp: number;
transactions: string[]; // Transaction hashes only
validator: string;
// Note: No AI scores or validation details
}
Transaction Structure
interface Transaction {
hash: string;
from: string;
to: string;
amount: string;
fee: string;
nonce: number;
timestamp: number;
status: 'pending' | 'confirmed' | 'failed';
// Note: No validation scores or AI details
}
Network Information
interface NetworkInfo {
chainId: string;
networkType: 'testnet' | 'mainnet';
blockHeight: number;
blockTime: number;
activeValidators: number;
// Note: No consensus parameters
}
Implementation Guidelines
For SDK Developers
- Always Check Network Type
if (network === 'mainnet' && !MAINNET_ENABLED) {
throw new Error('Mainnet not yet available');
}
- Include Testnet Warnings
console.warn('⚠️ Connected to SELF Chain TESTNET - tokens have no value');
- Rate Limit Everything
const rateLimiter = new RateLimiter({
maxRequests: 100,
windowMs: 60000 // 1 minute
});
- Validate But Don't Expose
// Good: Validate on client side for UX
if (!isValidAddress(address)) {
throw new Error('Invalid address format');
}
// Bad: Don't expose how validation works internally
// if (address.colorMarker !== calculateColorMarker(address)) { ... }
For Core Developers
-
Review All Public Interfaces
- Security review required for new interfaces
- Document security implications
- Test with adversarial mindset
-
Maintain Abstraction Layers
- Public interfaces call private implementations
- Never expose internal state
- Use dependency injection
-
Monitor Usage
- Log public API usage
- Detect abnormal patterns
- Have kill switches ready
Version Management
Interface Versioning
interface VersionedAPI {
version: '1.0.0';
deprecated?: string[];
experimental?: string[];
}
Breaking Changes
- Announce 3 months in advance
- Provide migration guides
- Support old version for 6 months
Security Checklist
Before making any interface public:
- No validation logic exposed
- No consensus parameters visible
- No security thresholds included
- Rate limiting implemented
- Testnet safety checks added
- Security review completed
- Documentation updated
- Examples provided
Conclusion
These public interfaces provide a safe, useful API surface for developers while protecting SELF Chain's security-critical components. When in doubt, keep it private and consult the security team.
"Security is not a feature, it's a design principle." - SELF Chain Security Team