Skip to main content
ALL CHAINS

End-to-End System Flows

This page documents eight complete flows through the Elastos stack. Each flow names the repositories where behavior is implemented, lists concrete steps aligned with source code paths (SDKs, nodes, contracts, and apps), and states the trust model so you can reason about what must be trusted and what is cryptographically enforced.

How to read this page

Treat each section as a trace: start from user or miner action, follow messages and transactions across processes, and end at a durable on-chain or network state. Cross-links to deeper protocol pages (cross-chain, identity, storage) complement the narrative here.

At-a-glance: repositories by flow​

┌─────────────────────────────────────────────────────────────────────────────┐
│  Flow                    │  Primary repositories                             │
├──────────────────────────┼───────────────────────────────────────────────────┤
│  1 DID creation          │  DID SDK · EID sidechain · Essentials             │
│  2 Deposit (main → ESC)  │  Elastos.ELA · SPV · Arbiter · SideChain.ESC      │
│  3 Withdraw (ESC → main) │  Elastos.ELA · Arbiter · SideChain.ESC             │
│  4 Proposal lifecycle    │  Main chain · Elastos DAO governance portal               │
│  5 Hive storage          │  Hive Node · EID · client SDKs                    │
│  6 Merged mining         │  Elastos.ELA · btcpool · Bitcoin                  │
│  7 Carrier messaging     │  Carrier core · DHT / Kademlia                    │
│  8 Essentials dApp       │  Essentials · InAppBrowser · Web3 providers       │
└─────────────────────────────────────────────────────────────────────────────┘

Flow 1: User creates a decentralized identity (DID)​

Repositories involved: DID SDK, EID sidechain, Essentials App (wallet UI and signing).

Step-by-step (source-aligned)​

  1. Key material: Generate a BIP-39 mnemonic, derive the seed, then HD derivation at path m/44'/0'/0'/0/0 using secp256r1 (P-256) to obtain a private/public key pair (Elastos identity curve choice for DID operations in this stack).
  2. Address and DID string: From the public key, build the redeem script (0x21 || pubkey || 0xAC), hash SHA256 → RIPEMD160, prepend 0x67, append checksum, Base58-encode. The resulting address starts with i. The DID is did:elastos:i<address>.
  3. DID Document: Construct JSON-LD with @context, id, publicKey, authentication, optional service and verifiableCredential entries; sign the document (or relevant proofs) with the private key so verifiers can bind keys to the DID.
  4. Publish on EID: Submit an EVM transaction on the identity chain that calls the precompile at address 0x16 (22 decimal) with the operationDID path using the create operation payload expected by the chain.
  5. Consensus and resolution: EID reaches agreement under PBFT (practical instant finality for that layer). The DID becomes resolvable via JSON-RPC such as did_resolveDID.

Trust model​

User sovereignty

The user controls the private key. No third party can create, modify, or deactivate that DID without key material or a deliberate user-authorized update path encoded in the DID Document and on-chain rules.

Verification surface

Resolvers and relying parties trust EID state for the latest document and cryptographic signatures for authenticity of claims presented off-chain.

Diagram: DID creation path​

  Mnemonic ──► Seed ──► HD(P-256) ──► Keypair
                                        │
                                        ▼
                              Redeem script + hashes
                                        │
                                        ▼
                              Base58 `i...` address
                                        │
                                        ▼
                         did:elastos:i<address>
                                        │
                    DID Document (signed) │
                                        ▼
                         EVM tx → precompile 0x16
                         operationDID / create
                                        │
                                        ▼
                         PBFT finality on EID
                                        │
                                        ▼
                         did_resolveDID (JSON-RPC)

Flow 2: Cross-chain transfer (main chain → ESC)​

Repositories involved: Elastos.ELA, Elastos.ELA.SPV, Elastos.ELA.Arbiter, Elastos.ELA.SideChain.ESC.

Step-by-step​

  1. User constructs deposit: Main-chain transaction of type TransferCrossChainAsset (0x08), with output directed to the ESC genesis-related deposit address, and payload specifying target sidechain, recipient address, and amount.
  2. Main-chain inclusion: The transaction is mined into a main-chain block. BPoS confirmation proceeds with validator signatures (supermajority: two-thirds plus one of the active validator set).
  3. Arbiter observation: The arbiter stack’s deposit listener (e.g. DepositListener.Notify() in the arbiter codebase) observes the inclusion; relevant data is persisted (e.g. MainChainTxs in SQLite) for coordinated relay.
  4. Relay to ESC: The on-duty arbiter path issues the sidechain-facing call: sendrechargetransaction RPC so ESC ingests the deposit intent with proofs/context the node expects.
  5. ESC verification and mint: ESC verifies the SPV proof (Merkle path against main-chain headers), materializes the credit as an internal EVM-side effect, and mints the corresponding ELA on ESC for the user address.

Trust model​

Trustless deposit verification

