FAQ

Frequently asked questions about Oak Chain.

Why Oak Chain?

Why the project exists, why now, and the bets it makes, including what happens if Ethereum or adoption fails, are covered in the Thesis.

Understanding Oak Chain

Who runs the validators?

Anyone can run the open-source software or operate an independent cluster. Membership in a specific Aeron cluster is currently operator-configured; there is no deployed permissionless public validator network or automatic validator discovery/admission service.

How much do validators earn? What are the costs?

Operating costs include hardware, storage, bandwidth, and, in chain-backed mode, RPC and settlement costs. V5 fees accrue to one cluster treasury. The contract does not split fees among validators or guarantee revenue; treasury distribution is an off-chain operator policy.

See Smart Contract for the current contract boundary.

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)

Model 2: Oak Chain Connector (AEM Integration)

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:

Best practices:

Important: Consensus stores binary references, while bytes may be author-hosted or written to a validator-configured BlobStore. A CID proves identity, not availability; at least one reachable storage provider must retain the bytes.

See Binary Storage Guide for IPFS setup.

How does wallet-based sharding work?

Your content lives under a path derived from your wallet address:

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

You cannot choose the path or the cluster. Clusters can claim ranges of the first prefix level, and a validator with sharding turned on redirects writes for wallets another cluster owns. Sharding is off by default, and cross-cluster deployments are not yet validated.

See Content Paths for the rules.

Payments & Economics

Why do I need to pay?

In chain-backed (sepolia) mode, payments provide:

  1. Spam prevention. Cost deters abuse.
  2. Payment record. Each write's payment is an Ethereum transaction anyone can check.
  3. Quality filter. Only content worth publishing gets published.

In mock mode, the default, payments are simulated. Chain-backed payments are not yet validated.

Is Oak Chain for everything?

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

Data Table
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?

Pricing is flat: every settled write or delete costs the same, paid in ETH to the ValidatorPaymentV5 contract. Current prices, gas costs, and capability flags are on Smart Contract.

Can I use testnet for free?

Yes! Use Sepolia testnet with free test ETH:

See Testnet Guide for setup.

What if my payment fails?

In sepolia mode, validators verify the settlement before a queued write is released to consensus. Mock mode, the default, simulates payment.

Technical

How fast is it?

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

See Consensus Model for timing.

What's the maximum content size?

Organization names and other path rules are on Content Paths. Binary size limits for validator-hosted uploads are on Binary Storage. With author-hosted binaries, Oak Chain stores only the CID, so the file size is up to your storage.

Can I delete content?

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

What about abandoned or spam content?

This is a planned design, not something the validator does today. Today only the owning wallet can delete its content. The plan is cross-cluster garbage collection proposals:

Data Table
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:

Failover behavior depends on the Aeron configuration and deployment topology; no public production failover SLO is currently established. See Consensus Model.

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

Minimum: 3 validators (for fault tolerance)

Recommended: 5 validators (production)

Cluster size: current lifecycle evidence centers on fixed three- and five-node test topologies. Larger membership and multi-cluster scaling require deployment-specific validation; there is no published production maximum or linear-scaling guarantee.

See Operators Guide for cluster setup.

Can I migrate existing AEM content to Oak Chain?

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

The validator has no segment import route, so content goes in through write proposals.

Option 1: Content API Migration

Option 2: Gradual Migration

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?

Current performance evidence is limited to local, single-host validation and includes documented finalization and backpressure bottlenecks. No production throughput, linear cross-cluster scaling, constant read-latency, or failover SLO has been demonstrated. Benchmark the actual payload, storage, and network topology before publishing capacity claims.

How is my content secured?

  1. Wallet signature. Only you can write to your namespace (checked in sepolia mode; mock mode checks the format only).
  2. Raft consensus. Majority of validators must agree.
  3. Ethereum settlement. In chain-backed mode, payments are anchored to Ethereum.
  4. Replication. Content stored on multiple validators.

Can someone else write to my namespace?

In sepolia mode, no. Every write requires a signature from the namespace owner's wallet, and without your private key no one can:

In mock mode, the default, the validator checks only the signature format, so anyone who can reach it can write under any wallet. Run mock mode only on trusted networks.

What if I lose my wallet?

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

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

Is the code audited?

Oak Chain is built on:

The Oak Chain integration layer and payment contract are open source for review. This documentation records no independent audit.

Is Oak Chain GDPR/HIPAA compliant?

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

GDPR concerns:

HIPAA concerns:

Recommendations:

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:

Export options:

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

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

Integration

Does it work with AEM?

AEM 6.5 LTS can mount Oak Chain content read-only at /oak-chain through an opt-in composite mount; see AEM 6.5 LTS Integration. AEM as a Cloud Service is not supported. Inside AEM the mounted content is ordinary JCR:

Can I use it with React/Vue/etc?

Yes. Oak Chain exposes a REST API:

// Read content (clusterId comes from /v1/explorer/content/nav)
const response = await fetch(
  `http://validator:8090/v1/explorer/content/clusters/${clusterId}/node?path=/oak-chain/...`
);
const node = 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:

git clone https://github.com/somarc/oak-chain-infra.git
git clone https://github.com/somarc/jackrabbit-oak.git
cd oak-chain-infra && npm ci && npm link
export CLUSTER_RUNTIME_ROOT=/tmp/oak-chain
oak-chain mock up -- --fresh --build

See Operators Guide for production setup.

Can an organization use multiple wallets?

Yes. Organizations can use multiple wallets for:

Management:

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:

How it works:

Limitations:

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

Who pays Ethereum gas fees?

Authors pay for both:

  1. Settlement fees (to the configured cluster treasury in the V5 reference path)
  2. Gas fees (to Ethereum network) - Transaction costs

Measured gas costs are on Smart Contract.

What query languages are supported?

Current:

Planned:

Note: Oak Chain uses Oak's query engine, so standard JCR query syntax works. Queries execute against the local Oak segment store. In AEM, read /oak-chain by path: Oak's indexes do not cover the mount.

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

Available surfaces:

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

Are there rate limits on writes?

Yes. Validators rate-limit requests per client, per validator, and writes per wallet, and answer 429 when a limit is hit. See API Reference for the defaults. Beyond that:

Use Sepolia or local mock mode for development and dry-runs.

Can I transfer content ownership to another wallet?

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

Option 1: Re-publish

Option 2: Reference

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

Roadmap & Contributing

What's coming next?

See Status for what works today and what is planned.

How can I contribute?

See the project's GitHub repository for contribution guidance.

Still have questions?