FAQ

Frequently asked questions about Oak Chain.

The Big Questions

Why does this exist?

Oak Chain is built on two operating assumptions:

Ethereum is durable settlement infrastructure. BlackRock, Visa, and J.P. Morgan make it clear that onchain settlement and tokenized asset flows are now production concerns, not side experiments.
Oak is entrenched in enterprise content operations. Oak underpins AEM and sits inside large content, asset, and publishing estates that are expensive to replatform.

We're building the bridge for teams that want stronger proof, attribution, and economic authorization without throwing away the Oak model they already run.

→ Read the full thesis

Why now?

Because finance has modernized faster than content infrastructure.

Ethereum-style settlement moved into production while most enterprise content systems still rely on centralized trust boundaries.

Oak Chain targets that gap.

What if Ethereum fails?

Then a core premise of the project fails too.

This is a concentrated architectural bet, not a hedge. Oak Chain assumes Ethereum remains the leading programmable settlement layer.

If that assumption breaks, Oak Chain needs a different foundation.

What if no one uses this?

Then we were wrong on timing, wedge, or both.

That risk is real. The counterargument is that the underlying problem is coherent: some content workflows do need stronger proof, attribution, and durable authorization than today's default CMS stack provides.

If the market still rejects it, the system remains a serious distributed Oak implementation, but the strategic thesis would need to be reconsidered.

Understanding Oak Chain

Who runs the validators?

Anyone can run a validator node. The network is permissionless. Validators:

Receive ETH payments for storing content
Participate in Raft consensus
Replicate content across the network

How much do validators earn? What are the costs?

Earnings:

Validators receive a share of write fees paid by authors
Share varies by tier (PRIORITY pays more than STANDARD)
Distributed among cluster members (leader + followers)

Costs:

Hardware: 4-8 CPU cores, 8-16GB RAM, 100GB+ SSD (see Operators Guide)
Storage: Grows with content volume (Oak segments + IPFS CIDs)
Network: 100 Mbps+ bandwidth for replication
Ethereum RPC: Infura/Alchemy API costs (~$50-200/month)

Economics: Validator economics are designed to be sustainable—authors pay for storage, validators earn for providing it. Exact revenue depends on network usage and tier distribution.

See Economic Tiers for payment details.

Is my content public?

Yes, all content on Oak Chain is publicly readable. For private content, encrypt before storing.

What's the difference between SDK (Model 1) and AEM Connector (Model 2)?

Oak Chain offers two integration paths:

Model 1: Oak Chain SDK (Blockchain-Native)

For: New applications, modern web/mobile apps, EDS deployments
Technology: JavaScript/TypeScript SDK with REST API client
Integration: Direct HTTPS API calls to validators
Best when: Building from scratch, using React/Next.js, or deploying to Edge Delivery Services

Model 2: Oak Chain Connector (AEM Integration)

For: Existing Adobe Experience Manager customers
Technology: AEM package (OSGi bundle) using Oak's composite mount
Integration: JCR API via composite mount pattern (like Cold Standby)
Best when: Already running AEM 6.5+ or AEM Cloud Service, want to keep existing workflows

Both models connect to the same validator cluster. The difference is how your application accesses Oak Chain—SDK for new apps, Connector for existing AEM.

See Architecture for detailed comparison.

What happens if my IPFS node goes down?

IPFS is decentralized—if your node goes down, binaries remain available if:

Other IPFS nodes have pinned your content
IPFS gateways (ipfs.io, Cloudflare, Pinata) cached your CID
CDN edge caches have the binary

Best practices:

Use a pinning service (Pinata, Infura IPFS, web3.storage) for redundancy
Pin important binaries on multiple IPFS nodes
Use IPFS gateways as fallback (configured in your application)

Important: Validators store only CIDs (46 bytes), not binaries. If all IPFS nodes lose a binary, you'll need to re-upload it, but the CID reference in Oak Chain remains valid.

