ICore Developer SDK

Build constitutional software with the ICore platform. Write once, run anywhere — from browser WASM to native CLI.

📘 What is ICore?

ICore is a constitutional computing platform. It provides a substrate for building software that is verifiable, auditable, and trust-preserving. The SDK gives you access to all ICore capabilities through a clean, Rust-native API.

Platform Components

⚙️ UCK Kernel

Core operations: execute, communicate, persist, verify

📘 SDK

Developer-friendly API over UCK

🤖 Agents

Autonomous constitutional agents

📦 UMS

Publish and install packages

🔗 TrustChain

Cryptographic trust and attestation

🔬 CITS

355 conformance invariants

Supported Runtimes

Runtime	Status	Use Case
Rust (native)	Stable	Full platform, CLI tools, servers
WebAssembly	Stable	Browser, UCF Engineering
JavaScript/WASM	Supported	Browser apps, PWAs
Zig	Planned	Binary tools, embedded

Quick Start

Get up and running with ICore in 3 minutes.

1

Add ICore to your project

TOML

[dependencies]
uck = { path = "../UCK" }
constitutional-sdk = { path = "../constitutional-sdk" }

2

Build and execute

Rust

use constitutional_sdk::{KernelBuilder, ReceiptExt};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Build the kernel
    let kernel = KernelBuilder::new()
        .epoch(1722086400)
        .build();

    // Execute an operation
    let receipt = kernel.execute(
        "my-component",
        uck::ExecutionMode::Deterministic,
        "hello-constitutional-world",
    )?;

    // Print the receipt
    println!("Operation: {}", receipt.base.operation_id);
    println!("Hash: {}", receipt.base.hash);
    println!("Verified: {}", kernel.verify(&receipt)?);

    Ok(())
}

3

Run it

Shell

$ cargo run
Operation: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Hash: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0...
Verified: true

✓ That's it!

You've executed a constitutional operation with cryptographic verification. Every operation produces a receipt that can be independently verified.

Installation

From Source (Recommended)

Shell

# Clone the ICore repository
git clone https://ucf.initialcore.net/icore/icore-gate-kernel
cd icore-gate-kernel

# Build all crates
cargo build --release

# Run the test suite (289+ tests)
cargo test --all

As a Dependency

TOML

[dependencies]
# Core kernel
uck = { path = "../UCK" }

# SDK (recommended for most users)
constitutional-sdk = { path = "../constitutional-sdk" }

# Individual components
ucn = { path = "../UCN" }          # Network
ucd = { path = "../UCD" }          # Data
trust-chain = { path = "../TrustChain" }  # Trust
corefab = { path = "../USR-CoreFab" }    # Execution

WebAssembly

Shell

# Install wasm-pack
cargo install wasm-pack

# Build the UCF WASM core
cd ucf-core
wasm-pack build --target web --release

# Output: pkg/ucf_core_bg.wasm (183KB)

System Requirements

Rust 1.70+, Cargo, wasm-pack (for WASM). No external services required — ICore is fully sovereign.

Architecture

ICore follows a layered architecture with constitutional invariants at every level.

Diagram

┌─────────────────────────────────────────────────┐
│                  Applications                    │
│         (Agents, Tools, PWAs, CLI)              │
├─────────────────────────────────────────────────┤
│              Constitutional SDK                  │
│    KernelBuilder · ConstitutionalAgent ·         │
│    ReceiptExt · FlowReceipts                     │
├─────────────────────────────────────────────────┤
│            Universal Constitutional Kernel        │
│    execute() · communicate() · persist() ·       │
│    verify()                                      │
├──────────┬──────────┬──────────┬────────────────┤
│  UCN     │  UCD     │ TrustChain │ CoreFab      │
│ Network  │ Data     │ Trust      │ Execution    │
├──────────┴──────────┴──────────┴────────────────┤
│            Constitutional Substrate               │
│    Content-addressing · Ed25519 · SHA-256        │
│    Receipt chains · Epochs · Determinism         │
└─────────────────────────────────────────────────┘

Key Design Principles

Constitutional ordering: Define → Implement → Validate → Publish
Content-addressing: All data is identified by SHA-256 hash
Tamper-evidence: Every operation produces a verifiable receipt
Determinism: Same input → same output, always
Sovereignty: No external services, no servers, no dependencies

UCK Kernel API

The Universal Constitutional Kernel provides four core operations.

`execute()`

Execute a constitutional operation and produce a receipt.

Parameter	Type	Description
`component`	`&str`	Component identifier
`mode`	`ExecutionMode`	Deterministic or NonDeterministic
`operation`	`&str`	Operation description

Returns: Result<Receipt>

`communicate()`

Send data between constitutional components.

Parameter	Type	Description
`source`	`&str`	Source component
`target`	`&str`	Target component
`payload`	`&str`	Data payload
`epoch`	`u64`	Current epoch

Returns: Result<FlowReceipts>

`persist()`

