# 3.1 Readable Transactions
Transaction information must be understandable to users with cognitive disabilities.
## Success Criteria
### 3.1.1 Plain Language Descriptions (Level A)
**Requirement**: Plain language descriptions must accompany all technical transaction data. Function names, hex data, and contract calls must have human-readable explanations.
**Intent**: Most users can't interpret `transferFrom(address,address,uint256)`. Plain language makes transactions understandable.
**Benefits**:
- **Cognitive disabilities**: Can understand what they're approving
- **New users**: Don't need technical knowledge
- **All users**: Faster, confident decisions
**Techniques**:
```tsx
<TransactionDescription>
{/* Technical data */}
<details>
<summary>Technical details</summary>
<code>
Function: transferFrom(address,address,uint256)
From: 0x742d...595f
To: 0x1234...abcd
Amount: 1000000000000000000
</code>
</details>
{/* Plain language (primary display) */}
<div className="plain-description">
<p>
<strong>What this transaction does:</strong>
Transfer 1.0 ETH from your wallet to the Uniswap router
contract for swapping.
</p>
</div>
</TransactionDescription>
// For approvals
<ApprovalDescription>
<p>
<strong>You're granting permission for:</strong>
The Uniswap app to transfer up to 1,000 USDC from your wallet.
</p>
<p>
This permission is needed so Uniswap can complete your swap.
The app can only move tokens when you confirm a swap.
</p>
</ApprovalDescription>
```
**Failures**:
- Only showing function signatures
- No explanation of transaction effects
- Technical jargon without definitions
---
### 3.1.2 Accessible Jargon Definitions (Level AA)
**Requirement**: Technical terms (slippage, gas, nonce, MEV, impermanent loss) must have accessible definitions available on demand.
**Intent**: DeFi has specialized vocabulary. Definitions enable understanding without prior knowledge.
**Benefits**:
- **Cognitive disabilities**: Learn terms in context
- **New users**: Self-service education
- **Non-native speakers**: Clearer understanding
**Techniques**:
```tsx
// Inline definition with tooltip
<Term
term="slippage"
definition="The difference between the expected price and the actual price when your trade executes. Higher slippage means you might receive less tokens than expected."
>
Slippage tolerance
</Term>
// Implementation
function Term({ term, definition, children }) {
const [showDef, setShowDef] = useState(false);
return (
<span className="term-wrapper">
<button
className="term"
aria-expanded={showDef}
aria-describedby={`def-${term}`}
onClick={() => setShowDef(!showDef)}
onKeyDown={(e) => e.key === 'Escape' && setShowDef(false)}
>
{children}
<span className="sr-only">(click for definition)</span>
</button>
{showDef && (
<span
id={`def-${term}`}
role="tooltip"
className="definition"
>
{definition}
</span>
)}
</span>
);
}
// Glossary page
<Glossary>
<h1>DeFi Terms Glossary</h1>
<dl>
<dt id="term-gas">Gas</dt>
<dd>
A fee paid to process your transaction on the blockchain.
Think of it like a shipping fee for sending data.
</dd>
<dt id="term-slippage">Slippage</dt>
<dd>
The difference between the expected price and actual price
when your trade executes.
</dd>
{/* ... more terms */}
</dl>
</Glossary>
```
**Failures**:
- Terms used without explanation
- Definitions only in separate glossary
- Technical definitions that use more jargon
---
### 3.1.3 Concrete Outcome Statements (Level AA)
**Requirement**: Transaction outcomes must be stated in concrete terms: what the user will send, receive, and pay—not abstract descriptions.
**Intent**: "Swap tokens" is vague. "You send 1 ETH, you receive ~2,000 USDC" is concrete and verifiable.
**Benefits**:
- **Cognitive disabilities**: Clear expectations
- **All users**: Verifiable outcomes
- **Risk reduction**: Catch errors before signing
**Techniques**:
```tsx
<TransactionOutcome>
<h3>What will happen:</h3>
<ul className="outcome-list">
<li className="outcome-send">
<span className="label">You send:</span>
<span className="value">1.0 ETH ($1,950)</span>
</li>
<li className="outcome-receive">
<span className="label">You receive:</span>
<span className="value">~1,948 USDC</span>
</li>
<li className="outcome-fee">
<span className="label">Network fee:</span>
<span className="value">~$4.50 (paid in ETH)</span>
</li>
</ul>
<p className="outcome-summary">
After this transaction, your ETH balance will decrease by
approximately 1.002 ETH, and you will have ~1,948 more USDC.
</p>
</TransactionOutcome>
// For DeFi positions
<PositionOutcome>
<h3>After depositing:</h3>
<ul>
<li>Your 1,000 USDC will be deposited into Aave</li>
<li>You will receive 1,000 aUSDC (representing your deposit)</li>
<li>You will earn approximately 3.2% APY</li>
<li>You can withdraw at any time</li>
</ul>
</PositionOutcome>
```
**Failures**:
- Vague descriptions ("Interact with contract")
- Missing fee information
- No before/after balance preview
---
### 3.1.4 Adjustable Complexity Levels (Level AAA)
**Requirement**: Users can adjust the complexity level of transaction information (simple, standard, advanced) based on their preferences.
**Intent**: Some users want minimal info, others want full technical details. Both should be served.
**Benefits**:
- **Cognitive disabilities**: Simpler view reduces overwhelm
- **Experts**: Full technical access
- **All users**: Personalized experience
**Techniques**:
```tsx
<ComplexitySelector>
<fieldset>
<legend className="sr-only">Transaction detail level</legend>
<label>
<input
type="radio"
name="complexity"
value="simple"
checked={complexity === 'simple'}
onChange={() => setComplexity('simple')}
/>
Simple (what you send and receive)
</label>
<label>
<input
type="radio"
name="complexity"
value="standard"
checked={complexity === 'standard'}
onChange={() => setComplexity('standard')}
/>
Standard (includes fees and details)
</label>
<label>
<input
type="radio"
name="complexity"
value="advanced"
checked={complexity === 'advanced'}
onChange={() => setComplexity('advanced')}
/>
Advanced (full technical data)
</label>
</fieldset>
</ComplexitySelector>
{/* Render based on complexity */}
{complexity === 'simple' && (
<SimpleView>
<p>Swap 1 ETH → ~2,000 USDC</p>
</SimpleView>
)}
{complexity === 'standard' && (
<StandardView>
{/* Include fees, slippage, etc. */}
</StandardView>
)}
{complexity === 'advanced' && (
<AdvancedView>
{/* Include raw calldata, gas limits, etc. */}
</AdvancedView>
)}
```
**Failures**:
- One-size-fits-all complexity
- Advanced-only view
- Preference doesn't persist
---
## Testing Checklist
- [ ] All transactions have plain language descriptions
- [ ] Technical data is secondary/expandable
- [ ] Jargon terms have accessible definitions
- [ ] Outcomes state concrete amounts
- [ ] Fees clearly stated
- [ ] Complexity settings available
- [ ] Settings persist across sessions
## Related Components
- [TransactionDescription.tsx](../../components/TransactionDescription.tsx)
- [Term.tsx](../../components/Term.tsx)
- [Glossary.tsx](../../components/Glossary.tsx)
