midnight-dapp:state-management

State Management

Read, sync, and cache contract state in Midnight DApps with proper handling of the dual-state model.

When to Use

• Reading public ledger state from deployed contracts
• Implementing reactive UI that updates with chain state
• Caching state for performance optimization
• Understanding when to use public vs private state
• Syncing state across multiple components

Key Concepts

Dual-State Model

Midnight contracts have two types of state:

State Type	Storage Location	Access Method	Visibility
Public Ledger State	On-chain (indexer)	contract.state.*	Anyone can read
Private Local State	Browser (LevelDB)	WitnessContext.privateState	Only local user

This is fundamentally different from Ethereum where all state is public on-chain.

State Access Patterns

// Public state - anyone can read
const totalSupply = await contract.state.total_supply();
const balance = await contract.state.balances.get(address);

// Private state - accessed only in witnesses
const witnesses = {
  get_secret: ({ privateState }) => privateState.secretKey,
};

Chain Synchronization

State on-chain can change from other transactions. DApps must handle:

1. Initial Load - Fetch current state when component mounts
2. Polling - Periodically check for updates
3. WebSocket - Subscribe to real-time updates
4. Optimistic Updates - Update UI before confirmation

References

Document	Description
contract-state.md	Reading public and private contract state
chain-sync.md	Synchronization patterns and subscriptions
privacy-aware-caching.md	Safe caching strategies for Midnight
web3-comparison.md	Ethereum state patterns vs Midnight

Examples

Example	Description
use-contract-state/	React hook for reading contract state
state-sync-provider/	Context provider for state synchronization
cache-manager/	Privacy-aware caching utilities

Quick Start

1. Read Simple State Values

// After contract deployment, read public state
const contract = await deployedContract();

// Simple value
const totalSupply: bigint = await contract.state.total_supply();

// Map lookup
const balance: bigint | undefined = await contract.state.balances.get(userAddress);

// Set membership
const isMember: boolean = await contract.state.members.has(userAddress);

2. Create a State Hook

function useContractState<T>(
  contract: Contract,
  accessor: (state: ContractState) => Promise<T>
) {
  const [value, setValue] = useState<T | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    let cancelled = false;

    async function fetchState() {
      setLoading(true);
      const result = await accessor(contract.state);
      if (!cancelled) {
        setValue(result);
        setLoading(false);
      }
    }

    fetchState();
    return () => { cancelled = true; };
  }, [contract, accessor]);

  return { value, loading };
}

3. Subscribe to Updates

// Poll for state changes
useEffect(() => {
  const interval = setInterval(async () => {
    const newBalance = await contract.state.balances.get(address);
    setBalance(newBalance);
  }, 5000); // Poll every 5 seconds

  return () => clearInterval(interval);
}, [contract, address]);

Common Patterns

Type-Safe State Reading

interface ContractState {
  total_supply(): Promise<bigint>;
  balances: {
    get(address: string): Promise<bigint | undefined>;
  };
  members: {
    has(address: string): Promise<boolean>;
  };
}

// The compiler generates these types from your Compact contract

Error Handling

async function safeStateRead<T>(
  accessor: () => Promise<T>,
  fallback: T
): Promise<T> {
  try {
    return await accessor();
  } catch (error) {
    console.error('State read failed:', error);
    return fallback;
  }
}

const balance = await safeStateRead(
  () => contract.state.balances.get(address),
  0n
);

Optimistic Updates

// Update UI immediately, then sync with chain
const [balance, setBalance] = useState<bigint>(0n);

async function transfer(to: string, amount: bigint) {
  // Optimistic update
  setBalance(prev => prev - amount);

  try {
    await contract.callTx.transfer(to, amount, witnesses);
    // State will sync on next poll
  } catch (error) {
    // Revert optimistic update
    setBalance(prev => prev + amount);
    throw error;
  }
}

Related Skills

• wallet-integration - Required for setting up providers
• proof-handling - Witness implementation that accesses private state
• transaction-flows - Submitting state-changing transactions
• error-handling - Handling state read errors

Related Commands

• /dapp-check - Validates provider configuration
• /dapp-debug state - Debug state synchronization issues