Store data with content-addressed integrity.

Parameter	Type	Description
`key`	`&str`	Storage key
`data`	`&[u8]`	Data to store
`epoch`	`u64`	Current epoch

Returns: Result<Receipt>

`verify()`

Verify the integrity of a receipt.

Parameter	Type	Description
`receipt`	`&Receipt`	Receipt to verify

Returns: Result<bool>

SDK API Reference

KernelBuilder

Ergonomic constructor for the Constitutional Kernel.

Rust

let kernel = KernelBuilder::new()
    .epoch(1722086400)      // Set epoch
    .build();                // Build the kernel

// Or with defaults
let kernel = KernelBuilder::new().build();

ConstitutionalAgent Trait

Implement this trait to create a constitutional agent.

Rust

pub trait ConstitutionalAgent {
    fn name(&self) -> &str;
    fn purpose(&self) -> &str;
    fn minimum_trust_level(&self) -> TrustLevel;
    fn execute(&self, input: &str)
        -> Result<String, Box<dyn Error>>;
    fn communicate(&self, source: &str, target: &str,
        payload: &str, epoch: u64)
        -> Result<FlowReceipts, Box<dyn Error>>;
}

ReceiptExt

Extension methods for receipt serialization.

Method	Returns	Description
`.to_json()`	`String`	Serialize receipt to JSON
`.to_pretty_json()`	`String`	Pretty-printed JSON
`.checksum()`	`String`	SHA-256 of receipt content

Guide: Build an Agent

Create a constitutional agent in 5 steps.

1

Define your agent struct

Rust

pub struct MyAgent {
    name: String,
    kernel: Kernel,
}

impl MyAgent {
    pub fn new(name: &str) -> Self {
        Self {
            name: name.to_string(),
            kernel: KernelBuilder::new().build(),
        }
    }
}

2

Implement the ConstitutionalAgent trait

Rust

impl ConstitutionalAgent for MyAgent {
    fn name(&self) -> &str { &self.name }
    fn purpose(&self) -> &str { "Performs custom operations" }
    fn minimum_trust_level(&self) -> TrustLevel {
        TrustLevel::Verified
    }
    fn execute(&self, input: &str) -> Result<String, Box<dyn Error>> {
        let receipt = self.kernel.execute(
            &self.name,
            ExecutionMode::Deterministic,
            input,
        )?;
        Ok(format!("Executed: {}", receipt.base.hash))
    }
    fn communicate(&self, src: &str, tgt: &str, payload: &str, epoch: u64)
        -> Result<FlowReceipts, Box<dyn Error>>
    {
        self.kernel.communicate(src, tgt, payload, epoch)
    }
}

3

Add your manifest

JSON

{
  "name": "my-agent",
  "version": "1.0.0",
  "category": "agent",
  "conformance_level": "L2",
  "dependencies": [{ "name": "uck", "version_req": ">=2.0.0" }]
}

4

Write tests

Rust

#[test]
fn agent_executes() {
    let agent = MyAgent::new("test-agent");
    let result = agent.execute("test-input").unwrap();
    assert!(result.contains("Executed:"));
}

#[test]
fn agent_communicates() {
    let agent = MyAgent::new("test-agent");
    let flow = agent.communicate("a", "b", "data", 1).unwrap();
    assert!(!flow.hash.is_empty());
}

5

Publish to UMS

Shell

# Build and publish
cargo build --release
ums publish --manifest manifest.json --sign key.pem

Guide: Publish to UMS

Share your constitutional packages with the world.

Package Requirements

Manifest: Valid manifest.json with name, version, category
Signature: Ed25519 signed by the author's key
Checksum: SHA-256 of package content
Conformance: At least L1 conformance level

Publish Flow

Shell

# 1. Build your package
cargo build --release

# 2. Generate signing key (first time only)
ums keygen --output my-key.pem

# 3. Create manifest
ums init --name my-pkg --version 1.0.0 --category library

# 4. Sign and publish
ums publish --manifest manifest.json --sign my-key.pem

# 5. Verify it's live
ums info my-pkg

✓ Your package is now live

Visit ums.initialcore.net to see your package in the registry.

Guide: Conformance Testing

Verify your implementation meets ICore standards.

Conformance Levels

Level	Name	Requirements
L0	Non-Compatible	Does not meet any requirements
L1	Core Compatible	Kernel operations work correctly
L2	Science Compatible	Full SDK + agents + receipts
L3	Fully Compatible	All 355 CITS invariants pass

Running Tests

Shell

# Run full conformance suite
cargo test --all

# Run specific test suites
cargo test --package ums          # UMS tests
cargo test --package UCK          # Kernel tests
cargo test --package CITS-Integration  # System-level tests

# Check conformance level
cits check --target ./target/release/my-impl

⚠ Self-conformance caveat

Running ICore's own tests against ICore proves internal consistency, not independent validation. For true validation, independent review and cross-implementation testing are needed.

