-
Notifications
You must be signed in to change notification settings - Fork 0
SDK.md
Document Type: Software Development Kit Specification
Project: CeloHT
Status: Active / Evolving
Last Updated: August 2026
Authors: Johnny Dubic & CeloHT Community
The CeloHT SDK is intended to provide developers with reusable interfaces for interacting with CeloHT services and supported Celo blockchain functionality.
The SDK should reduce unnecessary implementation complexity while maintaining strong security, predictable behavior, and clear developer documentation.
The SDK may provide functionality for:
Celo network interaction
CELO and cUSD operations
Wallet connectivity
Transaction preparation
Address validation
Smart-contract interaction
CeloHT platform services
Educational applications
Agent services
Application integrations
The exact API surface may evolve as the CeloHT technology stack develops.
The SDK should prioritize:
Security
Simplicity
Type safety
Reliability
Developer experience
Maintainability
Backward compatibility
Clear documentation
The SDK may be used by:
CeloHT developers
DApp developers
Community developers
Integration partners
Researchers
Educational developers
Internal project contributors
The SDK may support:
Modern web browsers
Node.js
TypeScript
JavaScript
Next.js applications
React applications
Additional environments may be supported in future releases.
A TypeScript-first implementation is recommended.
Example:
TypeScript
↓
CeloHT SDK
↓
Celo / RPC / Smart Contracts
↓
Blockchain
A typed API helps developers detect many integration errors before runtime.
A future package may be distributed through a package registry.
Example:
npm install @celoht/sdk
If the package name or distribution method changes, the official documentation should be treated as authoritative.
Example conceptual usage:
import { CeloHT } from "@celoht/sdk";
const celoht = new CeloHT({
network: "celo",
});
The exact initialization API may change before a stable release.
SDK applications should explicitly identify the intended network.
Example:
const celoht = new CeloHT({
network: "celo",
});
Production applications should not silently switch networks.
Sensitive configuration should be provided through environment variables or secure secret-management systems.
Example:
CELOHT_RPC_URL=
CELOHT_API_KEY=
Private keys must never be committed to source control.
The SDK may support wallet integrations through compatible wallet-provider interfaces.
Possible functionality:
Connect wallet
Disconnect wallet
Read account
Read chain
Request signature
Submit transaction
Monitor transaction
The SDK should never request a user's private key.
The SDK should provide utilities for validating blockchain addresses.
Example conceptual API:
const valid = celoht.address.isValid(address);
Applications should validate addresses before displaying or submitting transactions.
Supported functionality may include:
Read CELO balance
Prepare CELO transfer
Estimate transaction requirements
Submit transaction
Monitor confirmation
Example conceptual usage:
const balance = await celoht.celo.getBalance(address);
The SDK may provide interfaces for supported cUSD functionality.
Example:
const balance = await celoht.cusd.getBalance(address);
Applications should clearly distinguish CELO from cUSD.
A transaction should generally pass through:
Input
↓
Validation
↓
Transaction Construction
↓
User Review
↓
Wallet Signature
↓
Broadcast
↓
Confirmation
↓
Result
The SDK should not bypass user authorization.
Before a transaction is submitted, applications should display relevant information such as:
Recipient
Asset
Amount
Network
Estimated fees
Contract interaction where applicable
Users should have an opportunity to review transactions before signing.
The SDK may expose states such as:
prepared
signed
submitted
pending
confirmed
failed
replaced
unknown
Applications should not assume that submission automatically means successful confirmation.
SDK errors should be structured and predictable.
Example:
try {
await celoht.transaction.send(tx);
} catch (error) {
// Handle error
}
Errors may include:
Invalid address
Insufficient balance
Rejected signature
Network error
RPC failure
Contract revert
Timeout
Unsupported network
Automatic retries should be used carefully.
Safe retry candidates may include certain transient network failures.
The SDK should avoid blindly retrying transactions where doing so could create unintended duplicate operations.
Applications may configure RPC endpoints.
Example:
const celoht = new CeloHT({
network: "celo",
rpcUrl: process.env.CELOHT_RPC_URL,
});
Production systems should monitor RPC reliability and latency.
The SDK may expose typed interfaces for supported CeloHT smart contracts.
Conceptual example:
const contract = celoht.contracts.get("ExampleContract");
const result = await contract.read("someMethod");
Contract addresses and ABIs should be versioned and verified.
CeloHT may maintain a registry containing:
| Field | Description |
|---|---|
| Contract | Contract name |
| Address | Deployment address |
| Network | Blockchain network |
| Version | Contract version |
| ABI | Interface |
| Verification | Verification status |
| Deployment | Deployment reference |
Only officially maintained addresses should be presented as production CeloHT contracts.
Developers should never assume that an SDK abstraction makes a smart contract secure.
Security should include:
Code review
Testing
Access-control review
Dependency review
Audits where appropriate
Deployment verification
See SMART_CONTRACTS.md and SECURITY_AUDITS.md.
If CeloHT exposes backend APIs, the SDK may provide a typed API client.
Example:
const programs = await celoht.programs.list();
The API client should handle:
Authentication
Request formatting
Response validation
Errors
Timeouts
Versioning
Authenticated API requests should use secure authentication mechanisms.
Applications should not expose privileged credentials in client-side code.
Server-side credentials should remain on trusted infrastructure.
Authentication establishes identity.
Authorization determines what the authenticated entity may do.
The SDK should respect server-side authorization rules and should never rely solely on client-side permission checks.
The SDK may provide interfaces for CeloHT programs.
Potential resources:
Programs
├── Education
├── Agent Network
├── Reforestation
├── Community
└── Research
Potential functionality:
List courses
Retrieve course
Track progress
Retrieve lessons
Submit assessments
Retrieve quiz results
Example:
const courses = await celoht.education.listCourses();
The SDK may provide interfaces for educational assessments.
Potential methods:
education.quizzes.list()
education.quizzes.get(id)
education.quizzes.submit(id, answers)
Results should not be exposed to unauthorized users.
Where applicable, agent functionality may include:
Agent profile
Availability
Service information
Transaction records
Operational status
Sensitive financial or personal information must be protected.
Potential functionality may include:
Project listing
Planting records
Community participation
Monitoring data
Environmental metrics
Environmental metrics should clearly distinguish reported, estimated, and verified values.
Potential functionality may include:
Community profiles
Events
Programs
Participation
Announcements
Access controls should apply to private community information.
List APIs should support pagination where datasets may become large.
Example:
const result = await celoht.programs.list({
page: 1,
limit: 25,
});
The final pagination interface should be documented with the released SDK version.
APIs may implement rate limits to protect infrastructure.
Applications should:
Respect response headers.
Implement backoff where appropriate.
Avoid unnecessary polling.
Cache data where appropriate.
Caching may improve performance for data that does not change frequently.
However, applications should avoid caching:
Sensitive data
Authorization decisions
Highly volatile balances
Security-critical state
Cache duration should correspond to data freshness requirements.
The SDK may expose blockchain or platform events.
Potential examples:
TransactionSubmitted
TransactionConfirmed
ProgramUpdated
CourseCompleted
AgentStatusChanged
Event interfaces should be versioned.
Where supported, webhooks may notify applications about events.
Webhook implementations should verify:
Signature
Timestamp
Event ID
Source
Payload integrity
Applications should protect against replay attacks.
Where appropriate, real-time services may provide:
Transaction updates
Network status
Program updates
Agent availability
Applications should handle connection failures and reconnection safely.
The SDK should expose explicit TypeScript types.
Example:
type Asset = "CELO" | "cUSD";
interface Transfer {
asset: Asset;
amount: string;
recipient: string;
}
Financial amounts should avoid unsafe floating-point arithmetic.
Token amounts should preferably be represented using:
Integer base units
BigInt
Decimal-safe libraries
Avoid:
const amount = 0.1 + 0.2;
for financial calculations where precision matters.
SDK users should:
Protect private keys.
Use trusted wallet providers.
Validate addresses.
Verify networks.
Review transactions.
Keep dependencies updated.
Avoid exposing secrets.
Monitor production systems.
SDK logs should not expose:
Private keys
Recovery phrases
Passwords
Authentication tokens
Sensitive personal data
Applications should use structured logging where possible.
Production applications should monitor:
Request latency
Error rates
RPC failures
Transaction failures
API availability
SDK version
Dependency health
Monitoring helps identify integration problems early.
SDK development should include:
Test individual functions.
Test interactions with external services.
Test smart-contract interfaces.
Test complete user workflows.
Developers should use appropriate test environments before production deployment.
Testing should verify:
Wallet connection
Transactions
Contract interactions
Error handling
API behavior
Network switching
External services may be mocked during unit testing.
However, mocks should not replace real integration testing.
SDK releases should document:
Supported Node.js versions
Supported browsers
TypeScript compatibility
Supported network versions
API compatibility
Breaking changes should receive explicit release notes.
The SDK should follow a predictable versioning policy.
Example:
MAJOR.MINOR.PATCH
Breaking API changes.
Backward-compatible functionality.
Backward-compatible fixes.
See VERSIONING.md.
Deprecated APIs should:
Be documented.
Include migration guidance.
Remain available for an announced period where practical.
Eventually be removed according to the versioning policy.
SDK releases should ideally pass:
Code review
Automated tests
Security checks
Build verification
Documentation review
Package validation
Release publication
See RELEASE_PROCESS.md.
Each public SDK API should document:
Purpose
Parameters
Return value
Errors
Example usage
Security considerations
Version availability
Conceptual example:
import { CeloHT } from "@celoht/sdk";
const celoht = new CeloHT({
network: "celo",
});
async function main() {
const address = "0x...";
const balance = await celoht.celo.getBalance(address);
console.log(balance);
}
main();
This is illustrative. Production developers should use the API corresponding to the released SDK version.
A typical application may use:
CeloHT Application
│
▼
CeloHT SDK
│
┌──────┼────────┐
▼ ▼ ▼
Wallet API Celo
Provider Service Network
│
▼
Smart Contracts
Server-side applications may use the SDK for:
Blockchain reads
API integrations
Data processing
Monitoring
Administrative workflows
Private signing operations should be handled through secure infrastructure.
Frontend applications should generally rely on user-controlled wallets for signing transactions.
Sensitive credentials should never be embedded into browser bundles.
If mobile SDK support is introduced, it should follow platform-specific security standards.
Potential considerations include:
Secure key storage
Biometric authentication
Deep links
Wallet integration
Secure network communication
Developers should be able to report:
Bugs
Documentation problems
API inconsistencies
Security concerns
Feature requests
Security vulnerabilities should follow the responsible disclosure process rather than being publicly exposed immediately.
Where the SDK is open source, development should support:
Public issue tracking
Pull requests
Code review
Automated testing
Transparent releases
Community contributions
Changes to public interfaces should receive appropriate technical review.
Major architectural changes should consider:
Security
Developer impact
Compatibility
Maintenance cost
Performance
Community needs
The SDK specification represents the intended architecture and developer-facing direction of CeloHT.
Specific APIs should not be considered production guarantees unless they are implemented, tested, versioned, and documented in an official release.
The CeloHT SDK is intended to make integration with CeloHT technology simpler without hiding the security responsibilities associated with blockchain applications.
Its core principle is:
Make the safe path the easy path.
The SDK should help developers build reliable applications while preserving user control, transaction transparency, security, and compatibility.
Document Status: Active / Evolving
Maintained By: CeloHT Community
Primary Authors: Johnny Dubic & CeloHT Community
© 2026 CeloHT - Open Source. Global Impact. Licensed under Apache.