See Binary Storage Guide for IPFS setup.

How does wallet-based sharding work?

Content is assigned to an authoritative cluster based on the wallet-derived namespace prefix:

text

/oak-chain/{L1}/{L2}/{L3}/0x{wallet}/...

Clusters own explicit ranges of that wallet namespace. A write must go to the cluster that owns the wallet prefix; other clusters redirect before queueing.

You cannot choose which cluster stores your content—assignment is deterministic and automatic. This ensures:

Fair distribution across clusters
Consistent routing (same wallet → same cluster)
Fault isolation (issues contained to shard)

Path structure reflects sharding:

/oak-chain/{L1}/{L2}/{L3}/0x{wallet}/...

The {L1}/{L2}/{L3} prefix (first 6 hex chars) is the canonical wallet path root used for ownership and routing.

Operationally:

your authoritative cluster is the only place your namespace is writable
other clusters can still read your content through lazy read-only mounts
discovery of remote clusters is a separate control plane, not consensus

See Content Paths for details.

Payments & Economics

Why do I need to pay?

Payments provide:

Spam prevention. Cost deters abuse.
Validator incentives. Operators earn for storage.
Economic finality. Ethereum secures the network.
Quality filter. Only content worth publishing gets published.

Is Oak Chain for everything?

No. Oak Chain is for published content meant to be seen and shared.

Use Case	Oak Chain?	Why
Public website	✅ Yes	Meant to be seen
Product catalog	✅ Yes	Shared with customers
Press releases	✅ Yes	Public announcements
Internal drafts	❌ No	Keep on enterprise AEM
Dev/test content	❌ No	Use testnet or local
Bulk data dumps	❌ No	Economically prohibitive

The economic filter: Writing costs ETH. This naturally curates the network. You won't pay to store garbage. But the network is open, so low-quality content isn't excluded, just discouraged by cost.

Think of it like publishing: You could print anything, but printing costs money, so you publish what matters.

How much does it cost?

Current v1 prices come from the ValidatorPaymentV3_2 contract. These classes set payment amount, but they are not a public latency SLA.

Tier	ETH Price	USDC Price
PRIORITY	0.01 ETH	32.50 USDC
EXPRESS	0.002 ETH	6.50 USDC
STANDARD	0.001 ETH	3.25 USDC

Can I use testnet for free?

Yes! Use Sepolia testnet with free test ETH:

See Testnet Guide for setup.

What if my payment fails?

Transaction reverted → No charge, retry
Insufficient funds → Get more ETH, retry
Wrong contract class amount → Payment rejected, retry with the correct amount

Validators verify payment before accepting writes.

Technical

How fast is it?

Oak releases verified proposals through an adaptive packing buffer before Aeron consensus.

release timing depends on verification status, queue pressure, and Aeron health
Ethereum confirmation windows still matter for payment verification
payment class affects price, not a guaranteed wait time

What's the maximum content size?

Type	Limit
Single write	10 MB
Binary (IPFS)	Unlimited
Path depth	100 levels
Organization name	64 characters

For large files, upload to IPFS and store the CID in Oak Chain.

Can I delete content?

Yes. Submit a delete proposal with your wallet signature. The content is removed from the Oak tree, but:

Historical segments may retain data until compaction
IPFS binaries remain until unpinned
Blockchain payment records are permanent

What about abandoned or spam content?

Oak Chain introduces cross-cluster garbage collection proposals:

Scenario	Who Proposes	Outcome
Owner deletes	Content owner	Immediate removal
Abandoned content	Any cluster	Flagged for review
Spam/abuse	Validator consensus	Community decision

Since clusters mount each other read-only, they can observe content quality. If Cluster B sees spam in Cluster A's shard, Cluster B can propose deletion. The authoritative cluster (A) decides whether to accept.

This creates a community moderation layer without central authority. Clusters have economic incentive to maintain quality (validators want a reputable network).

What happens if a validator goes down?

Raft consensus handles failures automatically:

