Soren Documentation

Robinhood Chain

Soren is built for Robinhood Chain, an Ethereum-compatible network for onchain financial infrastructure and real-world assets. The interface reads network data using standard Ethereum tooling.

A dedicated RPC provider can be supplied through configuration and is always preferred over the public endpoint. Development defaults to the testnet unless mainnet is explicitly selected.

Stock Tokens

Stock Tokens are one category of real-world asset on Robinhood Chain. They are ERC-20 tokenised debt securities that provide economic exposure to a referenced security such as a stock or ETF. Holding one does not provide direct legal or beneficial ownership of the underlying shares.

Soren reads each token's contract for its symbol, name, decimals, supply, corporate-action multiplier, pause state, and the issuer terms document the contract publishes onchain.

Canonical Contract Verification

Token names and symbols are not enough to establish identity. Any ERC-20 can use the ticker of a legitimate asset.

Every genuine Robinhood Stock Token is administered through the same onchain access-control registry. Soren reads the registry each token points at, compares it with the canonical one, and asks that registry whether it currently blocks the contract. A token pointing somewhere else is reported as not canonical regardless of its symbol.

A canonical match verifies the identity of the onchain contract. It does not by itself verify every legal or offchain claim associated with the asset.

Asset-Specific Verification

Soren does not apply one universal reserve formula to every asset. The checks depend on what the asset is.

A check that cannot be evaluated from a source Soren tracks is reported as unknown. It is never reported as a pass, and no value is invented to fill the gap.

Verification Registry

The Verification Registry is the onchain record of Soren's current result for an asset. It stores a compact record rather than the evidence itself: a status, the time it was written, a hash of the offchain evidence bundle, and the policy version that produced it.

enum VerificationStatus {
  Unknown, Verified, PartiallyVerified,
  Outdated, Discrepancy, NotVerifiable
}

struct VerificationRecord {
  VerificationStatus status;
  uint64  updatedAt;
  bytes32 evidenceHash;
  uint32  policyVersion;
}

Writes require VERIFIER_ROLE. Reads are open to anyone, which is what lets a vault enforce the result without trusting the interface.

Verified Asset Vaults

A Verified Asset Vault is an ERC-4626 vault for a single underlying asset. Its one job in this release is making verification enforceable: it consults the verification policy before accepting a deposit, and never on the way out.

RWA / STOCK TOKEN
        ↓
SOREN VERIFICATION REGISTRY
        ↓
VERIFIED ASSET VAULT
        ↓
USER DEPOSIT POSITION

The vault runs no yield strategy. It has no owner, no upgrade path, and no function that lets any privileged account move, freeze, or seize a depositor's assets.

Vault Eligibility

Each vault reports whether it is currently accepting deposits and why. The interface shows the individual checks behind that answer, so a paused vault explains itself rather than failing silently.

For the current policy, eligibility means the registry reports Verified and the record is within the configured freshness window. Every other status pauses entry. The policy is a separate contract behind an interface, so future policies can additionally require a canonical contract match, a live oracle, an approved issuer, or valid corporate-action metadata without changing the vault.

Deposits

Depositing requires, in order:

• A connected wallet
• The wallet on Robinhood Chain
• The asset satisfying the vault verification policy
• A sufficient balance of the underlying asset
• An ERC-20 allowance for the vault, requested when the current allowance is too low
• The deposit transaction itself

The interface shows each stage as it happens: awaiting approval, approval submitted, approval confirmed, awaiting deposit confirmation, deposit submitted, deposit confirmed. Nothing is reported as successful until the transaction receipt reports success, and a Blockscout link is available from the moment the transaction is submitted.

Withdrawals

Withdrawals are never gated by verification state. A depositor can withdraw whether the asset is Verified, Partially Verified, Outdated, in Discrepancy, or Not Verifiable.

This is a deliberate design constraint: verification failure pauses entry, it does not confiscate or lock assets. The contract enforces it, not the interface.

Verification Changes

When a published verification result changes, vaults for that asset react immediately, because they read the registry at the moment of each deposit rather than caching a result.

The interface shows: "New deposits are paused because this asset no longer satisfies the vault verification policy. Existing positions remain withdrawable."

Contract Architecture

Wallet Connection

Soren connects to injected browser wallets such as MetaMask through wagmi and viem. The interface detects the current chain, offers to switch to Robinhood Chain when the wallet is elsewhere, and adds the network if the wallet does not know it.

Connection state persists across reloads. Rejected connection requests and rejected network switches are reported plainly. Soren never asks for a seed phrase or a private key, and never stores one.

Corporate Actions

Stock Tokens use an onchain multiplier to reflect corporate actions such as dividends and splits while the raw ERC-20 balance stays unchanged. Soren reads the current multiplier, any pending multiplier, and the time a pending change takes effect, directly from the token contract.

Raw oracle prices and multiplier-adjusted figures are different quantities. Soren labels which is which rather than mixing them.

Verification Statuses

Withdrawals remain available in every one of these states.

Data Sources

Where a value genuinely cannot be sourced, the interface shows Unavailable. A failed request is never rendered as a zero.

Indexer Architecture

A lightweight indexer runs as a separate service. It follows VerificationUpdated, VaultCreated, Deposit, and Withdraw events, records them to an offchain index, and tracks the last processed block so it resumes safely after a restart.

• Processes blocks in bounded ranges and confirms behind the head to tolerate reorgs
• Writes are idempotent on transaction hash and log index, so a replay cannot duplicate rows
• Temporary RPC failures are retried with backoff
• An RPC failure is logged and retried; it never results in an invented event

The live chain remains the authority. The index is a historical representation of what the chain already said, and is never the source of truth for balances, positions, vault state, verification status, or transaction confirmation. Those are read from the contracts on every request.

Security

• Contracts use OpenZeppelin implementations for ERC-4626, AccessControl, SafeERC20, and ReentrancyGuard rather than reimplementing them
• Vault entry points are non-reentrant and follow checks-effects-interactions
• The vault rejects fee-on-transfer and rebasing behaviour rather than mis-accounting it
• Vault creation is permissioned so a lookalike vault cannot be published for a real asset
• No owner sweep function and no upgrade path exists over depositor funds
• The frontend verifies the chain ID before every write and reads token decimals from the chain
• Buttons disable while a transaction is pending so a double click cannot submit twice
• Only http and https URLs from external metadata are ever placed in a link
• Security headers include a Content-Security-Policy, frame-ancestors none, nosniff, and HSTS in production

Risk and Trust Assumptions

Soren is not decentralised. A designated verifier account holds VERIFIER_ROLE and can set the verification state of any asset, and the admin can grant or revoke that role. Anything reading the registry, including every vault, inherits that trust assumption.

What that account can do is bounded: it can pause entry into a vault. It cannot move, freeze, or seize a depositor's assets, and it cannot prevent a withdrawal.

• The Soren contracts have not been independently audited
• Vault creation is restricted to an authorised account for the MVP
• Verification reflects the evidence available at a point in time and can change
• A canonical contract match verifies onchain identity only
• Price and market data come from a third-party index and can be delayed or missing
• Nothing in this product is financial, legal, tax, or investment advice

Frequently Asked Questions