Skip to content

feat: Expand documentation with tutorials, guides, and API references #136

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
caxtonacollins wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: Expand documentation with tutorials, guides, and API references #136

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
904 changes: 904 additions & 0 deletions docs/api/core-sdk.md
View file
Open in desktop

Large diffs are not rendered by default.

118 changes: 118 additions & 0 deletions docs/architecture/adrs/001-monorepo-structure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
# ADR 001: Monorepo Structure with pnpm Workspaces

## Status
Accepted

## Context
ChenAIKit consists of multiple interconnected packages (core SDK, CLI, backend, frontend, examples) that share code and dependencies. We needed to decide on a repository structure that would:

- Enable code sharing between packages
- Simplify dependency management
- Support independent versioning
- Facilitate coordinated releases
- Improve developer experience

## Decision
We will use a monorepo structure managed by pnpm workspaces.

### Repository Structure
```
chenaikit/
├── packages/
│ ├── core/ # Core TypeScript SDK
│ └── cli/ # CLI tool
├── backend/ # Backend services
├── frontend/ # Frontend applications
├── contracts/ # Soroban smart contracts
├── examples/ # Sample applications
├── docs/ # Documentation
└── tests/ # Shared test utilities
```

### Workspace Configuration
```json
{
"workspaces": [
"packages/*",
"examples/*",
"tests/*"
]
}
```

## Consequences

### Positive
- **Code Sharing**: Packages can easily import from each other using workspace protocol (`workspace:*`)
- **Dependency Management**: Single `pnpm-lock.yaml` ensures consistent versions
- **Atomic Changes**: Changes across multiple packages can be committed together
- **Simplified CI/CD**: Single repository to clone and test
- **Better Refactoring**: IDE support for cross-package refactoring
- **Faster Development**: No need to publish packages locally for testing

### Negative
- **Build Complexity**: Need to manage build order and dependencies
- **Larger Repository**: More code to clone initially
- **CI Time**: All packages tested even if only one changes (mitigated with change detection)
- **Learning Curve**: Developers need to understand workspace concepts

### Neutral
- **Tooling**: Requires pnpm (not npm/yarn) for workspace features
- **Scripts**: Need root-level scripts to coordinate package operations

## Alternatives Considered

### Multi-repo (Separate Repositories)
- **Pros**: Clear boundaries, independent releases, smaller clones
- **Cons**: Difficult code sharing, version management complexity, harder to coordinate changes
- **Rejected**: Too much overhead for our team size and release cadence

### Lerna + npm/yarn
- **Pros**: More mature tooling, wider adoption
- **Cons**: Slower than pnpm, more complex configuration, less efficient disk usage
- **Rejected**: pnpm workspaces are simpler and faster

### Nx Monorepo
- **Pros**: Advanced caching, task orchestration, change detection
- **Cons**: Additional complexity, opinionated structure, learning curve
- **Rejected**: Overkill for our current needs, can migrate later if needed

## Implementation Notes

### Package References
Packages reference each other using workspace protocol:
```json
{
"dependencies": {
"@chenaikit/core": "workspace:*"
}
}
```

### Build Scripts
Root package.json includes coordinated scripts:
```json
{
"scripts": {
"build": "pnpm -r build",
"test": "pnpm -r test",
"lint": "pnpm -r lint"
}
}
```

### CI/CD Strategy
- Use pnpm's built-in change detection
- Cache node_modules and build artifacts
- Run tests in parallel where possible