1 of 3 down: Network continues normally
2 of 3 down: Network pauses (no quorum)
Recovery: Failed nodes catch up via snapshot

Failover takes < 5 seconds.

What's the minimum cluster size? How many validators do I need?

Minimum: 3 validators (for fault tolerance)

1 can fail, network continues
2 failures = no quorum, network pauses

Recommended: 5 validators (production)

Can tolerate 2 failures
Better performance under load
More geographic distribution

Maximum per cluster: ~7-9 validators (Aeron Raft limit)

Beyond this, performance degrades
For scale, use sharding (multiple clusters)

Scaling strategy: Don't make one massive cluster. Shard into many small clusters (3-5 nodes each). This is how systems like EigenLayer DA, Espresso, and Near scale.

See Operators Guide for cluster setup.

Can I migrate existing AEM content to Oak Chain?

Yes, but migration tools are in development. Current options:

Option 1: Export/Import via Oak TAR

Export content from AEM as Oak TAR segments
Import segments to Oak Chain via validator API
Maintains JCR structure and metadata

Option 2: Content API Migration

Use AEM's Content Services API to read content
Write to Oak Chain via Connector or SDK
Requires custom migration script

Option 3: Gradual Migration

Install Oak Chain Connector in AEM
Mount /oak-chain read-only initially
Migrate content incrementally via write proposals

Note: Binary migration requires uploading binaries to IPFS first, then storing CIDs in Oak Chain.

Migration tooling is planned for future releases. See AEM Integration Guide for current integration options.

What's the read/write performance? How many writes per second?

Write throughput:

Single cluster: ~100-1000 writes/sec (depends on payload size)
Bottleneck: Ethereum finality (not Oak Chain itself)
Scaling: Add clusters via sharding for linear scale

Read performance:

Local reads: Sub-millisecond (from local Oak segments)
Remote reads: ~10-50ms (via HTTP segment transfer)
CDN cached: <10ms (edge delivery)

Release timing:

Adaptive-capacity scheduler decides when verified work is released
Ethereum confirmation windows still influence payment verification
payment class should not be read as a latency guarantee

Note: Oak Chain uses Aeron Raft, which can handle 100,000+ messages/sec at the messaging layer. Actual throughput depends on Oak segment store operations and Ethereum verification.

For high-throughput use cases, consider batching writes or using multiple clusters.

Security

How is my content secured?

Wallet signature. Only you can write to your namespace.
Raft consensus. Majority of validators must agree.
Ethereum finality. Payments anchored to Ethereum.
Replication. Content stored on multiple validators.

Can someone else write to my namespace?

No. Every write requires a signature from the namespace owner's wallet. Without your private key, no one can:

Create content under your wallet path
Modify your existing content
Delete your content

What if I lose my wallet?

Your content remains accessible (public reads), but you cannot:

Write new content to that namespace
Modify existing content
Delete content

Best practice: Use a hardware wallet and secure your seed phrase.

Is the code audited?

Oak Chain is built on:

Apache Jackrabbit Oak. 10+ years in production at Adobe.
Aeron Cluster. Used in financial trading systems.
Ethereum. Battle-tested smart contracts.

The Oak Chain integration layer is open source for review.

Current status: Oak Chain is public by design—all content is publicly readable. This creates compliance challenges:

GDPR concerns:

Right to erasure: Content can be deleted, but historical segments may persist until GC
Data portability: Content is exportable (Oak TAR format)
Data residency: Validators may be in any jurisdiction

HIPAA concerns:

