Build on Kepto

Kepto puts real assets on-chain with cryptographic proof of what backs them. It is three products on one settlement layer: tokenized stocks backed one to one, real-world assets bound to provably held documents, and the verifiable storage that makes those proofs real. 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 backing is readable on-chain at any moment, not promised in a quarterly PDF. Supply can never exceed attested reserves, documents are audited by random challenges, and retrieved bytes are re-hashed against an on-chain root before they reach you.

The three pillars#

Actors#

Core contracts#

Ways to integrate#

A tokenized stock is an ordinary ERC-20 that represents a share of a real company, one token per share. Kepto ships two demo tickers, dAAPL and dTSLA, each an EquityToken priced and traded in KEP. What makes it trustworthy is not a promise, it is an invariant enforced by the contract.

Secure Mint and 1:1 backing#

Each token carries an on-chain reserves figure the issuer attests to. Every mint runs through Secure Mint, which reverts unless totalSupply() + amount <= reserves. A share that is not covered by reserves simply cannot be issued, and reservesRatioBps() reports the live backing ratio for anyone to read.

Compliance-gated transfers#

Transfers pass through a shared ComplianceRegistry. In blacklist mode (the demo default) tokens move freely except for frozen accounts, so shares 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.

Mint and redeem#

Primary issuance uses an on-chain order queue so KEP and shares are only ever escrowed by the contract, never by a person.

1. 1
   Request
   You call requestMint(paymentKep); the contract escrows your KEP and records a pending order. Redeeming is the mirror, requestRedeem(shares) escrows your shares.
2. 2
   Fill
   The operator fills the order against real custody: fillMint issues shares through Secure Mint and forwards your KEP to the treasury; fillRedeem burns the shares and pays you KEP. An operator keeper fills continuously so this settles in seconds.
3. 3
   Or cancel
   While an order is still pending you can cancelOrder(id) and get your escrow back to the wei.

NAV and dividends#

navPerShare records the attested net asset value per share. Dividends are paid in KEP through a pull-model distributor: 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, so income follows the shares even as they move.

On-chain versus off-chain#

Try it#

# read a tokenized stock: reserves, backing, NAV, 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 your KEP dividends
KEPTO_PRIVATE_KEY=0x... kepto equity claim <dAAPL>

Stake tokenized shares in the EquityVault to earn yield without giving up ownership. Staking locks your shares and mints an ERC-721 position NFT that represents the stake. Your yield comes from two streams at once.

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 receipts. earned(positionId) reports the live reward and dividend, claimRewards(positionId) pays them out, and unstake(positionId) auto-claims everything and returns your exact shares.

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 must be provably stored in active Kepto storage deals. Every document is bound to the asset by the Merkle root of a deal you own; if the documents stop being stored, anyone can flag the asset as lapsed on-chain.

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.

Staked equities

The attestor model works for deeds and invoices, things whose backing is a document. It cannot enforce the backing of a share: a paper claim that you hold 100 shares does nothing to stop you selling those shares the next minute, leaving the claim naked. Custody has to be enforced, not promised.

EquityVault answers this by staking on-chain stock tokens (Robinhood Chain's native tokenized equities). You lock the equity tokens in the vault and receive a transferable ERC-721 position (Kepto Equity Position, IEQP). Because the tokens sit in the vault, the backing is cryptographically enforced: you provably cannot sell the underlying while the position exists. What trades is the receipt, the position NFT, and unstake redeems it 1:1 for the exact staked amount, no fees and no oracle.

Only owner-listed tokens are stakeable (listStock / delistStock); delisting blocks new positions while existing ones unwind normally. On testnet the listed tokens are clearly-labeled DemoStock ERC-20s with a public faucet minting 100 tokens per address per 24h, so anyone can try the flow; a mainnet vault would whitelist the chain's native tokenized equities.

• Stake, stake(stockToken, amount, metadataURI) pulls the 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 staked amount. The vault never creates equity exposure, it locks and receipts it.

Views expose the state on-chain: getPosition, getDocuments, getStock, stockCount / stockAt, positionCount and stockSymbol. The staking flow runs through the Equity CLI below, while the Equity page in the app surfaces the tokenized equity model: per token backing, compliance status, mint and redeem orders, and stablecoin dividends.

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)).

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.