Deposits are designed to be trust-minimized at verification time: ESC independently checks the SPV proof tying the main-chain commitment to the credited mint. You still rely on correct chain sync and honest majority for main-chain finality before the proof is stable.

  User (main chain)                Arbiters / SPV              ESC
       │                                │                      │
       │  TransferCrossChainAsset       │                      │
       │  ─────────────────────────────►│  DepositListener     │
       │                                │  MainChainTxs (DB)   │
       │                                │                      │
       │                                │  sendrechargetx RPC ─►
       │                                │                      │  Verify SPV
       │                                │                      │  Mint ELA

Flow 3: Cross-chain withdrawal (ESC → main chain)​

Repositories involved: Same bridge family as Flow 2; emphasis on arbiter monitor, proposal, and multi-sig paths on main chain plus ESC withdraw contract behavior.

Step-by-step​

  1. User initiates on ESC: User sends ELA to the cross-chain withdraw contract address on ESC (burn/lock semantics per deployed contract version).
  2. Arbiter detection: SideChainAccountMonitor.SyncChainData() (or equivalent polling loop) calls getwithdrawtransactionsbyheight (and related APIs), tracking until sufficient confirmations (commonly 6 blocks on the sidechain for safety margins).
  3. Withdrawal proposal: The on-duty arbiter constructs a withdrawal proposal on the main chain: a transaction spending UTXOs associated with the genesis/deposit pool address in line with consensus rules.
  4. P2P proposal propagation: The proposal is broadcast on the DPoS P2P fabric (e.g. DistributedItemMessage-style envelopes) so peer validators evaluate the same payload.
  5. Co-signing: Other arbiters verify the proposal and co-sign according to the configured scheme.
  6. Threshold submission: Collect 2/3×N+1 signatures (or Schnorr aggregation where implemented), then submit the finalized transaction to the main chain so the user receives main-chain ELA.

Trust model​

Semi-trusted arbiter set

Withdrawals are not verified by every full node like a pure SPV user proof in the same way as deposits on ESC; they rely on a threshold of arbiters agreeing. Two-thirds plus one of validators means up to one-third malicious validators cannot unilaterally steal funds; misbehavior requires breaching the supermajority.

Operational dependency

Liveness and latency depend on arbiter software correctness, connectivity, and honest-majority behavior. Monitor slashing, upgrades, and incident response alongside on-chain parameters.

Flow 4: Elastos Council proposal lifecycle​

Repositories involved: Elastos DAO governance portal (MongoDB, DID-authenticated sessions), Elastos.ELA main chain for Elastos Council transaction types.

Step-by-step​

  1. Suggestion: A community member files a suggestion in the Elastos DAO governance portal; backend stores metadata (e.g. MongoDB), with DID-based authentication binding identity to actions.
  2. On-chain proposal: A council member crafts a CRCProposal transaction on the main chain: type, budget stages, recipient, draft hash, and related fields per the active consensus version.
  3. Registered & review: Proposal enters Registered, then a 7-day review window for council scrutiny.
  4. Council votes: Members submit CRCProposalReview transactions with Approve / Reject / Abstain (exact enum labels follow chain code).
  5. State transitions: If approved, progression through states such as CRAgreed, another 7-day community review, then VoterAgreed when conditions are met, until the proposal is active for execution milestones.
  6. Treasury payouts: Budget withdrawal uses CRCProposalWithdraw (per milestone), sourcing funds from the Elastos DAO treasury allocation (notably the 30% of coinbase directed to Elastos DAO per tokenomics parameters in force).

Trust model​

Transparent governance

On-chain governance: votes and state transitions are public. Treasury movements are traceable to proposals and milestones, so auditors and community can reconcile policy with chain state.

  Web (Elastos DAO)            Main chain (Elastos Council)
      │                              │
      │  Suggestion (Mongo + DID)    │
      │                              │
      │         CRCProposal tx ─────►│ Registered
      │                              │ 7d council review
      │                              │ CRCProposalReview
      │                              │ CRAgreed → … → active
      │                              │ CRCProposalWithdraw

Flow 5: Hive data storage​

Repositories involved: Hive Node (service), EID (DID resolution), client SDKs / Essentials for signing.

Step-by-step​

  1. Presentation: The app presents an App DID to the Hive Node; the node issues a challenge string/nonce.
  2. User authentication: The user responds with a Verifiable Presentation signed appropriately; VP expiry is typically short (e.g. 3 minutes) to limit replay.
  3. Token issuance: Hive resolves the user DID on EID, validates the VP, then issues a JWT with bounded lifetime (e.g. 7-day expiry) for subsequent API calls.
  4. Vault provisioning: Create vault: POST /api/v2/vault/create. Backing storage uses a MongoDB database per user+app, commonly named from MD5(user_did + app_did) (or equivalent deterministic naming in deployment configs).
  5. Data plane: Applications perform document/collection operations and file operations backed by IPFS (or configured storage driver) for large blobs.
  6. Scripting (optional): Server-side scripts and conditions can gate writes/reads for automation beyond static ACLs.

Trust model​

