Build on Kepto

Kepto puts public asset state and backing commitments on-chain so they can be inspected independently. It is three products on one settlement layer: equity markets with a mainnet synthetic trade path and separate testnet contract prototypes, real-world assets bound to active, challengeable storage-deal commitments, andverifiable storage with on-chain Merkle roots and economic spot checks. Everything is priced and settled in KEP on Robinhood Chain, an EVM-compatible Arbitrum Orbit L2.

The difference from a normal broker or storage host is that the recorded state is readable on-chain at any moment, not promised in a quarterly PDF. Supply is capped by the issuer's on-chain reserve figure, storage challenges provide economic spot checks, and retrieved bytes are re-hashed against an on-chain root before they reach you. These checks do not independently audit an offchain reserve or guarantee future file availability.

The three pillars#

Actors#

Core contracts#

Cross-chain proof passports#

From an RWA, equity, or storage detail page, Publish cross-chain proof reviews the current public fields and a native ETH fee, then asks the source publisher to reread the canonical state during execution. Once verified publisher and receiver deployment records are configured, the resulting snapshot travels from Robinhood Chain Testnet through Chainlink CCIP to the authenticated receiver on Arbitrum Sepolia. Until then, the action fails closed. The preview is not the mined evidence, and snapshots are timestamped history rather than continuous sync. After a matching destination receipt is authenticated, these exact labels apply:

• Cross-chain proof delivered by Chainlink CCIP.
• A timestamped snapshot of Kepto's onchain asset and storage state.
• Verified on Arbitrum Sepolia from Robinhood Chain Testnet.

Chainlink transports and authenticates the cross-chain message. It does not verify legal title, custody, reserves, NAV or valuation, issuer attestations, documents, Robinhood-testnet equity prices, or future storage availability. Plaintext labels, URIs, documents, file bytes, keys, and private account data stay excluded, although hashes can still be correlated with public source state. Use Proofs for authenticated source events, CCIP message IDs, destination receipts, and updated snapshots.

Ways to integrate#

KEP is the settlement and coordination token of Kepto, with a fixed maximum supply of 1,000,000,000 tokens. It is non-mintable — no supply can ever be created after launch. Allocation:

Totals to 100% of the fixed 1,000,000,000 KEP supply. The token contract has no mint function, no owner-controlled inflation, and standard transfers are untaxed.

Mainnet dAAPL is a KEP-settled synthetic tracker of an oracle-published AAPL value. It is trade-only: Kepto does not custody Apple stock, and dAAPL provides no shareholder, voting, dividend, staking, or guaranteed NAV redemption right.

The contracts below are separate Robinhood Chain Testnet prototypes. Their ERC-20 tokens model issuer-configured equity records for testing; they do not establish legal title to a company. The testnet deployment includes twelve EquityToken examples, from dAAPL and dTSLA through dPLTR and dSPY, priced and traded in KEP. Their contracts enforce the supply, transfer, settlement, and reserve-cap rules described below.

Testnet Secure Mint and reserve cap#

Each testnet token carries an on-chain reserves figure the issuer attests to. Every mint runs through Secure Mint, which reverts unless totalSupply() + amount <= reserves. Tokens above that attested cap cannot be issued, and reservesRatioBps() reports the testnet contract ratio for anyone to read.

Testnet compliance-gated transfers#

Testnet transfers pass through a shared ComplianceRegistry. In blacklist mode (the current Robinhood Chain Testnet deployment default) tokens move freely except for frozen accounts, so the examples are composable across DeFi. Flip to allowlist mode and only verified addresses can hold, the permissioned pattern regulated issuers need. The registry also supports freeze, exempt, and delegated verification agents.

Testnet mint and redeem#

The testnet prototype uses an on-chain order queue so KEP and equity tokens are escrowed by the contract while an operator decides whether to fill an order.

1. 1
   Request
   You call requestMint(paymentKep); the contract escrows your KEP and records a pending order. Redeeming is the mirror, requestRedeem(amount) escrows your testnet equity tokens.
2. 2
   Fill
   The testnet operator may fill an order after its off-chain checks: fillMint issues tokens through Secure Mint and forwards KEP to the treasury; fillRedeem burns tokens and pays KEP. The contract does not guarantee that an operator will fill an order.
3. 3
   Or cancel
   While an order is still pending you can cancelOrder(id) and get your escrow back to the wei.

Testnet NAV and distribution functions#

The testnet navPerShare field records an issuer-attested value per token. Its pull-model distribution functions can allocate funded KEP: distributeDividend(amount) splits pro rata across every holder, withdrawableDividend(holder) reads what you are owed, and claimDividend() pays it out. The accounting corrects on every transfer. These testnet functions are not offered by the mainnet dAAPL trade-only release.

