diff --git a/BUILDERS_FORGE_RULES_S1.md b/BUILDERS_FORGE_RULES_S1.md
index 6b05bd0..223aa49 100644
--- a/BUILDERS_FORGE_RULES_S1.md
+++ b/BUILDERS_FORGE_RULES_S1.md
@@ -4,7 +4,7 @@ To ensure fairness and quality, all participants must follow the guidelines belo
- All tasks in our [Github](https://github.com/cedra-labs/docs/issues) with special `Builders Forge` label
- All code and documentation must be in English
-- No copy-paste β all work must be original
+- No copy-paste - all work must be original
- One GitHub account per participant
- Team submissions allowed, but rewards are per task, not per person
- Submit all work through a GitHub Pull Request (PR)
diff --git a/docs/cli/usage.md b/docs/cli/usage.md
index 8a4523d..29142b4 100644
--- a/docs/cli/usage.md
+++ b/docs/cli/usage.md
@@ -270,6 +270,8 @@ cedra move test
This will compile the package (in test mode) and run all tests in your code. Output will show which tests passed or failed, along with any debug prints or assertions from the tests. Use this to verify your module's logic off-chain before deploying.
+For comprehensive testing documentation including test annotations, expected failures, and best practices, see [Move Unit Testing](/move/testing).
+
### π Publishing Move Modules to the Blockchain
For packages exceeding 64KB, see [Deploying Large Packages](/large-packages).
diff --git a/docs/concepts/accounts/authentication.md b/docs/concepts/accounts/authentication.md
new file mode 100644
index 0000000..b77cbaa
--- /dev/null
+++ b/docs/concepts/accounts/authentication.md
@@ -0,0 +1,124 @@
+# Account Authentication
+
+Authentication on Cedra is more flexible than most blockchains. The separation between address and authentication key means you can rotate your keys without changing your account identity - similar to changing a password without creating a new username. Cedra also supports multiple cryptographic schemes and native multisig, all built into the protocol rather than implemented through smart contracts.
+
+:::tip Navigation
+**Previous:** [Understanding Accounts](/concepts/accounts/understanding-accounts)
+**You are here:** Authentication
+**Next:** [Resources](/concepts/accounts/resources)
+:::
+
+### Authentication Key vs Address
+
+When you first create an account, your authentication key becomes your address. But here's the key insight: while the address is permanent, the authentication key can change.
+
+The authentication key is what proves you own the account - it's derived from your public key and verified when you sign transactions. If your private key is compromised or you simply want better security, you can rotate to a new authentication key while keeping your existing address, balances, and resources.
+
+```mermaid
+graph LR
+ subgraph "Initial State"
+ A[Auth Key] -->|equals| B[Address]
+ end
+
+ subgraph "After Rotation"
+ C[New Auth Key] -->|authenticates| D[Same Address]
+ end
+
+ B --> D
+```
+
+The network maintains an on-chain mapping that tracks these rotations, so it knows which authentication key currently controls each address.
+
+## Authentication Schemes
+
+Cedra supports multiple cryptographic schemes for signing transactions. Each scheme uses a different algorithm to derive the authentication key from the public key.
+
+### Ed25519 (Default)
+
+The most common choice, using the Ed25519 elliptic curve. The authentication key is computed as:
+
+```
+auth_key = sha3-256(public_key | 0x00)
+```
+
+The `0x00` suffix is the scheme identifier that distinguishes Ed25519 from other schemes. Ed25519 offers fast signature verification and is well-suited for most use cases.
+
+### Secp256k1 ECDSA
+
+The same curve used by Bitcoin and Ethereum. If you're migrating from those ecosystems or want compatibility with existing tooling, Secp256k1 is available:
+
+```
+auth_key = sha3-256(0x01 | public_key | 0x02)
+```
+
+### MultiEd25519 (K-of-N Multisig)
+
+For accounts requiring multiple signatures, Cedra supports K-of-N multisig natively. You specify N public keys and require K of them to sign any transaction:
+
+```
+auth_key = sha3-256(pubkey_1 | pubkey_2 | ... | pubkey_n | K | 0x01)
+```
+
+For example, a 2-of-3 multisig would have three public keys concatenated, followed by the threshold value 2, then the scheme identifier.
+
+## Native Multisig Support
+
+Unlike Ethereum where multisig requires deploying a smart contract, Cedra's multisig is built into the protocol. This means:
+
+- **Lower gas costs** - No contract deployment or extra execution overhead
+- **Simpler setup** - Just combine public keys and set a threshold
+- **Mixed key types** - Combine Ed25519, Secp256k1, WebAuthn in one multisig
+- **No contract risk** - No smart contract bugs to worry about
+
+A transaction from a multisig account includes multiple signatures. The network verifies that at least K of the N authorized keys have signed before accepting the transaction.
+
+```mermaid
+graph TD
+ subgraph "2-of-3 Multisig"
+ A[Transaction] --> B{Collect Signatures}
+ B --> C[Signer 1: Ed25519]
+ B --> D[Signer 2: Secp256k1]
+ B --> E[Signer 3: Ed25519]
+ C --> F{K signatures?}
+ D --> F
+ F -->|Yes, 2 of 3| G[Valid Transaction]
+ end
+```
+
+
+## Key Rotation
+
+Key rotation lets you change the authentication key controlling your account while keeping the same address. This is essential for:
+
+- **Compromised keys** - If you suspect your private key was exposed, rotate immediately
+- **Security upgrades** - Move from a single key to multisig, or upgrade to a hardware wallet
+- **Organizational changes** - When team members change, rotate the controlling keys
+
+The rotation process uses the `account::rotate_authentication_key` function. You sign the rotation request with your current key to prove ownership, and specify the new authentication key that should take over.
+
+```mermaid
+sequenceDiagram
+ participant Owner
+ participant Account
+ participant Network
+
+ Owner->>Account: Sign rotation with current key
+ Owner->>Account: Specify new auth key
+ Account->>Network: Submit rotation transaction
+ Network->>Network: Verify current key signature
+ Network->>Network: Update auth key mapping
+ Network->>Owner: Confirmation
+ Note over Owner,Network: Old key no longer works
New key now controls account
+```
+
+After rotation, the old key can no longer sign transactions for this account. The address remains unchanged, so all your resources, module references, and history stay intact.
+
+:::info Rotation Tracking
+The network maintains an on-chain `OriginatingAddress` table that maps authentication keys to their original addresses. This ensures that even after multiple rotations, the account's identity remains consistent.
+:::
+
+## Next Steps
+
+- [Resources](/concepts/accounts/resources) - How Move resources are stored within accounts
+- [Understanding Accounts](/concepts/accounts/understanding-accounts) - Account fundamentals
+- [Transactions](/concepts/transactions/understanding-transactions) - How authenticated accounts interact with the network
diff --git a/docs/concepts/accounts/resources.md b/docs/concepts/accounts/resources.md
new file mode 100644
index 0000000..034bded
--- /dev/null
+++ b/docs/concepts/accounts/resources.md
@@ -0,0 +1,214 @@
+# Move Resources
+
+On Cedra, all on-chain state is organized into resources and modules stored within accounts. This is fundamentally different from Ethereum's model where each smart contract maintains its own storage. In Cedra, your tokens live in your account, not in a contract's storage - and this per-account model is what enables parallel transaction execution.
+
+:::tip Navigation
+**Previous:** [Authentication](/concepts/accounts/authentication)
+**You are here:** Resources
+**Overview:** [Understanding Accounts](/concepts/accounts/understanding-accounts)
+:::
+
+## Resources vs Instances
+
+Move distinguishes between two types of storable data based on their abilities.
+
+A **resource** has the `key` ability, meaning it can be stored directly under an account address. Resources are top-level citizens - you can query them directly by account address and type.
+
+An **instance** has the `store` ability, meaning it can be stored within other resources but not directly under an account. Instances are nested data that lives inside resources.
+
+```move
+module 0x1::coin {
+ /// Resource - stored directly under account (has `key`)
+ struct CoinStore has key {
+ coin: Coin,
+ }
+
+ /// Instance - stored within CoinStore (has `store`)
+ struct Coin has store {
+ value: u64,
+ }
+}
+```
+
+In this example, `CoinStore` is the resource that lives under your account. It contains a `Coin` instance that holds the actual balance. You can't store a `Coin` directly under an account - it must be wrapped in something with the `key` ability.
+
+```mermaid
+graph TD
+ subgraph "Account 0xABC"
+ A[CoinStore<CED>] -->|contains| B[Coin: 1000]
+ C[CoinStore<USDC>] -->|contains| D[Coin: 500]
+ end
+
+ style A fill:#e1f5fe
+ style C fill:#e1f5fe
+ style B fill:#fff3e0
+ style D fill:#fff3e0
+```
+
+## Defining Resources
+
+When you define a resource, you're specifying its structure, abilities, and the module that governs it.
+
+```move
+module 0x1234::token {
+ struct TokenStore has key {
+ tokens: vector,
+ frozen: bool,
+ }
+
+ struct Token has store, drop {
+ id: u64,
+ metadata: vector,
+ }
+}
+```
+
+The fully qualified path to this resource is `0x1234::token::TokenStore`. When you want to access it, you need three pieces of information:
+
+- **Address**: `0x1234` - where the module is deployed
+- **Module**: `token` - the module name
+- **Resource**: `TokenStore` - the struct name with `key` ability
+
+## Resource Permissions
+
+The module that defines a resource controls all operations on it. This is Move's core security model - only the defining module can:
+
+- Create new instances (`move_to`)
+- Destroy instances (`move_from`)
+- Borrow references (`borrow_global`, `borrow_global_mut`)
+
+External modules and users can only interact with resources through the public functions that the defining module exposes. The internal state of a resource is completely protected.
+
+```move
+module 0x1::coin {
+ struct Balance has key { value: u64 }
+
+ /// Only this module can create balances
+ public fun initialize(account: &signer) {
+ move_to(account, Balance { value: 0 });
+ }
+
+ /// Only this module can modify balances
+ public fun deposit(addr: address, amount: u64) acquires Balance {
+ let balance = borrow_global_mut(addr);
+ balance.value = balance.value + amount;
+ }
+
+ /// External code can read but not modify
+ public fun get_balance(addr: address): u64 acquires Balance {
+ borrow_global(addr).value
+ }
+}
+```
+
+This means "ownership" in Move is not just about where data is stored - it's about which module has permission to modify it. A token might be stored under your account, but only the token module's code can change its value.
+
+## Storage Location
+
+Resources live within the accounts that own them. When Alice holds CED tokens, the `CoinStore` resource is stored under Alice's address, not under some global contract address.
+
+To query a resource, you need the owner's address plus the resource type:
+
+```
+Account: 0xALICE
+Resource: 0x1::coin::CoinStore<0x1::ced::CED>
+```
+
+You can view resources through:
+- The Cedra Explorer - enter any address to see its resources
+- Fullnode REST API - `GET /accounts/{address}/resources`
+- SDK calls - `client.getAccountResource(address, resourceType)`
+
+```mermaid
+graph LR
+ subgraph "Query"
+ A[Account Address] --> B[Resource Type]
+ B --> C[Resource Data]
+ end
+
+ subgraph "Example"
+ D["0xALICE"] --> E["0x1::coin::CoinStore"]
+ E --> F["{ coin: { value: 1000 } }"]
+ end
+```
+
+## Parallel Execution Benefits
+
+This per-account storage model is why Cedra can execute transactions in parallel. When Alice sends tokens to Bob while Carol sends tokens to Dave, these transactions touch completely different storage locations:
+
+- Alice's transaction: reads/writes Alice's `CoinStore`, writes Bob's `CoinStore`
+- Carol's transaction: reads/writes Carol's `CoinStore`, writes Dave's `CoinStore`
+
+No overlap means no conflicts, so both transactions can execute simultaneously.
+
+```mermaid
+graph TD
+ subgraph "Parallel Execution"
+ subgraph "Thread 1"
+ A1[Alice's CoinStore] --> B1[Bob's CoinStore]
+ end
+ subgraph "Thread 2"
+ A2[Carol's CoinStore] --> B2[Dave's CoinStore]
+ end
+ end
+
+ style A1 fill:#e8f5e9
+ style B1 fill:#e8f5e9
+ style A2 fill:#e3f2fd
+ style B2 fill:#e3f2fd
+```
+
+Compare this to Ethereum, where all ERC-20 transfers go through a single contract's storage. Every transfer must access the same contract state, creating a bottleneck that prevents parallel execution.
+
+:::info Events and Receivers
+Events can also be stored in the receiver's account rather than emitted globally. This further reduces contention - Alice receiving tokens triggers an event stored under Alice's account, not in some shared event log.
+:::
+
+## Working with Resources
+
+Here's how you interact with resources in Move code:
+
+```move
+module 0x1::example {
+ struct Counter has key {
+ value: u64,
+ }
+
+ /// Create a new counter under the signer's account
+ public fun create(account: &signer) {
+ move_to(account, Counter { value: 0 });
+ }
+
+ /// Check if an account has a counter
+ public fun exists_at(addr: address): bool {
+ exists(addr)
+ }
+
+ /// Read the counter value
+ public fun get(addr: address): u64 acquires Counter {
+ borrow_global(addr).value
+ }
+
+ /// Increment the counter (requires signer for access control)
+ public fun increment(account: &signer) acquires Counter {
+ let addr = signer::address_of(account);
+ let counter = borrow_global_mut(addr);
+ counter.value = counter.value + 1;
+ }
+
+ /// Remove and destroy the counter
+ public fun destroy(account: &signer) acquires Counter {
+ let addr = signer::address_of(account);
+ let Counter { value: _ } = move_from(addr);
+ }
+}
+```
+
+The `acquires` annotation tells the compiler which resources a function accesses. This enables compile-time checking and helps with parallel execution planning.
+
+## Next Steps
+
+- [Understanding Accounts](/concepts/accounts/understanding-accounts) - Account fundamentals and types
+- [Authentication](/concepts/accounts/authentication) - How accounts prove ownership
+- [Move Resource Types](/move/resource) - Deep dive into resource programming
+- [Block-STM](/concepts/block-stm) - How per-account storage enables parallel execution
diff --git a/docs/concepts/accounts/understanding-accounts.md b/docs/concepts/accounts/understanding-accounts.md
new file mode 100644
index 0000000..c30633e
--- /dev/null
+++ b/docs/concepts/accounts/understanding-accounts.md
@@ -0,0 +1,140 @@
+# Understanding Accounts
+
+Accounts on Cedra represent access control over assets stored as Move resources. Unlike Ethereum where accounts exist implicitly once someone sends funds to an address, Cedra requires explicit account creation before any transactions can be executed. This design enables powerful features like key rotation and native multisig support.
+
+:::tip Navigation
+**You are here:** Understanding Accounts
+**Next:** [Authentication](/concepts/accounts/authentication) | [Resources](/concepts/accounts/resources)
+**Overview:** [Blockchain Architecture](/concepts/blockchain)
+:::
+
+
+### Account Addresses
+
+Every account is identified by a 32-byte address, displayed as a 64-character hexadecimal string prefixed with `0x`. When you see short addresses like `0x1` for framework modules, they're simply padded with leading zeros - `0x1` becomes `0x0000000000000000000000000000000000000000000000000000000000000001`.
+
+```mermaid
+graph LR
+ subgraph "Address Format"
+ A[32 bytes] --> B[64 hex characters]
+ B --> C["0x prefix"]
+ end
+
+ subgraph "Example"
+ D["0x1"] --> E["0x000...001"]
+ end
+```
+
+The address is permanent and never changes, even when authentication keys are rotated. Think of it as your unchanging identifier on the network, similar to a username that stays constant even when you change your password.
+
+
+## Account Types
+
+Cedra supports three distinct account types, each serving different purposes.
+
+### Standard Accounts
+
+The most common account type, controlled by a public/private key pair. When you create a wallet, you're creating a standard account. You sign transactions with your private key, and the network verifies them against your public key.
+
+### Resource Accounts
+
+These are autonomous accounts with no private key - nobody can sign transactions on their behalf. Developers use resource accounts to store modules and resources that need to exist independently of any user. For example, a DEX might deploy its liquidity pool logic to a resource account so the code persists regardless of the original deployer.
+
+### Objects
+
+Objects represent complex assets at a single address, useful when you need to group related resources together. Unlike standard accounts, objects are designed to represent single entities like NFTs or complex on-chain structures.
+
+```mermaid
+graph TD
+ subgraph "Standard Account"
+ A[Private Key] --> B[Public Key]
+ B --> C[Signs Transactions]
+ end
+
+ subgraph "Resource Account"
+ D[No Private Key]
+ D --> E[Autonomous]
+ E --> F[Stores Modules/Resources]
+ end
+
+ subgraph "Object"
+ G[Single Address]
+ G --> H[Groups Related Resources]
+ end
+```
+
+
+## Creating an Account
+
+Account creation follows a deterministic process that derives the address from your chosen authentication scheme.
+
+First, you select an authentication scheme - either Ed25519 (the default and most common) or Secp256k1 ECDSA. Then you generate a key pair for that scheme. From the public key, you derive a 32-byte authentication key using a hash function. This authentication key becomes your initial account address.
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant KeyGen
+ participant Hash
+ participant Network
+
+ User->>KeyGen: Select auth scheme (Ed25519/Secp256k1)
+ KeyGen->>KeyGen: Generate key pair
+ KeyGen->>Hash: Public key + scheme identifier
+ Hash->>Hash: SHA3-256
+ Hash->>User: 32-byte auth key
+ User->>Network: Create account with auth key as address
+```
+
+The relationship between authentication key and address is what enables key rotation - you can change your auth key later while keeping the same address.
+
+
+## Sequence Numbers
+
+Every account maintains a sequence number that acts as a transaction counter. When you submit a transaction, it must include your current sequence number. After successful execution, the sequence number increments by one.
+
+This mechanism serves a critical security purpose: replay protection. Without sequence numbers, an attacker could capture a valid signed transaction and submit it repeatedly. With sequence numbers, each transaction is valid exactly once - the second attempt would fail because the sequence number would no longer match.
+
+:::info Multi-Agent Transactions
+In transactions involving multiple signers, only the primary signer's sequence number is checked and incremented. Secondary signers don't need to worry about sequence number coordination.
+:::
+
+
+## Account State
+
+Each account can hold two types of on-chain data: Move modules and Move resources.
+
+**Modules** are compiled smart contract code. When you deploy a Move package, the bytecode is stored as modules under your account. Other accounts can then call functions from these modules.
+
+**Resources** are structured data that follows Move's ownership rules. Your CED balance, NFT collections, and any other on-chain assets exist as resources stored within your account.
+
+An account can hold an arbitrary number of both modules and resources. This per-account storage model is fundamentally different from Ethereum's contract-centric approach, and it's what enables Cedra's parallel execution - transactions touching different accounts can run simultaneously without conflicts.
+
+
+## Access Control with Signers
+
+Move uses the `signer` type to implement access control. When a function requires a `signer` parameter, only the account owner can call it - they must sign the transaction to prove ownership.
+
+```move
+module 0x1::coin {
+ /// Only the account owner can withdraw from their balance
+ public fun withdraw(account: &signer, amount: u64): Coin {
+ // signer proves ownership of the account
+ let balance = borrow_global_mut(signer::address_of(account));
+ // ... withdraw logic
+ }
+
+ /// Anyone can check a balance - no signer required
+ public fun balance(addr: address): u64 {
+ borrow_global(addr).value
+ }
+}
+```
+
+Functions without a `signer` parameter are open to anyone. In the example above, `withdraw` requires the account owner's signature, but `balance` can be called by anyone to view any account's balance. This pattern - signer for writes, address for reads - appears throughout Move development.
+
+
+## Next Steps
+
+- [Authentication](/concepts/accounts/authentication) - Learn about auth schemes, multisig, and key rotation
+- [Resources](/concepts/accounts/resources) - Understand how Move resources are stored and accessed
+- [Transactions](/concepts/transactions/understanding-transactions) - See how accounts interact with the network
diff --git a/docs/concepts/block-stm.md b/docs/concepts/block-stm.md
new file mode 100644
index 0000000..27894c0
--- /dev/null
+++ b/docs/concepts/block-stm.md
@@ -0,0 +1,243 @@
+# Block-STM: Parallel Execution Engine
+
+Cedra achieves high throughput through Block-STM, a parallel execution engine that processes transactions concurrently while maintaining deterministic results. This technology enables over 160,000 transactions per second by combining Software Transactional Memory techniques with a novel collaborative scheduler.
+
+### Key Concepts
+
+- **[Parallel Execution](#how-block-stm-works)**: Running multiple transactions simultaneously
+- **[Optimistic Concurrency Control](#optimistic-vs-pessimistic-concurrency)**: Execute first, validate later
+- **[Multi-version Data Structure](#multi-version-data-structure)**: Track all writes with versions
+- **[Collaborative Scheduler](#the-collaborative-scheduler)**: Coordinate tasks across threads
+
+---
+
+## The Concurrency Challenge
+
+Smart contract execution is a major throughput bottleneck for blockchains. After proposing blocks and agreeing on their order, validators must execute the transactions and arrive at the same final state - one that corresponds to some sequential execution. This creates a fundamental tension: we want parallel execution for speed, but we need deterministic results for consensus.
+
+:::info Core Principle
+Block-STM guarantees that parallel execution produces the same result as if transactions were executed sequentially in the preset order. This determinism is essential - validators executing the same block must arrive at identical final states.
+:::
+
+Current blockchains face a difficult choice: execute sequentially (which doesn't scale) or require an embarrassingly parallel workload with no conflicts (which is unrealistic for real applications). Transactions often have significant access conflicts due to popular contracts, economic opportunities like auctions and arbitrage, or even performance attacks.
+
+Block-STM solves this by dynamically and transparently extracting the inherent parallelism from any workload, without requiring users to declare dependencies upfront.
+
+---
+
+## Optimistic vs Pessimistic Concurrency
+
+There are two fundamental approaches to handling concurrent access to shared resources:
+
+```mermaid
+graph LR
+ subgraph "Pessimistic (PCC)"
+ A1[Declare Dependencies] --> A2[Acquire Locks]
+ A2 --> A3[Execute]
+ A3 --> A4[Release Locks]
+ end
+
+ subgraph "Optimistic (OCC)"
+ B1[Execute Speculatively] --> B2[Validate Results]
+ B2 -->|Valid| B3[Commit]
+ B2 -->|Conflict| B4[Re-execute]
+ B4 --> B2
+ end
+```
+
+### Pessimistic Concurrency Control (PCC)
+
+In PCC systems like Solana, transactions are blocked if they need to access a resource already in use by another transaction. This approach requires transactions to declare upfront what portions of memory they will read from and write to, since acquiring locks on the fly leads to unserializable execution results.
+
+While PCC has historically performed well in distributed databases, it comes with significant limitations: users must specify all dependencies before execution, which constrains what transactions can do and may require complex transactions to be broken up or retried.
+
+### Optimistic Concurrency Control (OCC)
+
+Block-STM uses OCC, where transactions execute on all available processing resources with no regard for conflicts. Instead of writing directly to persistent memory, transactions write to a log. After execution, each transaction is validated to ensure it didn't violate database integrity rules. If validation fails, the transaction is rolled back and rescheduled; otherwise, it commits.
+
+| Aspect | PCC (Solana) | OCC (Block-STM) |
+|--------|--------------|-----------------|
+| **Dependency Declaration** | Required upfront | Not required |
+| **Execution** | Blocked if resource locked | Proceeds optimistically |
+| **Conflict Detection** | Before execution | After execution |
+| **Developer Experience** | Must specify all accessed accounts | Transparent, automatic |
+| **Arbitrary Logic** | Limited by declarations | Fully supported |
+
+Thanks to clever design and engineering, Block-STM performs surprisingly well, with the added benefits of allowing arbitrary logic and a superior developer experience.
+
+---
+
+## How Block-STM Works
+
+Block-STM combines known techniques with novel ideas to achieve high-performance parallel execution:
+
+```mermaid
+graph TD
+ A[Transactions Ordered by Priority] --> B[Schedule for Parallel Execution]
+ B --> C[Execute with Multi-Version Data Structure]
+ C --> D[Track Read Set During Execution]
+ D --> E[Validate Against Current Values]
+ E -->|Match| F[Mark Valid]
+ E -->|Mismatch| G[Mark as ESTIMATE]
+ G --> H[Re-execute]
+ H --> D
+ F --> I[All Prior Validated?]
+ I -->|Yes| J[Safe to Commit]
+ I -->|No| K[Wait for Prior Transactions]
+```
+
+### Transaction Ordering
+
+Before execution begins, transactions are ordered by priority: `txβ > txβ > txβ > ... > txβ`. This preset order is crucial - it reduces the amount of synchronization required during execution. Where a general-purpose STM would need to solve consensus when conflicts occur, Block-STM simply follows the predetermined order: if txβ
and txβ conflict, txβ waits for txβ
.
+
+### Multi-Version Data Structure
+
+Block-STM uses a multi-version data structure to avoid write-write conflicts. All writes to the same location are stored along with their versions, which contain:
+- The transaction ID
+- The number of times the writing transaction was re-executed
+
+When a transaction `txβ±Ό` reads a memory location, it obtains the value written by the highest-priority transaction that appears before `txβ±Ό` in the preset order, along with the associated version.
+
+### Read Set Tracking
+
+During execution, each transaction records its read set - the memory locations and associated values it read. This information is essential for validation.
+
+### Validation Process
+
+After a transaction completes execution, it's validated by comparing its read set with the current values at those memory locations:
+
+- **If values match**: The transaction is marked valid (but not yet safe to commit)
+- **If values differ**: A higher-priority transaction modified a location that this transaction read, making the results invalid
+
+### Conflict Resolution with ESTIMATE
+
+When validation fails, instead of deleting dirty values from the data structure, Block-STM marks them as `ESTIMATE` and schedules the transaction for re-execution. This is a key optimization:
+
+- Values aren't deleted because re-execution will likely write to the same locations
+- Any lower-priority transaction that reads an `ESTIMATE` value waits for the dependency to be resolved
+- This prevents a cascade of aborts and wasted work
+
+---
+
+## The Collaborative Scheduler
+
+The collaborative scheduler is the performance-critical core of Block-STM. It coordinates validation and execution tasks among threads with minimal synchronization overhead.
+
+```mermaid
+graph LR
+ subgraph "Thread Pool"
+ T1[Thread 1]
+ T2[Thread 2]
+ T3[Thread 3]
+ TN[Thread N]
+ end
+
+ subgraph "Atomic Counters"
+ EC[Execution Index]
+ VC[Validation Index]
+ end
+
+ T1 --> EC
+ T2 --> VC
+ T3 --> EC
+ TN --> VC
+```
+
+A naive approach would use priority queues to track execution and validation tasks, but concurrent ordered sets are notoriously challenging to scale. Block-STM sidesteps this by using atomic counters that track a lower bound index for transactions needing execution or validation.
+
+Threads repeatedly:
+1. Fetch-and-increment the counter with the lower index
+2. Check the transaction's status
+3. Execute or validate if the transaction is ready
+
+The fetch-and-increment naturally disperses threads to different indices, preventing contention on status information.
+
+### Avoiding Cascading Aborts
+
+When a transaction fails validation, its write set marks all its writes as `ESTIMATE` in the multi-version data structure. When another transaction reads an `ESTIMATE` value, it waits for the dependency to be resolved rather than proceeding blindly.
+
+This is more efficient than pre-executing all transactions from the initial state because:
+- Estimates are generated only when needed
+- Estimates are based on a state much fresher than the block's beginning
+
+---
+
+## Transaction Lifecycle in Block-STM
+
+```mermaid
+stateDiagram-v2
+ [*] --> Submitted: Client Request
+ Submitted --> Mempool: Signature & Balance Checks
+ Mempool --> Ordered: Block Proposal
+ Ordered --> Executing: Scheduled
+ Executing --> Executed: Complete
+ Executed --> Validating: Check Read Set
+ Validating --> Valid: No Conflicts
+ Validating --> Executing: Conflict Detected
+ Valid --> Committed: All Prior Valid
+ Committed --> [*]
+```
+
+1. **Submission**: Client sends transaction to a fullnode or validator
+2. **Mempool**: Nodes verify signatures, minimum balances, and sequence numbers for replay protection
+3. **Block Proposal**: Leader selects transactions and proposes an ordering
+4. **Parallel Execution**: Transactions execute concurrently on available threads
+5. **Validation**: Each transaction's read set is compared against current values
+6. **Re-execution**: Invalid transactions are rescheduled with `ESTIMATE` markers
+7. **Commitment**: Once all prior transactions are valid, the block commits
+
+A transaction is not safe to commit until all transactions before it in the preset order have been executed and validated - a failed validation of an earlier transaction requires revalidation of all later ones.
+
+---
+
+## Performance Characteristics
+
+Block-STM achieves remarkable performance by dynamically adapting to workload characteristics:
+
+:::info Performance Results
+With 32 threads processing 10,000 peer-to-peer Move transactions (8 reads, 5 writes each):
+- **Low contention**: 16x speedup over sequential execution
+- **High contention**: 8x speedup over sequential execution
+- **Sequential workload**: Minimal overhead
+:::
+
+The system automatically extracts available parallelism without hints from users. Under low contention, it approaches the theoretical maximum speedup. Under high contention, it gracefully degrades while still providing substantial improvements over sequential execution.
+
+Importantly, when the workload is inherently sequential (worst case), Block-STM incurs only small overhead compared to sequential execution.
+
+---
+
+## Why This Matters for Developers
+
+Block-STM provides transparent parallel execution - developers write smart contracts without worrying about concurrency:
+
+**No Dependency Declarations**: Unlike systems that require upfront specification of accessed accounts, Block-STM handles everything automatically. Write your logic; the system figures out the rest.
+
+**Arbitrary Logic Supported**: Because dependencies are discovered at runtime, transactions can contain complex, conditional logic that accesses different resources based on state.
+
+**Better User Experience**: Users don't need to structure their transactions around parallelization requirements or retry failed transactions due to incorrect dependency specifications.
+
+**Consistent Results**: Despite parallel execution, the results are guaranteed to match sequential execution in the preset order - perfect for blockchain's determinism requirements.
+
+---
+
+## Summary
+
+Block-STM is Cedra's parallel execution engine that achieves high throughput without sacrificing developer experience or flexibility:
+
+- **Optimistic execution** proceeds without waiting for locks, validating afterward
+- **Multi-version data structures** track all writes with versions for conflict detection
+- **ESTIMATE markers** prevent cascading aborts when conflicts are detected
+- **Collaborative scheduling** with atomic counters minimizes synchronization overhead
+- **Preset ordering** simplifies conflict resolution and guarantees determinism
+- **Transparent operation** requires no dependency declarations from developers
+
+The result: over 160,000 transactions per second with the flexibility to support arbitrary smart contract logic.
+
+---
+
+## Learn More
+
+- [Blockchain Architecture](/concepts/blockchain) - Overall system design
+- [Understanding Transactions](/concepts/transactions/understanding-transactions) - Transaction structure and lifecycle
+- [States and Transitions](/concepts/transactions/states) - How state evolves
diff --git a/docs/concepts/blockchain.md b/docs/concepts/blockchain.md
index 7e1ec42..9db29c4 100644
--- a/docs/concepts/blockchain.md
+++ b/docs/concepts/blockchain.md
@@ -7,6 +7,7 @@ Cedra is a high-performance blockchain built on Move language technology, design
Before diving deeper, let's establish the fundamental concepts:
+- **[Accounts](/concepts/accounts/understanding-accounts)**: Entities that hold assets and can submit transactions
- **[Transactions](/concepts/transactions/understanding-transactions)**: Atomic operations that change the blockchain state
- **Blocks**: Containers that group multiple transactions for processing
- **Validators**: Network participants that execute transactions and reach consensus
@@ -50,7 +51,7 @@ Valid transactions spread across the network through a gossip protocol. Each val
Validators take turns acting as block proposers. The current leader selects transactions from the mempool, prioritizing by gas price and other factors, and forms them into a proposed block.
#### Execution Stage
-Cedra employs parallel execution through Block-STM technology. Multiple transactions execute simultaneously with optimistic concurrency control. The system tracks read and write operations, detecting and resolving conflicts automatically.
+Cedra employs parallel execution through [Block-STM](/concepts/block-stm) technology. Multiple transactions execute simultaneously with optimistic concurrency control. The system tracks read and write operations, detecting and resolving conflicts automatically.
#### Commitment Stage
After execution, validators must agree on the results. Once consensus is reached with a quorum of validators, the block and its effects become permanent. The state changes are applied, and the transactions are irreversibly committed to the blockchain.
@@ -253,7 +254,7 @@ Only after passing all validation does a block become part of the permanent bloc
Key architectural decisions enable Cedra's performance:
- Layered network architecture separates concerns and protects validators
-- Parallel execution through Block-STM maximizes throughput
+- Parallel execution through [Block-STM](/concepts/block-stm) maximizes throughput
- BFT consensus ensures agreement without lengthy confirmation periods
- Sophisticated state management enables efficient verification
@@ -268,4 +269,12 @@ For detailed technical understanding of specific components:
### Transaction System
- **[Understanding Transactions](/concepts/transactions/understanding-transactions)** - Complete guide to transaction anatomy, types, and lifecycle
- **[States and State Transitions](/concepts/transactions/states)** - How the blockchain state evolves through transactions
-- **[Proofs and Verification](/concepts/transactions/proofs-and-verification)** - Cryptographic proofs enabling trustless verification
\ No newline at end of file
+- **[Proofs and Verification](/concepts/transactions/proofs-and-verification)** - Cryptographic proofs enabling trustless verification
+
+### Accounts
+- **[Understanding Accounts](/concepts/accounts/understanding-accounts)** - Account addresses, types, and access control
+- **[Authentication](/concepts/accounts/authentication)** - Auth schemes, multisig, and key rotation
+- **[Resources](/concepts/accounts/resources)** - How Move resources enable per-account storage
+
+### Execution
+- **[Block-STM Parallel Execution](/concepts/block-stm)** - How Cedra achieves 160k+ TPS through optimistic concurrency
\ No newline at end of file
diff --git a/docs/getting-started/counter.md b/docs/getting-started/counter.md
index b7f02b7..d3e835d 100644
--- a/docs/getting-started/counter.md
+++ b/docs/getting-started/counter.md
@@ -104,7 +104,9 @@ module counter::simple_counter {
## π§ͺ Step 3: Add Tests
-Let's add comprehensive tests to our contract. Add the following test functions to your `tests/counter.move` file:
+Let's add comprehensive tests to our contract. For a complete guide on Move testing including annotations and best practices, see [Move Unit Testing](/move/testing).
+
+Add the following test functions to your `tests/counter.move` file:
```rust
#[test_only]
diff --git a/docs/glossary.md b/docs/glossary.md
index 7c194d5..abee67e 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -1,24 +1,25 @@
# Glossary
-## Core Concepts
-### Blockchain
+### Core Concepts
+
+#### Blockchain
A distributed digital ledger that records transactions across many computers so that the record cannot be altered retroactively.
-### Decentralization
+#### Decentralization
The process of distributing and dispersing power away from a central authority. In blockchain, it means no single entity controls the network.
-### Distributed Ledger
+#### Distributed Ledger
A database that is consensually shared and synchronized across multiple sites, institutions, or geographies.
-### Node
+#### Node
A node is any device that participates in a blockchain network. Nodes maintain a copy of the ledger and may help validate or relay transactions.
-#### Types of Nodes:
+**Types of Nodes:**
- **Full Node**: Stores the entire blockchain and validates blocks/transactions
- **Light Node (Light Client)**: Stores only essential parts (e.g., block headers) and relies on full nodes for data
-- **Archive Node**: A full node with historical state data β useful for explorers and analytics
+- **Archive Node**: A full node with historical state data - useful for explorers and analytics
- **Miner Node / Validator Node**: Performs consensus (mining or validating blocks)
:::info How to Create a Node
@@ -31,7 +32,7 @@ The type of node depends on your goal:
- **Validator/Miner** = to secure the network (requires staking or computing power)
:::
-### Miners
+#### Miners
Miners are nodes in Proof of Work (PoW) systems (like Bitcoin) that compete to solve cryptographic puzzles to create the next block. Miners exist only in PoW-based networks. You won't find miners in Proof of Stake systems.
**Role:**
@@ -41,7 +42,7 @@ Miners are nodes in Proof of Work (PoW) systems (like Bitcoin) that compete to s
**Node type:** Specialized full node with mining software/hardware (e.g., ASICs for Bitcoin)
-### Validators
+#### Validators
Validators are nodes in Proof of Stake (PoS) systems (like Ethereum 2.0, Solana) that are chosen to propose and attest to blocks based on the amount of cryptocurrency they've staked. Validators exist only in PoS-based networks. You won't find validators in pure PoW systems.
**Role:**
@@ -52,12 +53,12 @@ Validators are nodes in Proof of Stake (PoS) systems (like Ethereum 2.0, Solana)
**Node type:** Full node running validator software, requires a stake (e.g., 32 ETH for Ethereum)
:::warning Can a network have both miners and validators?
-In most mainstream blockchains β **no**. A network typically uses either PoW (with miners) or PoS (with validators), not both. They are designed for different consensus mechanisms.
+In most mainstream blockchains - **no**. A network typically uses either PoW (with miners) or PoS (with validators), not both. They are designed for different consensus mechanisms.
However, some experimental or hybrid blockchains (e.g., Decred) use both mechanisms together, where miners produce blocks and validators approve them. But this is not common in major protocols like Bitcoin, Ethereum, Solana, or Polygon.
:::
-### Clients
+#### Clients
A client is the software implementation of the blockchain protocol. It allows a node to join the network.
**Role:**
@@ -70,46 +71,46 @@ A client is the software implementation of the blockchain protocol. It allows a
- **Bitcoin Clients**: Bitcoin Core
- **Solana Client**: Solana Validator
-### Consensus Mechanism
+#### Consensus Mechanism
A system used to agree on the state of the blockchain.
**Examples**: Proof of Work (PoW), Proof of Stake (PoS), Proof of History (PoH), etc.
-### Epoch
-An epoch is a defined period of time in a blockchain system, during which certain operations occur β like validator selection, reward distribution, or checkpoint creation.
+#### Epoch
+An epoch is a defined period of time in a blockchain system, during which certain operations occur - like validator selection, reward distribution, or checkpoint creation.
**Where It's Used:**
- **Ethereum 2.0 (Proof of Stake)**: Epochs group 32 slots (blocks), and validators are shuffled during epoch transitions
- **Cardano, Solana, Polkadot**: Epochs are used to manage validator cycles and staking rewards
-### Genesis Block
+#### Genesis Block
The genesis block is the first block of a blockchain. It serves as the root from which all subsequent blocks originate. It is hardcoded into the protocol and typically has no previous block.
-### Reward Emission in PoS Networks
+#### Reward Emission in PoS Networks
Emission is the protocol-driven creation of new tokens, a form of controlled inflation, which occurs according to network rules.
**How it works:**
-- The blockchain protocol itself "mints" new coins each block or epoch β they did not previously exist
+- The blockchain protocol itself "mints" new coins each block or epoch - they did not previously exist
- These tokens are added directly into the ledger by the system (similar to a system-generated transaction)
- Validators and delegators receive most of the newly minted tokens as block rewards
- A portion may go to a treasury fund or foundation
- Some networks burn part of the transaction fees
:::note
-In PoS blockchains, validators don't just collect user fees β they receive newly created tokens from the protocol's inflation model. These tokens are automatically minted by the protocol during block or epoch creation.
+In PoS blockchains, validators don't just collect user fees - they receive newly created tokens from the protocol's inflation model. These tokens are automatically minted by the protocol during block or epoch creation.
:::
-### Crypto Primitives in Blockchain
+#### Crypto Primitives in Blockchain
Cryptographic primitives are the basic building blocks of cryptographic systems used in blockchain to ensure security, integrity, and authenticity.
-#### Essential Crypto Primitives:
+**Essential Crypto Primitives:**
1. **Hash Functions** (e.g., SHA-256, Keccak)
- One-way functions used to create unique fingerprints of data
- Used in: Bitcoin, Ethereum, Solana (uses SHA-256 + SHA-512)
2. **Public-Key Cryptography**
- - A pair of keys β one public, one private β is used to encrypt, decrypt, and sign data
+ - A pair of keys - one public, one private - is used to encrypt, decrypt, and sign data
3. **Digital Signatures** (e.g., ECDSA, Ed25519)
- Allow users to prove ownership and authorize transactions
@@ -120,86 +121,342 @@ Cryptographic primitives are the basic building blocks of cryptographic systems
- Reduces the amount of data needed to verify integrity
- Used in: Bitcoin, Ethereum (in receipts and logs), others
-π [Learn more about crypto primitives](https://cryptobook.nakov.com/)
-
| Blockchain | Hashing | Signature | Other |
|------------|---------|-----------|--------|
| Bitcoin | SHA-256 | ECDSA | Merkle Tree |
| Ethereum | Keccak-256 | ECDSA | Merkle Patricia Trie |
| Solana | SHA-256 + SHA-512 | Ed25519 | Flat account state |
-## Blockchain Trilemma
+### Structures and Operations
+
+#### Block
+A unit of data in the blockchain that contains transactions, a timestamp, and a reference (hash) to the previous block.
+
+#### Transaction
+A record of an operation (e.g., sending cryptocurrency) stored in a block.
+
+#### Smart Contract
+A self-executing contract with the terms directly written into code.
+
+**Example**: An escrow system where funds are released only after certain conditions are met.
+
+#### Gas
+A unit that measures the amount of computational effort required to execute operations.
+
+#### Wallet
+A digital tool (software or hardware) that allows users to store and manage their cryptocurrencies.
+
+#### Private Key & Public Key
+A cryptographic pair. The private key is kept secret and used to sign transactions, while the public key is shared and used to verify them.
+
+---
+
+## Cedra Blockchain
+
+#### Cedra
+A community-owned blockchain built on the Move language, enabling developers to create secure smart contracts with native asset safety guarantees.
+
+#### CED
+The native token of the Cedra blockchain, used for paying gas fees and staking.
+
+#### Octas
+The smallest unit of CED. 1 CED = 100,000,000 Octas
+
+#### Devnet
+Development network for testing features. URL: `https://devnet.cedra.dev`. Tokens have no real value and the network may be reset.
+
+#### Testnet
+Testing network for pre-production validation. URL: `https://testnet.cedra.dev`. More stable than devnet, used for final testing before mainnet.
+
+#### Mainnet
+The production network where real value transactions occur.
+
+#### Cedrascan
+Block explorer for viewing transactions, accounts, and modules on the Cedra blockchain.
+
+#### Faucet
+A service that provides free test tokens for development on devnet and testnet.
+
+### Execution & Performance
+
+#### Sequence Number
+A transaction counter for each account that prevents replay attacks. Unlike Ethereum's nonce, Cedra allows parallel transaction submission with different sequence numbers.
+
+#### Parallel Execution
+Cedra's ability to process multiple transactions simultaneously using optimistic concurrency control, significantly increasing throughput.
+
+#### Block-STM
+Technology enabling parallel transaction execution with automatic conflict detection and resolution. Transactions are speculatively executed in parallel and re-executed only if conflicts occur. See [Block-STM Parallel Execution](/concepts/block-stm) for details.
+
+#### Instant Finality
+Transactions become irreversible immediately after consensus is reached. No need to wait for multiple block confirmations.
+
+#### BFT Consensus
+Byzantine Fault Tolerant consensus mechanism that can tolerate up to 1/3 of validators acting maliciously while still reaching agreement.
-The **Blockchain Trilemma** is a term popularized by Ethereum co-founder Vitalik Buterin to describe the challenge of achieving three key objectives in blockchain networks simultaneously:
+### Accounts & Storage
-### The Three Pillars
+#### Account Address
+A 32-byte identifier for an account on Cedra, typically shown as a hex string prefixed with `0x`. In Move code, addresses are prefixed with `@`.
-1. **Decentralization**
- - The network is not controlled by a single entity or small group
- - Anyone can participate in validating transactions and governing the system
+#### Authentication Key
+The cryptographic identity of an account, derived from the public key. Can be rotated without changing the account address.
-2. **Security**
- - The network is resistant to attacks, manipulation, or failure
- - It protects user data, funds, and transaction integrity
+#### Global Storage
+Blockchain state where resources with the `key` ability are stored. Organized by address and type - each address can hold at most one instance of each resource type.
-3. **Scalability**
- - The ability of the blockchain to handle a growing number of transactions per second (TPS)
- - Without slowing down or becoming expensive
+#### Type-indexed Storage
+Storage organized by type rather than arbitrary slots. Each resource type is stored exactly once per account, preventing slot collision bugs.
-### Trade-offs
+---
-Most blockchains can effectively optimize only two of these three properties at any given time:
+## Move Language
-- **Bitcoin**: Prioritizes security and decentralization, but sacrifices scalability (low TPS)
-- **Solana**: Focuses on scalability and security, but critics argue it may reduce decentralization due to high hardware requirements
-- **Ethereum (Pre-2.0)**: Strong in decentralization and security, but struggles with scalability β hence high gas fees during peak use
+### Core Concepts
+#### Move
+A resource-oriented programming language designed for safe digital asset management on blockchains. Move's type system prevents common bugs like double-spending and asset loss at compile time.
+
+#### Module
+The fundamental unit of code organization in Move. A module contains structs, functions, and constants, and is deployed at a specific blockchain address. Modules define the logic for interacting with resources.
+
+```rust
+module my_address::my_module {
+ // structs, functions, constants
+}
```
- Decentralization
- /\
- / \
- / \
- / \
- / \
- /__________\
- Security Scalability
+
+#### Resource
+A special type in Move that cannot be copied or accidentally dropped. Resources ensure digital assets are handled safely - they must be explicitly moved, stored, or destroyed.
+
+#### Struct
+A custom data type that groups related fields together. Structs can have abilities that control how they behave.
+
+```rust
+struct Token has key, store {
+ value: u64,
+}
```
-In this triangle, most projects lie toward one side and must make trade-offs. Solving the trilemma means finding a system design that balances all three without major compromises β a current goal of innovation in blockchain technology.
+#### Linear Type System
+Move's type system that ensures resources exist in exactly one location at any time. Values must be explicitly moved, preventing duplication or loss of assets.
-### Solutions Being Developed
+### Abilities
-To address the trilemma, developers and researchers are working on:
-- Layer 2 Solutions (e.g., Optimistic Rollups, zk-Rollups)
-- Sharding (breaking the blockchain into smaller pieces)
-- New Consensus Mechanisms (e.g., Proof of Stake, Delegated PoS)
-- Interoperability Protocols (e.g., Polkadot, Cosmos)
+#### Ability
+A property granted to structs that controls what operations are allowed on instances of that type. Move has four abilities: `copy`, `drop`, `store`, and `key`.
-## Blockchain Structures and Operations
+#### copy
+Allows a struct to be duplicated. Use for data that doesn't represent scarce resources (like configuration or counters). Resources representing assets typically don't have this ability.
-### Block
-A unit of data in the blockchain that contains transactions, a timestamp, and a reference (hash) to the previous block.
+#### drop
+Allows a struct to be discarded when it goes out of scope. Without `drop`, the compiler enforces that values must be explicitly handled, preventing accidental loss.
-### Transaction
-A record of an operation (e.g., sending cryptocurrency) stored in a block.
+#### store
+Allows a struct to be stored inside other structs or in global storage containers. Required for types that need to persist on-chain as part of other resources.
-### Smart Contract
-A self-executing contract with the terms directly written into code.
+#### key
+Allows a struct to exist as a top-level resource in global storage. Only one instance of a `key` type can exist per address. This is the foundation for account-based storage.
-**Example**: An escrow system where funds are released only after certain conditions are met.
+### Functions & Visibility
-### Gas
-A unit that measures the amount of computational effort required to execute operations.
+#### Entry Function
+A function marked with `entry` that can be called directly from transactions. Entry functions cannot return values and serve as the public interface for user interactions.
-### Wallet
-A digital tool (software or hardware) that allows users to store and manage their cryptocurrencies.
+```rust
+public entry fun transfer(from: &signer, to: address, amount: u64) { ... }
+```
-### Private Key & Public Key
-A cryptographic pair. The private key is kept secret and used to sign transactions, while the public key is shared and used to verify them.
+#### Public Function
+A function accessible from other modules using the `public` keyword. Public functions form the API of a module and can be called by any other module.
+
+#### Friend Function
+A function using `public(friend)` visibility, accessible only to specifically declared friend modules. Useful for controlled access between related modules.
+
+#### View Function
+A read-only function marked with `#[view]` that doesn't modify state. View functions can be called without creating a transaction, making them free to execute.
+
+#### Signer
+A special type representing transaction authority. A `&signer` reference proves the caller has permission to perform operations on behalf of an account.
+
+#### Acquires
+An annotation required on functions that read from or modify global storage. Helps prevent reentrancy attacks by making storage access explicit.
+
+```rust
+public fun get_balance(addr: address): u64 acquires Balance { ... }
+```
+
+### Ownership & Storage
+
+#### Ownership
+In Move, every value has exactly one owner. When a value is assigned to a new variable or passed to a function, ownership transfers (the value "moves").
+
+#### Borrow
+Accessing data through references without taking ownership. Borrowing allows temporary access while the original owner retains the value.
+
+#### Immutable Reference (&)
+A read-only reference to data. Multiple immutable references can exist simultaneously, allowing shared read access.
+
+#### Mutable Reference (&mut)
+A reference that allows modification of borrowed data. Only one mutable reference can exist at a time, ensuring exclusive write access.
+
+#### borrow_global
+Function to obtain an immutable reference to a resource stored in global storage at a specific address.
+
+```rust
+let token = borrow_global(addr);
+```
+
+#### borrow_global_mut
+Function to obtain a mutable reference to a resource in global storage, allowing modification.
+
+```rust
+let token = borrow_global_mut(addr);
+token.value = token.value + 1;
+```
+
+#### move_to
+Operation that publishes a resource to global storage at an address. The signer must own the address.
+
+```rust
+move_to(account, Token { value: 100 });
+```
+
+#### move_from
+Operation that removes a resource from global storage and returns it. The resource must exist at the specified address.
+
+#### exists\
+Function to check if a resource of type T exists at a given address. Returns `true` or `false`.
+
+```rust
+if (exists(addr)) { ... }
+```
+
+### Patterns
+
+#### Capability Pattern
+Using resource types as proof of authorization. Holding a capability resource grants permission to perform specific operations. The capability itself is the access control.
+
+```rust
+struct AdminCap has key, store {}
+
+public fun admin_only(cap: &AdminCap) { ... }
+```
+
+#### Hot Potato Pattern
+A resource without any abilities (`copy`, `drop`, `store`, `key`) that must be handled immediately within the same transaction. Forces atomic operations and prevents partial execution.
+
+#### Witness Pattern
+A one-time use type that proves initialization has occurred. Typically has only the `drop` ability, ensuring it can only be used once and then discarded.
+
+#### Phantom Type
+A type parameter that doesn't appear in struct fields but provides compile-time type safety. Used to distinguish between different instances of the same structure.
+
+```rust
+struct Coin has store {
+ value: u64,
+}
+```
+
+---
+
+## Fungible Assets (FA)
+
+### Core Concepts
+
+#### Fungible Asset (FA)
+Cedra's token standard that replaces ERC-20-style patterns with ownable objects. FA provides safer, cheaper, and more composable token operations.
+
+#### FungibleStore
+An object that holds a user's balance for a specific fungible asset. Each holder has their own store for each token type they own.
+
+#### Metadata
+An object storing token information including name, symbol, decimals, icon URI, and supply tracking. Acts as the token's identity and admin account.
+
+#### Primary Fungible Store
+The default storage location for an account's FA balance. Created lazily on first receipt - no manual registration required.
+
+#### Object
+A first-class on-chain entity with a unique address. Objects can own resources and other objects, enabling complex ownership hierarchies.
+
+### Capabilities
+
+#### MintRef
+A capability granting permission to create new tokens (inflate supply). Only holders of this reference can mint.
+
+#### BurnRef
+A capability granting permission to destroy tokens (deflate supply). Controls token removal from circulation.
+
+#### TransferRef
+A capability enabling token movement without the owner's signature. Used for escrow and automated transfer scenarios.
+
+#### FreezeRef
+A capability to pause transfers from a specific store. Used for compliance or security freezes on suspicious accounts.
+
+---
+
+## Development
+
+### Package Management
+
+#### Move.toml
+The package manifest file that defines dependencies, named addresses, and compilation settings for a Move project.
+
+```toml
+[package]
+name = "my_project"
+version = "1.0.0"
+
+[addresses]
+my_project = "0x1"
+
+[dependencies]
+CedraFramework = { git = "..." }
+```
+
+#### Named Address
+An alias for a blockchain address used in code, resolved at compile time. Allows the same code to be deployed to different addresses.
+
+#### Package
+A collection of Move modules with their dependencies, compiled and deployed together as a unit.
+
+#### Upgrade Policy
+Rules governing how a deployed package can be modified. Cedra supports `compatible` (backward-compatible changes only) and `immutable` (no changes allowed).
+
+#### Compatible Upgrade
+A package update that preserves backward compatibility - existing struct layouts and public function signatures remain unchanged.
+
+#### Immutable Package
+Code that cannot be upgraded after deployment. Provides maximum trust guarantees that behavior will never change.
+
+#### Chunked Publishing
+A method for deploying packages larger than 64KB by splitting bytecode into multiple transactions that are staged and assembled on-chain.
+
+### CLI & Tools
+
+#### Cedra CLI
+The command-line interface for Move development on Cedra. Supports compiling, testing, publishing, and interacting with contracts.
+
+```bash
+cedra move compile
+cedra move test
+cedra move publish
+```
+
+#### @cedra-labs/ts-sdk
+The official TypeScript SDK for building applications that interact with the Cedra blockchain.
+
+#### Transaction Simulation
+A dry-run of a transaction to estimate gas costs and verify it will succeed before actually submitting it to the network.
+
+#### Profile
+A CLI configuration for different networks (devnet, testnet, mainnet). Profiles store endpoint URLs and account credentials.
+
+---
## Ecosystem & Use Cases
-### Oracle
+#### Oracle
A blockchain oracle is a service that connects smart contracts to external data sources, enabling them to access information that exists outside the blockchain (also called off-chain data).
| Type of Oracle | Description |
@@ -211,26 +468,26 @@ A blockchain oracle is a service that connects smart contracts to external data
| **Human** | Verified individuals provide data input manually |
| **Decentralized** (e.g. Chainlink) | Uses multiple sources and consensus to prevent manipulation |
-### dApp (Decentralized Application)
+#### dApp (Decentralized Application)
An application that runs on a decentralized network rather than a single server.
-### DeFi (Decentralized Finance)
+#### DeFi (Decentralized Finance)
Financial services without traditional intermediaries like banks.
**Examples**: Lending platforms, DEXs (Decentralized Exchanges)
-### NFT (Non-Fungible Token)
+#### NFT (Non-Fungible Token)
Unique digital assets that represent ownership of specific items or content, often used in art, gaming, or music.
-### DAO (Decentralized Autonomous Organization)
+#### DAO (Decentralized Autonomous Organization)
An organization governed by smart contracts and voting systems rather than central leadership.
-### Layer 1 vs Layer 2
+#### Layer 1 vs Layer 2
-- **L1 (Layer 1)**: The base blockchain (e.g., Ethereum) β secure but limited in throughput
-- **L2 (Layer 2)**: Built on top of L1 to scale it β processes many transactions off-chain or in batches, then submits the result back to L1
+- **L1 (Layer 1)**: The base blockchain (e.g., Ethereum) - secure but limited in throughput
+- **L2 (Layer 2)**: Built on top of L1 to scale it - processes many transactions off-chain or in batches, then submits the result back to L1
-#### Transaction Flow:
+**Transaction Flow:**
1. The user interacts with the L2 app (e.g., Arbitrum, Optimism)
2. Transaction processed on L2 (fast, cheap)
3. Periodically, L2 sends a proof or summary (e.g., rollup, zk-proof, state root) back to L1
@@ -244,27 +501,33 @@ An organization governed by smart contracts and voting systems rather than centr
L1 always acts as the source of truth, ensuring that L2 cannot cheat (disputes or fraud proofs are used if needed).
:::
+---
+
## Security & Risks
-### 51% Attack
+#### 51% Attack
When an entity gains over 50% of the network's hashing power, potentially allowing them to double-spend or block transactions.
-### Rug Pull
+#### Rug Pull
A type of scam where project creators take investor funds and disappear.
-### Phishing
+#### Phishing
Fraudulent attempts to obtain sensitive information such as private keys or seed phrases.
-### Re-Entrancy Attack
+#### Re-Entrancy Attack
A vulnerability in smart contracts where an external contract calls back into the original contract before the first execution is finished, often used to drain funds.
-**Example**: The DAO hack on Ethereum in 2016 β ~$60M lost due to improper state updates before fund transfers.
+**Example**: The DAO hack on Ethereum in 2016 - ~$60M lost due to improper state updates before fund transfers.
**Prevention:**
- Update state before external calls
- Use reentrancy guards (e.g., mutex or `nonReentrant` in Solidity)
-### Sandwich Attack
+:::tip Move's Safety
+Move's `acquires` annotation and linear type system prevent reentrancy attacks by design. Functions must declare what resources they access, and resources cannot be borrowed twice simultaneously.
+:::
+
+#### Sandwich Attack
Occurs in DeFi and DEXs where an attacker front-runs and back-runs a user's transaction to profit from price manipulation.
**How it works:**
@@ -278,22 +541,24 @@ Occurs in DeFi and DEXs where an attacker front-runs and back-runs a user's tran
- Slippage control
:::
-## Developer Essentials
+---
+
+## Other Developer Tools
-### Solidity
+#### Solidity
The main programming language for Ethereum smart contracts.
-### EVM (Ethereum Virtual Machine)
+#### EVM (Ethereum Virtual Machine)
The environment in which all Ethereum smart contracts run.
-### Web3.js / Ethers.js
+#### Web3.js / Ethers.js
JavaScript libraries to interact with Ethereum and smart contracts.
-### RPC (Remote Procedure Call)
+#### RPC (Remote Procedure Call)
A communication protocol used to interact with blockchain nodes.
-### CLI
-CLI is a text-based interface used to interact with blockchain clients or tools via terminal/command prompt. It offers full control, automation, and low-level interaction β essential for developers and node operators.
+#### CLI
+CLI is a text-based interface used to interact with blockchain clients or tools via terminal/command prompt. It offers full control, automation, and low-level interaction - essential for developers and node operators.
**Use Cases in Blockchain:**
- Deploy and interact with smart contracts
@@ -301,9 +566,7 @@ CLI is a text-based interface used to interact with blockchain clients or tools
- Query network data
- Set up validators or nodes
-**Examples**: `cedra-cli`, `solana-cli`, `near-cli`, `geth`, `hardhat`, `eth-cli`
-
-### Zero-Knowledge Proof
+#### Zero-Knowledge Proof
A Zero-Knowledge Proof is a cryptographic method that allows one party (the prover) to convince another (the verifier) that a statement is true without revealing any information beyond the fact that the statement is indeed true.
There are multiple types, such as: zk-SNARKs, zk-STARKs, Bulletproofs, etc.
@@ -312,7 +575,7 @@ There are multiple types, such as: zk-SNARKs, zk-STARKs, Bulletproofs, etc.
- **Privacy**: Proves knowledge or computation without revealing sensitive data
- **Integrity**: Ensures computations are done correctly, useful in blockchains and authentication
-### Blockchain Bridge
+#### Blockchain Bridge
A blockchain bridge connects two separate blockchains, allowing assets or data to be transferred between them.
**A blockchain bridge allows:**
@@ -325,7 +588,7 @@ A blockchain bridge connects two separate blockchains, allowing assets or data t
- **Liquidity fragmentation**: Helps use tokens across chains without siloing liquidity
:::note Why are bridges needed?
-Bridges are needed because most blockchains are not natively compatible β Bitcoin, Ethereum, Solana, etc., all use different consensus mechanisms, address formats, and virtual machines.
+Bridges are needed because most blockchains are not natively compatible - Bitcoin, Ethereum, Solana, etc., all use different consensus mechanisms, address formats, and virtual machines.
:::
**Problems Solved by Bridges:**
@@ -333,36 +596,3 @@ Bridges are needed because most blockchains are not natively compatible β Bitc
- **DeFi composability**: Use an asset on multiple platforms (e.g., stake ETH on Avalanche)
- **Network scalability**: Offload transactions to layer-2s or sidechains
- **Cross-chain dApps**: Combine functionality across chains (e.g., an app using Solana speed + Ethereum security)
-
-## How Bridges Are Built (Mechanisms)
-
-### 1. Trusted (Centralized) Bridges
-- Operated by a central custodian (e.g., Binance Bridge)
-- The user sends assets to a controlled wallet on Chain A
-- Equivalent tokens are minted on Chain B by the custodian
-
-**Risks:**
-- Custodian key compromise
-- Lack of transparency
-
-### 2. Federated (Multi-sig / MPC) Bridges
-- A set of validators (e.g., 5-of-7 multisig) manage asset locking and minting
-- Can use MPC (Multi-party computation) for managing shared signing keys
-- More decentralized than custodial bridges, but still not trustless
-
-**Risks:**
-- Collusion among validators
-- Still partially trusted
-
-### 3. Trustless (Smart Contract + ZKP + Light Client) Bridges
-Rely on on-chain verification of state transitions or proofs. Most secure and decentralized form.
-
-**How it works:**
-1. **On Chain A**: A user locks or burns tokens. A zk-proof is generated attesting that this event occurred according to Chain A's consensus rules
-2. **Proof Generation**: A zk-circuit models the consensus & logic. Generates a validity proof (e.g., zk-SNARK or zk-STARK)
-3. **On Chain B**: A smart contract verifies the zk-proof. If the proof is valid, a wrapped token is minted or an action is executed
-
-**Challenges and Limitations:**
-- **Heavy setup cost**: circuit design and proof generation can be complex
-- **Proof generation cost**: still CPU/GPU intensive (especially zk-STARKs)
-- **Still experimental**: fewer projects use it in production compared to MPC or multisig bridges
\ No newline at end of file
diff --git a/docs/indexer/index.mdx b/docs/indexer/index.mdx
index 45e1d9e..0fc5ac5 100644
--- a/docs/indexer/index.mdx
+++ b/docs/indexer/index.mdx
@@ -52,7 +52,7 @@ import TabItem from '@theme/TabItem';
Take full control of your data pipeline with the Cedra Indexer SDK. Design custom processors that understand
your smart contract's unique events and data structures, transforming raw blockchain data into precisely the
format your application needs. Define your own schemas, implement complex business logic, and store processed
- data in your preferred databaseβwhether that's PostgreSQL, MongoDB, or a specialized time-series database.
+ data in your preferred database - whether that's PostgreSQL, MongoDB, or a specialized time-series database.
Perfect for protocols with complex on-chain mechanics or applications requiring specialized data transformations
that go beyond standard indexing.
diff --git a/docs/move-package-upgrades.md b/docs/move-package-upgrades.md
index a8e6e1d..d7d53d6 100644
--- a/docs/move-package-upgrades.md
+++ b/docs/move-package-upgrades.md
@@ -168,7 +168,7 @@ struct Token has store, copy { value: u64 }
struct Token { value: u64 } // Removed 'store' - not allowed!
```
-With these rules in mind, you're ready to safely upgrade your packages. If you're unsure whether your changes are compatible, compile with `cedra move compile` firstβthe compiler will catch compatibility violations before you attempt to publish.
+With these rules in mind, you're ready to safely upgrade your packages. If you're unsure whether your changes are compatible, compile with `cedra move compile` first - the compiler will catch compatibility violations before you attempt to publish.
## Next Steps
diff --git a/docs/move/errors.md b/docs/move/errors.md
index aadba94..591c109 100644
--- a/docs/move/errors.md
+++ b/docs/move/errors.md
@@ -509,7 +509,7 @@ Remember: on blockchain, failed transactions still cost gas. Check the cheap con
## Testing Your Error Handling
-Robust code tests both success and failure paths. Move provides excellent tools for testing that your functions fail correctly:
+Robust code tests both success and failure paths. Move provides excellent tools for testing that your functions fail correctly. For comprehensive testing documentation, see [Move Unit Testing](/move/testing).
```rust
#[test_only]
diff --git a/docs/move/modules.md b/docs/move/modules.md
index f243af4..8c7e803 100644
--- a/docs/move/modules.md
+++ b/docs/move/modules.md
@@ -372,22 +372,22 @@ public fun complete_process(receipt: Receipt) {
## Testing Your Modules
-Testing is crucial for confidence in your code:
+Testing is crucial for confidence in your code. For comprehensive testing documentation, see [Move Unit Testing](/move/testing).
```rust
#[test_only]
module 0x42::auction_tests {
use 0x42::auction;
-
+
#[test]
fun test_auction_lifecycle() {
// Setup
let seller = @0x123;
let seller_signer = create_signer_for_test(seller);
-
+
// Create auction
auction::create(seller_signer, item_id, starting_price);
-
+
// Verify state
let (current_bid, leader) = auction::get_status(seller, item_id);
assert!(current_bid == starting_price, 0);
diff --git a/docs/move/testing.md b/docs/move/testing.md
new file mode 100644
index 0000000..445e1a0
--- /dev/null
+++ b/docs/move/testing.md
@@ -0,0 +1,201 @@
+# Move Unit Testing
+
+Unit testing is essential for Move smart contracts where bugs can lead to significant financial losses. Move provides three test annotations that are excluded from compiled bytecode unless compiled for testing.
+
+:::tip Prerequisites
+Before writing tests, ensure you have:
+- β
[Cedra CLI installed](/getting-started/cli)
+- β
[Basic Move knowledge](/move/basics)
+- β
[Understanding of modules](/move/modules)
+:::
+
+The simplest way to create a test is with the `#[test]` annotation. Any function marked with this attribute becomes a test case that runs when you execute `cedra move test`:
+
+```rust
+module 0x42::example {
+ #[test]
+ fun this_is_a_test() {
+ // Test logic here
+ }
+}
+```
+
+Often you'll need code that only exists for testing purposes - helper functions, mock data structures, or debug imports. The `#[test_only]` annotation marks code that should be excluded from production bytecode. You can apply it to entire modules, individual functions, structs, or even use statements:
+
+```rust
+#[test_only]
+module 0x42::test_helpers {
+ // This entire module only exists during testing
+}
+
+module 0x42::my_module {
+ #[test_only]
+ use std::debug;
+
+ #[test_only]
+ struct TestStruct { value: u64 }
+
+ #[test_only]
+ fun helper_function(): u64 { 42 }
+}
+```
+
+## Testing Expected Failures
+
+Sometimes you need to verify that your code fails correctly. The `#[expected_failure]` annotation lets you test that a function aborts under specific conditions:
+
+```rust
+#[test]
+#[expected_failure(abort_code = 0, location = Self)]
+fun test_zero_coin_fails() {
+ let coin = MyCoin { value: 0 };
+ make_sure_non_zero_coin(coin);
+}
+```
+
+This test passes only if the function aborts with code `0` from the current module (`Self`). You can also test for failures from other modules using `location = other::module`, or test for specific error types like `arithmetic_error` for overflow/underflow, `vector_error` with `minor_status = 1` for index out of bounds, or `out_of_gas` for gas exhaustion.
+
+## Working with Signers
+
+Most Move functions that modify state require a `signer` argument. You can inject test signers directly in the test annotation:
+
+```rust
+#[test(a = @0x1, b = @0x2)]
+fun test_with_signers(a: signer, b: signer) {
+ publish_coin(&a);
+ assert!(has_coin(@0x1), 0);
+}
+```
+
+The annotation creates signer values for each specified address, which are then passed to the test function as arguments. Named addresses from your `Move.toml` work too:
+
+```rust
+#[test(admin = @admin)]
+fun test_admin_only(admin: signer) {
+ // admin signer is bound to the 'admin' named address
+}
+```
+
+## Running Tests
+
+Run all tests in your package with:
+
+```bash
+cedra move test
+```
+
+You'll see output showing which tests passed or failed:
+
+```
+Running Move unit tests
+[ PASS ] 0x42::my_module::make_sure_non_zero_coin_passes
+[ PASS ] 0x42::my_module::make_sure_zero_coin_fails
+[ PASS ] 0x42::my_module::test_has_coin
+Test result: OK. Total tests: 3; passed: 3; failed: 0
+```
+
+To run only specific tests, use the filter flag. This runs any test containing "zero_coin" in its name:
+
+```bash
+cedra move test -f zero_coin
+```
+
+For code coverage information, add the `--coverage` flag and then run `cedra move coverage` for a detailed breakdown. Other useful flags include `--gas-limit` to set gas limits per test and `-v` for verbose output.
+
+## Complete Example
+
+Here's a full module demonstrating all the testing concepts together:
+
+```rust
+module 0x1::my_module {
+ struct MyCoin has key { value: u64 }
+
+ const E_ZERO_COIN: u64 = 0;
+
+ public fun make_sure_non_zero_coin(coin: MyCoin): MyCoin {
+ assert!(coin.value > 0, E_ZERO_COIN);
+ coin
+ }
+
+ public fun has_coin(addr: address): bool {
+ exists(addr)
+ }
+
+ // ========== Tests ==========
+
+ #[test]
+ fun make_sure_non_zero_coin_passes() {
+ let coin = MyCoin { value: 1 };
+ let MyCoin { value: _ } = make_sure_non_zero_coin(coin);
+ }
+
+ #[test]
+ #[expected_failure(abort_code = E_ZERO_COIN, location = Self)]
+ fun make_sure_zero_coin_fails() {
+ let coin = MyCoin { value: 0 };
+ let MyCoin { value: _ } = make_sure_non_zero_coin(coin);
+ }
+
+ #[test_only]
+ fun publish_coin(account: &signer) {
+ move_to(account, MyCoin { value: 1 })
+ }
+
+ #[test(a = @0x1, b = @0x2)]
+ fun test_has_coin(a: signer, b: signer) {
+ publish_coin(&a);
+ publish_coin(&b);
+ assert!(has_coin(@0x1), 0);
+ assert!(has_coin(@0x2), 1);
+ assert!(!has_coin(@0x3), 1);
+ }
+}
+```
+
+## Organizing Your Tests
+
+Tests can live in the same file as your production code (convenient for small modules) or in a separate `tests/` directory (better for larger projects):
+
+```
+my_project/
+βββ Move.toml
+βββ sources/
+β βββ my_module.move # Can include inline tests
+βββ tests/
+ βββ my_module_tests.move # Or separate test files
+```
+
+For naming, use `test_` prefix for test functions (like `test_increment`), add `_fails` suffix for expected failures (like `test_zero_balance_fails`), and name test files as `_tests.move`.
+
+## Best Practices
+
+Structure your tests using the **Arrange β Act β Assert** pattern. First set up the test state, then perform the action you're testing, and finally verify the results:
+
+```rust
+#[test(account = @0x1)]
+fun test_counter_increment(account: signer) {
+ // Arrange
+ initialize(&account);
+
+ // Act
+ increment(&account);
+ increment(&account);
+
+ // Assert
+ assert!(get_count(@0x1) == 2, 0);
+}
+```
+
+Each test should focus on one behavior. When a test fails, you want to know exactly what broke. Instead of a single `test_everything` function, write separate tests like `test_increment_from_zero` and `test_increment_from_nonzero`.
+
+Tests should be independent - each one sets up its own state rather than relying on side effects from other tests. This makes tests reliable and order-independent.
+
+Cover all paths through your code: the happy path where everything works, error cases where things fail correctly, and edge cases like zero values or maximum limits. Use descriptive names that explain both what's being tested and what should happen, like `test_transfer_insufficient_balance_fails` or `test_mint_updates_total_supply`.
+
+Finally, keep test setup DRY by extracting common setup logic into `#[test_only]` helper functions that multiple tests can share.
+
+## Next Steps
+
+- [Error Handling](/move/errors) - Define and test abort codes
+- [Counter Tutorial](/getting-started/counter) - Complete example with tests
+- [CLI Usage](/cli/usage) - More testing commands
diff --git a/sidebars.ts b/sidebars.ts
index 3e17c71..adb36b3 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -204,6 +204,11 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
type: 'doc',
id: 'large-packages',
label: 'π Deploying Large Packages'
+ },
+ {
+ type: 'doc',
+ id: 'move/testing',
+ label: 'π§ͺ Unit Testing'
}
]
},
@@ -423,6 +428,32 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
id: 'concepts/blockchain',
label: 'Blockchain'
},
+ {
+ type: 'doc',
+ id: 'concepts/block-stm',
+ label: 'Block-STM Parallel Execution'
+ },
+ {
+ type: 'category',
+ label: 'Accounts',
+ items: [
+ {
+ type: 'doc',
+ id: 'concepts/accounts/understanding-accounts',
+ label: 'Understanding Accounts'
+ },
+ {
+ type: 'doc',
+ id: 'concepts/accounts/authentication',
+ label: 'Authentication'
+ },
+ {
+ type: 'doc',
+ id: 'concepts/accounts/resources',
+ label: 'Resources'
+ }
+ ]
+ },
{
type: 'category',
label: 'Transactions',