## References
- [pnpm Workspaces Documentation](https://pnpm.io/workspaces)
- [Monorepo Best Practices](https://monorepo.tools/)
- [Why pnpm?](https://pnpm.io/motivation)

## Date
2024-10-04

## Authors
ChenAIKit Team
200 changes: 200 additions & 0 deletions docs/architecture/adrs/002-stellar-soroban-blockchain.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,200 @@
# ADR 002: Stellar and Soroban for Blockchain Layer

## Status
Accepted

## Context
ChenAIKit requires blockchain functionality for:
- Decentralized credit scoring storage
- Transparent fraud detection records
- Immutable transaction history
- Smart contract execution for business logic
- Cross-border payment capabilities

We needed to choose a blockchain platform that provides:
- Smart contract capabilities
- Low transaction costs
- Fast finality
- Good developer experience
- Active ecosystem

## Decision
We will use Stellar as our primary blockchain platform with Soroban for smart contracts.

### Technology Stack
- **Stellar Network**: Layer 1 blockchain for payments and asset issuance
- **Soroban**: Smart contract platform built on Stellar
- **Horizon API**: REST API for Stellar network interaction
- **Stellar SDK**: JavaScript/TypeScript SDK for client applications
- **Rust**: Programming language for Soroban contracts

## Rationale

### Why Stellar?

1. **Low Cost**: Transaction fees are ~$0.00001, making it economical for high-volume operations
2. **Fast Finality**: 3-5 second transaction confirmation
3. **Built-in DEX**: Native decentralized exchange for asset trading
4. **Asset Issuance**: Easy creation of custom tokens
5. **Compliance**: Built-in compliance features (authorized accounts, clawback)
6. **Mature Ecosystem**: 8+ years of production use

### Why Soroban?

1. **Modern Language**: Rust provides memory safety and performance
2. **WebAssembly**: Contracts compile to WASM for portability
3. **Stellar Integration**: Native access to Stellar accounts and assets
4. **Developer Experience**: Excellent tooling and documentation
5. **Cost Efficiency**: Optimized for low gas costs
6. **Security**: Strong type system and ownership model

## Consequences

### Positive
- **Low Operational Costs**: Minimal fees for transactions and contract execution
- **Fast User Experience**: Quick transaction finality improves UX
- **Rich Functionality**: Access to DEX, multi-sig, and asset features
- **Developer Productivity**: Rust's tooling and safety features
- **Ecosystem Support**: Active community and extensive documentation
- **Compliance Ready**: Built-in features for regulatory requirements

### Negative
- **Learning Curve**: Developers need to learn Rust and Soroban
- **Ecosystem Size**: Smaller than Ethereum (but growing rapidly)
- **Contract Limitations**: Some restrictions compared to EVM chains
- **Tooling Maturity**: Soroban is newer than established platforms

### Neutral
- **Network Effects**: Need to build on Stellar's existing ecosystem
- **Interoperability**: Limited direct bridges to other chains (can be added)

## Alternatives Considered

### Ethereum + Solidity
- **Pros**: Largest ecosystem, most developers, extensive tooling
- **Cons**: High gas fees ($5-50+ per transaction), slower finality (12-15s), complex development
- **Rejected**: Cost prohibitive for our use case

### Polygon/L2 Solutions
- **Pros**: Lower fees than Ethereum, EVM compatibility
- **Cons**: Still higher fees than Stellar, additional complexity, bridge risks
- **Rejected**: Stellar provides better cost/performance ratio

### Solana + Rust
- **Pros**: Very fast, low fees, Rust-based
- **Cons**: Network stability concerns, complex programming model, less mature tooling
- **Rejected**: Stellar offers better stability and developer experience

### Cosmos SDK
- **Pros**: Flexible, IBC for interoperability, Rust support
- **Cons**: Need to run own chain or find suitable zone, higher operational complexity
- **Rejected**: Too much infrastructure overhead

## Implementation Details

### Smart Contracts
We implement three core contracts in Soroban:

1. **Credit Score Contract**
- Store and calculate credit scores
- Access control for score updates
- Oracle integration for external data

2. **Fraud Detection Contract**
- Pattern recognition and risk scoring
- Alert generation
- Historical fraud data storage

3. **Governance Contract**
- Voting mechanisms
- Timelock for critical operations
- Proposal management

### Backend Integration
```typescript
import { StellarConnector } from '@chenaikit/core';

const stellar = new StellarConnector({
network: 'mainnet',
horizonUrl: 'https://horizon.stellar.org'
});

// Interact with contracts
const score = await stellar.invokeContract(
contractId,
'calculate_score',
[accountAddress]
);
```
Comment on lines +114 to +128
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify StellarConnector methods in actual implementation
ast-grep --pattern 'class StellarConnector {
  $$$
}'

Repository: nexoraorg/chenaikit

Length of output: 2010

Remove or clarify the invokeContract example — it does not exist in the current StellarConnector implementation.

The code snippet calls stellar.invokeContract(), but the actual StellarConnector class in packages/core/src/stellar/connector.ts only provides getAccount, submitTransaction, getFee, and getNetworkPassphrase. Update the example to use available methods, add a note explaining this is planned API for a future release, or implement the missing method before merge.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/architecture/adrs/002-stellar-soroban-blockchain.md` around lines 114 -
128, The docs example incorrectly calls StellarConnector.invokeContract which
doesn't exist; update the snippet to use the actual API
(StellarConnector.getAccount and StellarConnector.submitTransaction, and
optionally StellarConnector.getFee/getNetworkPassphrase) or explicitly mark
invokeContract as a planned/future API. Replace the invokeContract call with a
brief example that retrieves an account via getAccount and submits a transaction
via submitTransaction (using getFee/getNetworkPassphrase as needed), and/or add
a short note that invokeContract is not implemented in StellarConnector yet and
will be provided in a future release.


### Network Strategy
- **Development**: Stellar testnet for development and testing
- **Staging**: Stellar testnet with production-like data
- **Production**: Stellar mainnet (public network)

## Migration Path

If we need to support additional blockchains in the future:

1. **Abstract Blockchain Layer**: Create interface for blockchain operations
2. **Adapter Pattern**: Implement adapters for each blockchain
3. **Multi-Chain Support**: Allow users to choose their preferred chain
4. **Bridge Contracts**: Enable cross-chain functionality

```typescript
interface BlockchainAdapter {
deployContract(wasm: Buffer): Promise<string>;
invokeContract(id: string, method: string, args: any[]): Promise<any>;
getAccount(address: string): Promise<Account>;
}

class StellarAdapter implements BlockchainAdapter { /* ... */ }
class EthereumAdapter implements BlockchainAdapter { /* ... */ }
```

## Performance Considerations

### Transaction Throughput
- Stellar: ~1000 TPS (operations per second)
- Sufficient for our current scale
- Can batch operations for efficiency

### Contract Execution
- Soroban contracts execute in milliseconds
- Gas costs are predictable and low
- Optimization techniques available (WASM size reduction)

### Data Storage
- Use contract storage for critical data
- Use Horizon API for historical queries
- Cache frequently accessed data in backend

## Security Considerations

### Contract Security
- Comprehensive testing with Soroban SDK test utilities
- Access control on all sensitive operations
- Upgrade mechanisms for bug fixes
- External security audits before mainnet deployment

### Key Management
- Use Stellar's multi-signature capabilities
- Hardware wallet support for production keys
- Separate keys for different environments

### Network Security
- Use HTTPS for all Horizon API calls
- Validate all transaction signatures
- Implement rate limiting on contract calls

## References
- [Stellar Documentation](https://developers.stellar.org/)
- [Soroban Documentation](https://soroban.stellar.org/docs)
- [Stellar Consensus Protocol](https://www.stellar.org/papers/stellar-consensus-protocol)
- [Soroban by Example](https://soroban.stellar.org/docs/examples)

## Date
2024-10-04

## Authors
ChenAIKit Team
Loading
Loading