On-chain versus off-chain#

Try it#

# read a testnet equity token: reserve cap, NAV field, supply
KEPTO_CHAIN=robinhoodTestnet kepto equity token <dAAPL>

# request a mint by escrowing KEP (an operator fills it)
KEPTO_PRIVATE_KEY=0x... kepto equity mint <dAAPL> 300

# claim a funded testnet KEP distribution
KEPTO_PRIVATE_KEY=0x... kepto equity claim <dAAPL>

This section describes the Robinhood Chain Testnet EquityVault prototype only. Mainnet dAAPL is trade-only and has no public staking or dividend promise. On testnet, the vault locks equity tokens and mints an ERC-721 position NFT that records the position.

How APR is computed#

APR is read straight from chain state, never a marketing number. The vault exposes aprBps(stock), which annualizes the current emission rate against the value of everything staked, priced at navPerShare. As more shares stake, the same emission spreads wider and the APR falls; the figure the dashboard shows is exactly what the contract returns.

Yield-bearing NFTs#

Pending rewards are attached to the position NFT itself. Transfer the NFT and its accrued yield goes with it, so positions are tradable instruments, not just testnet receipts. earned(positionId) reports the configured reward and distribution, claimRewards(positionId) pays them out, and unstake(positionId) auto-claims everything and returns your exact locked testnet equity tokens.

Try it#

# see the live APR, total staked and reward rate for a stock
KEPTO_CHAIN=robinhoodTestnet kepto equity pool <dAAPL>

# stake shares, then check and claim what you have earned
KEPTO_PRIVATE_KEY=0x... kepto equity stake <dAAPL> 10
KEPTO_PRIVATE_KEY=0x... kepto equity rewards <positionId>
KEPTO_PRIVATE_KEY=0x... kepto equity claim-rewards <positionId>

A deal is a fixed-term contract between one client and one provider over one file commitment. Its lifecycle:

Created ──acceptDeal──▶ Accepted ──activateDeal──▶ Active ──▶ Completed
   │                        │                                 │
   └──cancelDeal────────────┴──cancel (window lapsed)         └──▶ Terminated
                     ▼                                              (3 faults)
                 Cancelled

1, Create

The client calls createDeal(provider, merkleRoot, leafCount, sizeBytes, duration, totalPrice) and escrows totalPrice KEP into the market. The provider must be active in the registry, the commitment must be internally consistent (leafCount == ceil(sizeBytes / 4096)) and the duration must be within 1-360 days.

2, Accept

The provider has a 24-hour acceptWindow to call acceptDeal, locking collateral equal to 50% of the deal price (collateralBps = 5000). The slash amount per fault is set to collateral / maxFaults.

3, Activate

The client uploads the raw file bytes to the provider's HTTPS endpoint. The provider re-chunks the body, recomputes the Merkle root, checks it against the on-chain deal and then calls activateDeal within the 24-hour activationWindow. This starts the clock: endTime = now + duration.

4, Earn, settle, or unwind

• Vesting, escrow vests linearly: vested = totalPrice · (min(now, endTime) − startTime) / duration. The provider can pull the vested balance at any time with withdrawEarnings.
• Settlement, after endTime, anyone can call settleDeal (as long as no challenge is open): the provider receives the remaining escrow plus its collateral back and the deal completes.
• Cancellation, the client can cancelDeal while the deal is Created, or once an Accepted deal's activation window has lapsed. Escrow is refunded; collateral (if locked) returns to the provider.
• Termination, three unanswered challenges end the deal in the client's favor (see the slashing model below).

Protocol parameters

Storage without proofs is a promise. Kepto makes the promise expensive to break with a challenge game anyone can play.

Challenges

While a deal is Active (and before endTime), anyone except the provider may call challenge(dealId), posting the 10 KEP bond. The call records only the commitBlock, it does not pick the challenged chunk. The chunk is fixed later from that block's hash, which nobody can know when the challenge is submitted:

index = keccak256(blockhash(commitBlock) ‖ dealId ‖ faultCount) mod leafCount

Because the index is unknowable at challenge time and the provider is barred from challenging itself, a provider cannot steer the challenge onto chunks it happens to hold. Challenges are rate-limited to one per deal per 12 hours (challengeCooldown), and only one may be open at a time.

Proofs

The provider, or anyone relaying on its behalf, answers with submitProof(dealId, chunk, proof): the raw challenged chunk and its Merkle sibling path. The market verifies it against the deal's committed root at the challenged index. On success the challenge clears and the bond is paid to the provider as gas compensation.