Public accessibility: All content is readable by anyone
Encryption: Encrypt PHI before storing (Oak Chain doesn't encrypt at rest)
Audit trails: Blockchain provides immutable audit logs

Recommendations:

Encrypt sensitive data before storing in Oak Chain
Use Oak Chain for public content only (product catalogs, marketing)
Keep PHI/PII in private AEM instances
Consider private clusters for compliance-sensitive content

Future: Access control lists (ACLs) and encryption at rest are planned features.

Can I export my content? What format?

Yes. Oak Chain uses Oak TAR segment format, which is:

Standard Oak format (compatible with any Oak repository)
Exportable via validator API or Oak tools
Portable to other Oak-based systems

Export options:

TAR segments: Full repository export (segments + journal)
Content API: JSON export via REST API
JCR API: Standard JCR export (if using AEM Connector)

Migration away: You can export your content and import it into:

Another Oak Chain cluster
Standard AEM instance
Any Oak-based CMS

Note: IPFS binaries must be exported separately (download from IPFS by CID).

Integration

Does it work with AEM?

Yes! Oak Chain is designed for AEM compatibility:

Same JCR API
Same content model
Same Sling patterns
HTTP segment transfer (like Cold Standby)

Can I use it with React/Vue/etc?

Yes. Oak Chain exposes a REST API:

javascript

// Read content
const response = await fetch('http://validator:8090/api/explore?path=/oak-chain/...');
const content = await response.json();

// Write content (with wallet signature)
await fetch('http://validator:8090/v1/propose-write', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    proposalId: '0x1111111111111111111111111111111111111111111111111111111111111111',
    walletAddress: wallet,
    message: JSON.stringify(content),
    ethereumTxHash: txHash,
    signature,
  }),
});

Is there a JavaScript SDK?

There is a JavaScript package at somarc/oak-chain-sdk, but the write-side client is currently being realigned to the validator contract. For chain-backed writes today, prefer direct HTTP against the validator API with a client-supplied proposalId. See API Reference for the current HTTP contract.

Can I run my own cluster?

Yes! Oak Chain is open source. You can:

Run a private cluster for your organization
Join the public network as a validator
Fork and customize for your use case

bash

git clone https://github.com/somarc/oak-chain-infra.git
git clone https://github.com/somarc/jackrabbit-oak.git
cd oak-chain-infra
./modes/mock/validators/lifecycle/start-cluster.sh --build --fresh

See Operators Guide for production setup.

Can an organization use multiple wallets?

Yes. Organizations can use multiple wallets for:

Brand separation: Different wallets for different brands/products
Team isolation: Separate wallets per team/department
Security: Limit exposure if one wallet is compromised

Management:

Each wallet has its own namespace (/oak-chain/{L1}/{L2}/{L3}/0x{wallet}/...)
Content is isolated per wallet
No built-in cross-wallet management UI (use your own tooling)