Operator trust

Users trust the Hive Node operator with confidentiality and availability of stored payloads. Authentication is anchored in DID; integrity of auth proofs is cryptographic, but data at rest depends on operator policy unless client-side encryption is applied by the app.

Self-hosting

For data sovereignty, deploy a Hive Node you control and point clients at it. Trust base shifts from a third-party host to your infrastructure while keeping the same DID verification flow.

Flow 6: Merged mining (Bitcoin → ELA)​

Repositories involved: Elastos.ELA node, btcpool (or pool integration), Bitcoin full node / mining stack.

Step-by-step​

  1. Aux block polling: btcpool daemon polls createauxblock on the ELA node to obtain work that embeds Elastos block commitments.
  2. Coinbase embedding: The ELA block hash is embedded in the Bitcoin coinbase transaction per AuxPoW, with Chain ID 1224 as the Elastos identifier in the merged-mining handshake.
  3. Joint PoW: A Bitcoin miner finds a nonce satisfying Bitcoin difficulty; the same proof structure satisfies AuxPoW linkage rules.
  4. Submission to ELA: btcpool submits the AuxPoW bundle via submitauxblock to the Elastos node.
  5. ELA validation: Elastos checks that the Bitcoin block hash meets ELA difficulty targets, Chain ID is correct, and BPoS validators finalize the block under consensus rules.

Trust model​

Hash-rate inheritance

ELA inherits Bitcoin’s hash rate for the merged-mining portion of security assumptions. BPoS adds fast finality and governance-aligned block acceptance on top; understand both layers when reasoning about reorgs and confirmations.

  btcpool                    Elastos.ELA              Bitcoin miner
     │                            │                         │
     │ createauxblock             │                         │
     │◄──────────────────────────│                         │
     │                            │                         │
     │  embed ELA hash in BTC     │                         │
     │  coinbase (AuxPoW, ID)     │                         │
     │ ───────────────────────────────────────────────────► │
     │                            │                         │ PoW solve
     │ submitauxblock ───────────►│ validate + BPoS         │

Flow 7: Carrier P2P message exchange​

Repositories involved: Carrier core (C/C++ and bindings), DHT implementation.

Step-by-step​

  1. Identity & routing: Generate an Ed25519 keypair; Node ID derives from the public key. Bootstrap to known DHT nodes; maintain Kademlia K-buckets with K = 8.
  2. Peer announcement: ANNOUNCE_PEER to the K closest nodes for the target keyspace so others can discover reachability.
  3. Discovery: FIND_PEER queries with service_id return nodes that previously announced for that service.
  4. Store / retrieve: STORE_VALUE at the recipient’s node ID may require an anti-spam token and Ed25519-signed envelopes to reduce abuse.
  5. NAT traversal: Active Proxy (or similar) assists NAT’d endpoints so two home users can still complete sessions.

Trust model​

P2P authenticity

Carrier provides peer discovery and transport. End-to-end trust for application data requires your protocol (encryption, signing, DID-bound sessions) above Carrier. The DHT is not a trust root by itself.

Flow 8: Essentials dApp browser session​

Repositories involved: Essentials mobile app, InAppBrowser, injected Web3 providers.

Step-by-step​

  1. Navigation: User opens a dApp URL; the app instantiates InAppBrowser and checks the URL against a phishing / blocklist database.
  2. Provider injection: The webview injects providers: window.ethereum, window.elastos, window.unisat, window.elamain (exact availability may vary by build and chain profile).
  3. Account access: dApp calls eth_requestAccounts; the user approves wallet connection in Essentials UI.
  4. Transaction path: On eth_sendTransaction, Essentials shows a review screen (value, data, network).
  5. Signing: User confirms with password / biometric; Essentials signs locally and broadcasts the transaction.
  6. Completion: dApp receives the tx hash and polls eth_getTransactionReceipt until mined.

Trust model​

Supply-chain and UI trust

Users trust Essentials not to alter transaction parameters maliciously and to display accurate summaries. dApps remain untrusted; always verify domain, contract addresses, and calldata before approval.

Multi-provider surface

Multiple injected namespaces exist for EVM, Elastos-specific calls, and Bitcoin-family wallets; feature-detect before assuming a single global.

Summary table​

FlowPrimary assuranceMain trust boundary
1 DIDP-256 keys + EID stateUser key custody
2 DepositSPV + mint rulesChain sync + honest majority (main)
3 WithdrawArbiter thresholdSupermajority arbiters
4 ProposalOn-chain Elastos Council + treasuryTransparent votes; council composition
5 HiveDID auth + JWTHive operator (unless self-hosted)
6 Merged miningAuxPoW + BPoSBitcoin work + Elastos consensus
7 CarrierEd25519 + DHT routingApp-layer crypto for payloads
8 EssentialsLocal signing + reviewUser verifies prompts

See also​

Contributing

If you trace a new code path (commit hash, file, and function), extend this page with a short “Source pointers” subsection per flow so readers can jump from narrative to implementation.