Guide: Third-Party Integration

Integrate ICore into your existing systems.

Integration Points

Component	API	Protocol
UCK Kernel	Rust trait	In-process
WASM Core	JavaScript	Browser API
UMS Registry	REST	HTTPS
UCF Forge	Web UI	Browser

Minimal Integration

Rust

// Add ICore to your project
use uck::{ConstitutionalKernel, ExecutionMode};

fn main() {
    let kernel = uck::ConstitutionalKernel::new();

    // Execute a constitutional operation
    let receipt = kernel.execute(
        "my-system",
        ExecutionMode::Deterministic,
        "operation-name",
    ).expect("Operation failed");

    // Verify the receipt
    assert!(kernel.verify(&receipt).expect("Verification failed"));
    println!("✓ Operation verified: {}", receipt.base.hash);
}

Conformance Requirements

Implement all four UCK operations
Produce valid receipts for every operation
Pass CCS invariants (at least L1)
Use Ed25519 for signing
Use SHA-256 for content addressing

Type Reference

Receipt

Field	Type	Description
`operation_id`	`String`	Unique operation identifier (UUID)
`hash`	`String`	SHA-256 content hash
`parent_hash`	`Option<String>`	Previous receipt hash (chain)
`timestamp`	`u64`	Unix timestamp
`epoch`	`u64`	Constitutional epoch
`mode`	`ExecutionMode`	Deterministic or NonDeterministic
`component`	`String`	Component that produced receipt
`operation`	`String`	Operation description

FlowReceipts

Field	Type	Description
`source`	`String`	Source component
`target`	`String`	Target component
`payload`	`String`	Data payload
`hash`	`String`	SHA-256 of flow
`epoch`	`u64`	Constitutional epoch

ExecutionMode

Variant	Description
`Deterministic`	Same input always produces same output
`NonDeterministic`	Output may vary (e.g., I/O operations)

Error Codes

Error	Code	Description
`KernelError`	1001	General kernel error
`InvalidReceipt`	1002	Receipt verification failed
`ComponentNotFound`	1003	Referenced component doesn't exist
`EpochMismatch`	1004	Epoch is not monotonically increasing
`TrustViolation`	1005	Insufficient trust level
`DataCorruption`	1006	Data integrity check failed
`CircularDependency`	1007	Circular dependency detected

Trust Levels

Level	Score	Description
Unknown	0	No trust established
Community	1	Published by community member
Verified	2	Identity verified by TrustChain
Official	3	Official ICore release
Core	4	Core substrate component

Conformance Levels

Level	Name	Tests Required
L0	Non-Compatible	None
L1	Core Compatible	CCS core operations
L2	Science Compatible	CCS + SDK + agents
L3	Fully Compatible	All 355 CITS invariants

Testing Framework

ICore includes a comprehensive testing framework for constitutional software.

Running Tests

Shell

# Run all tests (341+ tests)
cargo test --all

# Run with the test runner
bash automation/test-all.sh

# Run specific crate
cargo test --package UCK
cargo test --package ums
cargo test --package constitutional-sdk

Test Categories

Category	Crate	Tests	What it tests
ISP	libisp-core, libisp-dht	82	Inter-System Protocol
Core	USR-CoreFab, UCN, UCD, TrustChain	76	Core constitutional crates
Integration	Integration, CITS-Integration	67	Cross-module + system-level
Kernel	UCK	20	Universal Constitutional Kernel
SDK	constitutional-sdk	14	Developer SDK
Agents	reference-agents	14	Reference constitutional agents
Properties	property-measurement	6	Constitutional properties
Third-Party	third-party	10	Third-party enablement
UMS	ums	52	Universal Module System

Checksum Calculator

Compute SHA-256 checksums for your data.

Getting Started

Core APIs

Guides

Reference

Tools

ICore Developer SDK

Platform Components

⚙️ UCK Kernel

📘 SDK

🤖 Agents

📦 UMS

🔗 TrustChain

🔬 CITS

Supported Runtimes

Quick Start

Add ICore to your project

Build and execute

Run it

Installation

From Source (Recommended)

As a Dependency

WebAssembly

Architecture

Key Design Principles

UCK Kernel API

execute()

communicate()

persist()

verify()

SDK API Reference

KernelBuilder

ConstitutionalAgent Trait

ReceiptExt

Guide: Build an Agent

Define your agent struct

Implement the ConstitutionalAgent trait

Add your manifest

Write tests

Publish to UMS

Guide: Publish to UMS

Package Requirements

Publish Flow

Guide: Conformance Testing

Conformance Levels

Running Tests

Guide: Third-Party Integration

Integration Points

Minimal Integration

Conformance Requirements

Type Reference

Receipt

FlowReceipts

ExecutionMode

Error Codes

Trust Levels

Conformance Levels

Testing Framework

Running Tests

Test Categories

Checksum Calculator

`execute()`

`communicate()`

`persist()`

`verify()`