Faults & slashing

If the 8-hour proofWindow lapses unanswered, anyone can call reportFault(dealId):

• slashPerFault = collateral / maxFaults is burned from the provider's collateral (capped by what remains).
• Half of the slash goes to the challenger (plus their bond back); half goes to the client.
• At 3 faults the deal terminates: the client receives all unwithdrawn escrow plus the remaining collateral. The provider keeps only what it already withdrew.

The data commitment is normative and shared by every component, the Solidity verifier (StorageProofs.sol), the TypeScript reference (@kepto/core), the provider daemon and this web app. They must agree byte-for-byte.

Constants & rules

Proof format

A proof is an array of sibling hashes from the leaf level upward. At any level where the current node is the promoted lone last node, no sibling is consumed. Verification walks:

h = leafHash(chunk); idx = index; size = leafCount; pi = 0
while size > 1:
    if idx == size-1 and size is odd:
        pass
    else:
        sib = proof[pi]; pi += 1
        h = idx % 2 == 0 ? node(h, sib) : node(sib, h)
    idx  = idx / 2
    size = (size + 1) / 2
require pi == len(proof) and h == root

Every proof element must be consumed, over-long proofs are invalid, which rules out proof-padding games.

Reference implementations

In TypeScript: commit(data) returns { root, leafCount, sizeBytes, tree }, and proveLeaf(tree, index) / verifyLeaf(root, leafCount, index, chunk, proof) mirror the contract exactly. This app runs commit() in your browser both when storing and when verifying retrievals.

The RWA layer (RwaRegistry, RwaVault) tokenizes real-world assets as ERC-721s (Kepto RWA, IRWA) whose legal-paperwork commitments reference active Kepto storage deals. Every document record binds the asset to a deal ID and Merkle root. If a referenced deal is no longer live, anyone can flag that deal-status condition and move the asset to Lapsed; the registry does not observe missing file bytes directly.

The flow

• Register, registerAsset(name, assetType, metadataURI, declaredValue, dealIds[], labels[]) pays the registration fee and mints the NFT to the caller. Every dealId must be an Active StorageMarket deal owned by the caller; each becomes a document { dealId, merkleRoot, label } bound to the asset. More documents can be added later with addDocument while the asset is Registered.
• Attest, an approved attestor (owner-managed allowlist) calls attest(assetId) after verifying the asset against the stored documents. Requires the backing to be intact. Each call records one per-attestor approval (AttestationRecorded); the asset flips to Attested once attestationCount reaches attestationsRequired. revokeAttestation(assetId, reason) withdraws the caller's own approval, while the quorum is still forming or after Attested, and drops an Attested asset back to Registered.
• Valuation, any attestor can revise declaredValue with updateValuation(assetId, newValue), emitting ValuationUpdated with the old and new values.
• Lapse, anyone can call flagLapsed(assetId). If any document's deal is no longer Active the asset becomes Lapsed and loses its attestation. Lapse-flagging keeps working while the asset is fractionalized, so share markets can see backing failures.
• Renew, the asset owner repairs backing with renewDocument(assetId, docIndex, newDealId). The new deal must be Active, owned by the caller, and commit the same merkleRoot. A Lapsed asset with fully renewed backing returns to Registered (re-attestation required).
• Fractionalize, fractionalize(assetId, totalShares, name, symbol) requires a current attestation (isAttestationCurrent, not merely status Attested): the NFT is locked in the RwaVault and an RwaShares ERC-20 minting totalShares to the caller is deployed. redeem(assetId) by a caller holding all shares burns them and returns the NFT.

Attestation quorum and expiry

The registry owner sets the policy with setAttestationPolicy(validity, required): attestationsRequired (default 1) approvals from distinct attestors are needed before an asset becomes Attested, and an attestation stays fresh for attestationValidity (default 90 days, 0 means it never expires).

• attestationCount(assetId), hasAttested(assetId, attestor) and isAttestationCurrent(assetId) expose the quorum and freshness state on-chain.
• Once the validity window has passed, anyone can call flagStale(assetId): the asset returns to Registered with all approvals reset (AttestationExpired), and a fresh quorum is required.
• Approvals also reset whenever the evidence changes: on flagLapsed, on addDocument, and on a renewDocument that restores a Lapsed asset.

Income distribution

RwaShares is a dividend token. Anyone, an issuer forwarding rent, a servicer paying coupons, can call distribute(amount) to pull KEP into the token (approve it first); the amount is split pro rata across holders at that moment via a per-share accumulator (accPerShare).

