Building an Unshielded Token dApp on Midnight with React and Compact

eateLedgerClient } from './ledger-client.mjs';

const app = express(); app.use(express.json());

// Load artifacts generated by the compiler const artifacts = loadCompactArtifacts('./contracts/managed/transparent-asset'); const ledger = createLedgerClient(process.env.MIDNIGHT_NODE_URL);

app.post('/api/issue', async (req, res) => { try { const { recipient, amount } = req.body; // Validate types against Compact schema const validated = artifacts.schemas.issue.validate({ recipient, amount });

    const tx = await ledger.submitTransaction('issue', validated);
    res.json({ status: 'submitted', txHash: tx.hash });
} catch (err) {
    res.status(400).json({ error: err.message });
}

});

app.get('/api/state/:address', async (req, res) => { const { address } = req.params; const state = await ledger.queryState('balances', address); res.json({ balance: state ?? 0n }); });

app.listen(4000, () => console.log('Ledger proxy running on port 4000'));

#### 4. Frontend Integration with React

The React application manages wallet state, user inputs, and balance displays. It communicates with the API bridge via fetch calls.

**Architecture Decision:** We use custom hooks to encapsulate wallet logic and data fetching. This promotes reusability and keeps components clean. `BigInt` is used for all numeric values to prevent precision loss, as JavaScript's `Number` type cannot safely represent large integers common in blockchain contexts.

```typescript
// src/components/AssetManager.tsx
import { useState, useEffect, useCallback } from 'react';
import { useLaceWallet } from '../hooks/useLaceWallet';
import { fetchBalance, submitIssue } from '../services/api';

export const AssetManager = () => {
    const { address, isConnected, connect } = useLaceWallet();
    const [balance, setBalance] = useState<BigInt>(0n);
    const [inputAmount, setInputAmount] = useState<string>('');
    const [isProcessing, setIsProcessing] = useState(false);

    const refreshBalance = useCallback(async () => {
        if (!address) return;
        const data = await fetchBalance(address);
        setBalance(BigInt(data.balance));
    }, [address]);

    useEffect(() => {
        refreshBalance();
    }, [refreshBalance]);

    const handleIssue = async () => {
        if (!address || !inputAmount) return;
        setIsProcessing(true);
        try {
            await submitIssue({
                recipient: address,
                amount: BigInt(inputAmount)
            });
            await refreshBalance();
            setInputAmount('');
        } catch (err) {
            console.error('Issue failed:', err);
        } finally {
            setIsProcessing(false);
        }
    };

    if (!isConnected) {
        return <button onClick={connect}>Connect Lace Wallet</button>;
    }

    return (
        <div className="asset-manager">
            <h2>Transparent Asset Manager</h2>
            <p>Address: {address}</p>
            <p>Balance: {balance.toString()}</p>
            
            <div className="controls">
                <input 
                    type="text" 
                    value={inputAmount} 
                    onChange={(e) => setInputAmount(e.target.value)}
                    placeholder="Amount"
                />
                <button 
                    onClick={handleIssue} 
                    disabled={isProcessing || !inputAmount}
                >
                    {isProcessing ? 'Processing...' : 'Issue Tokens'}
                </button>
            </div>
        </div>
    );
};

Pitfall Guide

Production experience with Midnight reveals specific failure modes. Avoid these common mistakes to ensure stability and correctness.

1. JavaScript Number Precision Loss

   • Explanation: Using Number for token amounts causes silent data corruption for values exceeding Number.MAX_SAFE_INTEGER.
   • Fix: Enforce BigInt for all balance and amount variables. Convert user input strings to BigInt explicitly before transmission.

2. Ignoring Compact Compilation Warnings

   • Explanation: Compact may produce warnings about unused variables or type mismatches that do not halt compilation but cause runtime failures.
   • Fix: Treat warnings as errors. Run npm run doctor or equivalent validation scripts after every contract change. Inspect the managed/ output for completeness.

3. State Drift After Transactions

   • Explanation: The frontend may display stale balances because the ledger state update is asynchronous and the UI does not poll or listen for events.
   • Fix: Implement a refresh mechanism after transaction submission. For production, use WebSocket subscriptions or polling intervals to sync state.

4. Hardcoding Contract Addresses

   • Explanation: Embedding contract addresses in frontend code breaks when deploying to different networks or upgrading contracts.
   • Fix: Inject addresses via environment variables or a configuration service. Support dynamic address resolution based on the connected network.

5. Skipping Artifact Setup

   • Explanation: Cloning a repository without running the setup script results in missing artifacts, causing the API bridge to crash on startup.
   • Fix: Always run the setup command (e.g., npm run setup) after cloning. Verify artifact existence before starting services.

6. Confusing Unshielded and Shielded Models

   • Explanation: Attempting to hide data in an unshielded contract leads to confusion, as the ledger will still expose the state.
   • Fix: Clearly document the privacy model. If data must be private, switch to a shielded contract design. Do not mix models within the same contract without explicit separation.

7. API Rate Limiting and Throttling

   • Explanation: Rapid UI interactions can flood the API bridge, causing transaction nonce conflicts or node overload.
   • Fix: Implement debouncing on input fields. Add queue management in the API bridge to serialize transaction submissions per address.

Production Bundle

Action Checklist

• Environment Verification: Confirm Node.js 20+ and Midnight Lace Wallet are installed. Run npm run doctor to validate tooling.
• Artifact Generation: Compile the Compact contract and verify artifacts exist in the managed/ directory.
• BigInt Enforcement: Audit all frontend code to ensure BigInt is used for numeric values. Remove Number conversions.
• Error Boundaries: Wrap React components in error boundaries to handle wallet rejections and API failures gracefully.
• Multi-Account Testing: Test transfer flows using multiple Lace Wallet accounts to verify state updates across different addresses.
• API Security: Restrict API endpoints to authorized origins. Validate all inputs against Compact schemas before processing.
• State Sync Strategy: Implement a reliable method for refreshing balances after transactions, such as polling or event listeners.

Decision Matrix

Configuration Template

Use this template to standardize project scripts and dependencies.

{
  "name": "midnight-transparent-asset",
  "version": "1.0.0",
  "scripts": {
    "setup": "npm install && npm run compile:contract",
    "compile:contract": "compact compile contracts/TransparentAsset.compact contracts/managed/transparent-asset",
    "dev:api": "node scripts/ledger-proxy.mjs",
    "dev:ui": "vite",
    "dev": "concurrently \"npm run dev:api\" \"npm run dev:ui\"",
    "doctor": "node scripts/doctor.mjs",
    "check:artifacts": "node scripts/check-artifacts.mjs"
  },
  "dependencies": {
    "@midnight-ir/compact-runtime": "^latest",
    "express": "^4.18.2",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "concurrently": "^8.2.0",
    "typescript": "^5.0.0",
    "vite": "^5.0.0"
  }
}

Quick Start Guide

1. Initialize Project: Clone the repository and run npm run setup to install dependencies and compile the contract.
2. Validate Environment: Execute npm run doctor to ensure all tools are configured correctly.
3. Start Services: Run npm run dev to launch the API bridge and React frontend concurrently.
4. Connect Wallet: Open the UI in a browser, click "Connect Lace Wallet," and authorize the connection.
5. Test Flow: Enter an amount and click "Issue Tokens." Verify the balance updates and the transaction appears in the Lace Wallet history.