Best practice: Use a wallet management system (like MetaMask's account switching or a multi-sig wallet) to manage multiple wallets.

Is there content versioning?

Current status: Oak Chain uses Oak's immutable segment store, which provides:

Revision history: Every write creates a new revision
Access via revision: Can read content at specific revisions
JCR versioning: Not yet implemented (planned feature)

How it works:

Each write creates a new revision (like Git commits)
Previous revisions remain accessible until GC
Revision access via HTTP is not yet exposed (planned).

Limitations:

No JCR versioning API yet (planned)
No version labels or branches
GC may remove old revisions (configurable retention)

Future: Full JCR versioning support is planned, including version labels, checkpoints, and version history APIs.

Who pays Ethereum gas fees?

Authors pay for both:

Write fees (to Oak Chain validators) - ETH payment to smart contract
Gas fees (to Ethereum network) - Transaction costs

Gas costs:

Write proposal transaction: ~85,000-220,000 gas
At ~20 gwei: ~$2-5 per write (varies with network congestion)
Not included in Oak Chain write fees

Optimization: Use Layer 2 (Arbitrum, Optimism) or batch transactions to reduce gas costs.

Note: Oak Chain write fees are separate from Ethereum gas. You pay both.

What query languages are supported?

Current:

JCR queries (XPath, SQL-2) - via AEM Connector
REST API - JSON responses for content reads
SSE streaming - Real-time content feed

Planned:

GraphQL API - For flexible queries
Full-text search - Via Oak indexes

Note: Oak Chain uses Oak's query engine, so standard JCR query syntax works. Queries execute against the local Oak segment store (fast) or remote clusters via composite mounts.

How do I monitor my content? What metrics are available?

Available metrics:

Validator dashboard: http://validator:8090/ - Cluster status, peers, latest epoch
Prometheus metrics: http://validator:8090/metrics - Write throughput, storage, cluster state
Health endpoint: http://validator:8090/health - Node health status

Metrics include:

oak_chain_writes_total{tier="..."} - Write count by tier
oak_chain_cluster_role - Leader/follower status
oak_chain_cluster_term - Raft term number
oak_chain_storage_bytes - Storage usage

Grafana dashboards: Production dashboards in development. See Operators Guide for current monitoring setup.

Are there rate limits on writes?

No hard rate limits, but practical constraints:

Adaptive release: Queue pressure and Aeron health govern release timing
Raft consensus: ~100-1000 writes/sec per cluster (depends on payload)
Gas costs: High-frequency writes become expensive

Best practices:

Batch writes when possible (multiple nodes in one proposal)
Choose the payment class that fits your economics and workflow
Distribute across clusters via sharding for higher throughput

Note: Spam prevention comes from economic cost (ETH payments), not rate limits.

Can I transfer content ownership to another wallet?

Not directly. Content is tied to the wallet that created it. Options:

Option 1: Re-publish

Export content from old wallet namespace
Re-publish to new wallet namespace (pays write fees again)
Old content remains (but orphaned)

Option 2: Reference

Keep content in original wallet
Create references/links from new wallet namespace
Cross-wallet references work via composite mounts

Future: Content ownership transfer is a planned feature, allowing wallet-to-wallet transfers with proper authorization.

Roadmap & Contributing

What's coming next?

[ ] GraphQL API
[ ] Content versioning
[ ] Access control lists
[ ] Mainnet launch

How can I contribute?

Code: github.com/somarc/oak-chain-docs
Docs: Edit any page (link at bottom)
Feedback: Open an issue

See Contributing guide.

Still have questions?

GitHub Issues: github.com/somarc/oak-chain-docs/issues
Documentation: Browse the sidebar
Source Code: github.com/somarc

FAQ ​

The Big Questions ​

Why does this exist? ​

Why now? ​

What if Ethereum fails? ​

What if no one uses this? ​

Understanding Oak Chain ​

Who runs the validators? ​

How much do validators earn? What are the costs? ​

Is my content public? ​

What's the difference between SDK (Model 1) and AEM Connector (Model 2)? ​

What happens if my IPFS node goes down? ​

How does wallet-based sharding work? ​

Payments & Economics ​

Why do I need to pay? ​

Is Oak Chain for everything? ​

How much does it cost? ​

Can I use testnet for free? ​

What if my payment fails? ​

Technical ​

How fast is it? ​

What's the maximum content size? ​

Can I delete content? ​

What about abandoned or spam content? ​

What happens if a validator goes down? ​

What's the minimum cluster size? How many validators do I need? ​

Can I migrate existing AEM content to Oak Chain? ​

What's the read/write performance? How many writes per second? ​

Security ​

How is my content secured? ​

Can someone else write to my namespace? ​

What if I lose my wallet? ​

Is the code audited? ​

Is Oak Chain GDPR/HIPAA compliant? ​

Can I export my content? What format? ​

Integration ​

Does it work with AEM? ​

Can I use it with React/Vue/etc? ​

Is there a JavaScript SDK? ​

Can I run my own cluster? ​

Can an organization use multiple wallets? ​

Is there content versioning? ​

Who pays Ethereum gas fees? ​

What query languages are supported? ​

How do I monitor my content? What metrics are available? ​

Are there rate limits on writes? ​

Can I transfer content ownership to another wallet? ​

Roadmap & Contributing ​

What's coming next? ​

How can I contribute? ​

Still have questions? ​

FAQ