• withdrawableOf(holder) and claimedOf(holder) report a holder's pending and already-claimed income; totalDistributed() is the lifetime total. claim() pays the pending amount out in KEP.
• Earned income survives share transfers and the burn in redeem: selling or redeeming shares never forfeits income already earned, and a buyer does not inherit the seller's past distributions.
• Integer rounding can strand up to a few wei of dust per distribution in the token, amounts always round down in the holder's disfavor.

Statuses

Registration fee

registerAsset transfers registrationFee KEP (default 100 KEP, owner-settable) into the registry. Collected fees are withdrawable by the registry owner. Approve the fee on the KEP token before registering, the Tokenize page does both steps for you.

The renewal convention

Storage deals are finite; assets are not. Before a backing deal's endTime, the asset owner re-stores the exact same bytes, which produces the same merkleRoot, under a new deal, then calls renewDocument. Continuous coverage keeps the asset attestable; a gap lets anyone flag it Lapsed.

Testnet staked-equity simulation

This section describes a Robinhood Chain Testnet prototype. Its document, reserve, and token records simulate contract mechanics; they do not prove company-share custody, legal ownership, or off-chain asset backing.

On testnet, EquityVault locks configured prototypeEquityToken units and issues a transferable ERC-721 position (Kepto Equity Position, IEQP). The contract can prove only that the recorded token amount remains in the vault. It cannot prove what an off-chain asset represents or who holds it. unstake burns the position and returns the same recorded token amount, with no fee or oracle.

Only owner-listed testnet tokens can enter the simulation (listStock / delistStock); delisting blocks new positions while existing ones unwind normally. The current testnet inventory uses the deployed EquityToken prototypes. Units enter wallets through simulated mint, order, or trading flows; these contracts do not expose a public token faucet.

• Stake, stake(stockToken, amount, metadataURI) pulls testnet tokens into the vault, mints the position NFT recording token, amount, opener and open time, and tracks totalLocked per stock.
• Attach, attachDocument(positionId, dealId, label) lets the position owner bind prospectus or terms documents held as live Kepto deals (same live-deal and caller-owns-deal rules as the RWA registry).
• Unstake, unstake(positionId) by the position owner burns the NFT and returns the exact recorded token amount. The vault does not establish off-chain equity exposure.

Views expose the state on-chain: getPosition, getDocuments, getStock, stockCount / stockAt, positionCount and stockSymbol. This testnet simulation runs through the Equity CLI below, while the Equity page in the app surfaces the prototype state: an issuer-recorded reserve cap, compliance flags, simulated mint and redeem orders, and funded token-distribution events.

Testnet equity CLI

Equity gateway endpoints

The gateway exposes the vault read-only under /api/v1/equity:

The Kepto Gateway (packages/gateway) is a hosted integration API in the spirit of web3.storage: it holds a funded wallet and turns plain HTTP into storage deals. POST raw bytes and the gateway computes the Merkle commitment, picks the cheapest active provider with capacity (or the one you pin), escrows KEP, uploads the data and waits for on-chain activation, then hands you back the deal as JSON. Retrievals are re-verified against the on-chain root before a single byte is returned.

Base URL & authentication

All endpoints live under /api/v1 (default port 8748). When the gateway is started with the API_KEYS environment variable set (comma-separated), every request except GET /api/v1/status and GET /api/v1/openapi.yaml must carry a bearer token:

Authorization: Bearer <your-api-key>

With no API_KEYS configured the gateway is open. Errors are JSON: { "error": string }.

Endpoints

Store a file

curl -X POST "$GATEWAY/api/v1/files?duration=30d&price=5" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/octet-stream" \
  -H "x-filename: backup.tar" \
  --data-binary @backup.tar

The call blocks through the whole pipeline, commit, escrow, provider acceptance, upload, activation, and returns the live deal:

{
  "dealId": 42,
  "provider": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
  "merkleRoot": "0x9c22ff5f21f0b81b113e63f7db6da94fedef11b2119b4088b89664fb9a3cb658",
  "sizeBytes": 1048576,
  "leafCount": 256,
  "status": "Active",
  "durationSeconds": 2592000,
  "totalPriceKep": "5",
  "collateralKep": "2.5",
  "filename": "backup.tar"
}

Check status

curl -H "Authorization: Bearer $API_KEY" "$GATEWAY/api/v1/files/42"

Replication

POST /api/v1/files?replicas=n stores the same commitment with n distinct active providers, cheapest first, creating one deal per provider and returning all deal ids. Retrieval tries the providers in order until one returns bytes matching the on-chain root, so a single surviving replica is enough to recover the file.

Free-tier quotas

When API_KEYS is set, per-key upload quotas can be enforced with FREE_TIER_MAX_BYTES (0 = unlimited, the default). Usage is tracked per key in the gateway's quota store, and once a key's cumulative uploaded bytes would exceed the cap the gateway returns 413 quota exceeded.

Retrieve verified bytes

curl -H "Authorization: Bearer $API_KEY" \
  -o backup.tar "$GATEWAY/api/v1/files/42/content"

Run your own gateway

The gateway is a single Node process (npm run start -w @kepto/gateway) configured entirely via environment variables:

@kepto/sdk is a viem-based TypeScript client for the whole protocol, usable from Node and the browser. It re-exports the chunking & Merkle primitives from @kepto/core and ships the kepto CLI.

Quickstart

import { readFile, writeFile } from "node:fs/promises";
import { parseEther } from "viem";
import { KeptoClient, chains } from "@kepto/sdk";

const client = new KeptoClient({
  chain: chains.robinhoodTestnet,
  privateKey: process.env.KEPTO_PRIVATE_KEY as `0x${string}`,
  addresses: {
    token: "0x…",
    registry: "0x…",
    market: "0x…",
  },
});

const data = new Uint8Array(await readFile("backup.tar"));

const stored = await client.storeFile({
  data,
  provider: "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
  durationSeconds: 30n * 86400n,
  totalPrice: parseEther("5"),
  onProgress: (m) => console.log(m),
});
console.log("deal", stored.dealId, "root", stored.root);

const deal = await client.getDeal(stored.dealId);
console.log("status", deal.status, "ends", deal.endTime);

const bytes = await client.retrieve(stored.dealId);
await writeFile("restored.tar", bytes);

addresses may be omitted on chains with a generated deployment in @kepto/core; pass rpcUrl to override the chain default, or walletClient instead of privateKey to sign with an injected wallet.

Key methods

DealStatus

The kepto CLI

CLI configuration

kepto store walks the same five steps the Store page performs in the browser: approve, create, wait for acceptance, upload, wait for activation.

A provider is an HTTPS server with a wallet. Registration and collateral live on-chain; the data plane is a small daemon (packages/provider-node) that stores raw files under a data directory and answers challenges automatically.

1, Fund & register

• Get testnet ETH (gas) and at least 1,000 KEP (stake), see the faucets.
• Register on the Providers page (or via CLI): approve the stake, then register(endpoint, capacityBytes, pricePerGiBPerEpoch). The endpoint must be your node's public HTTPS base URL.
• Manage the listing later with updateInfo, topUpStake, deactivate / reactivate and withdrawStake (deactivated, zero active deals, 7-day delay).

2, Run the node

Configure the daemon via environment variables:

State lives under a data dir: <dataDir>/content/<merkleRoot> (raw files) and <dataDir>/deals.json (manifest). See the package README for the full flag list.

3, What the daemon does

• Watches DealCreated events directed at it and auto-accepts per policy (minimum price, max size, capacity headroom).
• Verifies uploads: re-chunks the body, recomputes the root, then calls activateDeal.
• Watches ChallengeIssued and answers immediately with submitProof.
• Withdraws vested earnings and settles ended deals on a timer.

Provider HTTP API

Base URL = the registry endpoint. Errors are JSON { "error": string }; CORS allows all origins.

The app is currently configured for Robinhood Chain Testnet (chain id 46630, NEXT_PUBLIC_CHAIN=robinhoodTestnet). Addresses resolve from explicit environment overrides first, then the generated deployment table in @kepto/core (getDeployment(chainId)). The cross-chain publisher and receiver resolve separately from generated getCcipDeployment(chainId) records; an unpublished record remains visibly marked as not configured and is never linked to a placeholder address.

Mainnet proof contracts

Standalone Chainlink CCIP proof deployed on Robinhood Chain mainnet (chain 4663) with an authenticated receiver on Arbitrum One (chain 42161). These are separate from the testnet app deployment above and are wired to the live KEP token.

Overriding

NEXT_PUBLIC_CHAIN=robinhoodTestnet
NEXT_PUBLIC_TOKEN_ADDRESS=0x…
NEXT_PUBLIC_REGISTRY_ADDRESS=0x…
NEXT_PUBLIC_MARKET_ADDRESS=0x…
NEXT_PUBLIC_RWA_REGISTRY_ADDRESS=0x…
NEXT_PUBLIC_RWA_VAULT_ADDRESS=0x…
NEXT_PUBLIC_EQUITY_VAULT_ADDRESS=0x…

Rebuild after changing these, NEXT_PUBLIC_* variables are inlined at build time.