Documentation missing

[alexanderkjeldaas]

I think you need documentation that shows the various states tokens can be in, and how to move into and out of a given state.

For example, pending tokens, missing external poi, private balance, etc.

1. What do the states mean?
2. How do you get tokens into the state?
3. How do you get tokens out of the state?

[alexanderkjeldaas]

AI analysis of the code below:

Railgun POI Balance Bucket State Diagram

stateDiagram-v2
    direction LR
    
    [*] --> ShieldPending: New Shield Transaction\n(isShieldCommitmentType && (!pois || !hasAllKeys))
    
    ShieldPending --> MissingExternalPOI: After time delay\n(1hr mainnet/1min testnet)\nWITHOUT valid POIs
    
    ShieldPending --> Spendable: Receives valid POIs\nfrom network\n(all active lists = Valid)
    
    ShieldPending --> ShieldBlocked: POI validation returns\nShieldBlocked status
    
    [*] --> MissingInternalPOI: Change/DeFi output\n(!pois || !hasAllKeys && isChange)
    [*] --> MissingExternalPOI: External output\n(!pois || !hasAllKeys && !isChange)
    
    MissingInternalPOI --> ProofSubmitted: User - Generate POI\nOR Network - Proof submitted
    MissingExternalPOI --> ProofSubmitted: User - Generate POI\nOR Network - Proof submitted
    
    ProofSubmitted --> Spendable: Network validates proof\n(all active lists = Valid)
    
    [*] --> Spendable: Has valid POIs for all active lists
    
    ShieldBlocked --> [*]: Permanent state\n(cannot transition)
    
    [*] --> Spent: TXO spent\n(txo.spendtxid !== false)
    
    %% User Actions
    note right of MissingExternalPOI
        USER ACTIONS:
        • Refresh Received POI
        • Generate Wallet POI
        • Fix Broadcasters
    end note
    
    note right of ProofSubmitted
        WAITING FOR:
        • Network validation
        • Broadcaster confirmation
        • POI node consensus
    end note
    
    note right of ShieldPending
        TIME DELAY:
        • Mainnet: 1 hour
        • Testnet: 1 minute
        BUT requires POIs to become Spendable
    end note

Loading

State Definitions

ShieldPending

• Trigger: New shield transaction (isShieldCommitmentType)
• Condition: No POIs or missing POI lists for active lists
• Time Delay: 1 hour (mainnet) / 1 minute (testnet)
• Transition: Requires POI validation to become Spendable

MissingExternalPOI

• Trigger: External transaction output (non-change)
• Condition: No POIs or missing POI lists for active lists
• User Action: Use "Refresh Received POI" in POI Tools
• Common Case: Received shielded tokens from another wallet

MissingInternalPOI

• Trigger: Change output or DeFi interaction (swap receipt)
• Condition: No POIs or missing POI lists for active lists
• User Action: Use "Generate Wallet POI" in POI Tools

ProofSubmitted

• Trigger: POI proof submitted to network
• Condition: Any active list has ProofSubmitted status
• Waiting For: Network validation via POI aggregator
• Transition: → Spendable when all lists have Valid status

Spendable

• Trigger: All active lists have Valid POI status
• Condition: POI.hasValidPOIsActiveLists(pois) = true
• Result: Funds can be spent/unshielded

ShieldBlocked

• Trigger: Shield blocked by at least one active list
• Condition: Any POI status is ShieldBlocked
• Result: Permanent state, cannot transition

Spent

• Trigger: TXO has been spent (unshielded)
• Condition: txo.spendtxid !== false
• Result: Transaction output is consumed

POI Tools Menu Guidance

When to use each tool:

1. Generate Wallet POI

   • Comprehensive POI refresh for all transactions
   • Use for: MissingInternalPOI, general POI issues
   • Calls: refreshPOIsForAllTXIDVersions()

2. Refresh Received POI

   • Specifically for received shielded tokens
   • Use for: MissingExternalPOI (your current state)
   • Calls: refreshReceivePOIsAllTXOs()

3. Refresh Spent POI

   • For spent transactions needing POI validation
   • Use for: Unshield proof issues
   • Calls: refreshSpentPOIsAllSentCommitmentsAndUnshieldEvents()

Common User Scenarios

Scenario 1: Received shielded tokens stuck in MissingExternalPOI

• Current State: MissingExternalPOI
• Root Cause: Received tokens without POI validation
• Action: Fix Broadcasters → Refresh Received POI
• Expected Path: MissingExternalPOI → ProofSubmitted → Spendable

Scenario 2: Shield transaction not becoming spendable

• Current State: ShieldPending
• Root Cause: Waiting for POI validation (not just time)
• Action: Ensure broadcasters connected, wait for network validation
• Note: ShieldPending doesn't auto-expire to Spendable

Scenario 3: Change outputs stuck in MissingInternalPOI

• Current State: MissingInternalPOI
• Root Cause: Internal transactions need POI generation
• Action: Generate Wallet POI
• Expected Path: MissingInternalPOI → ProofSubmitted → Spendable

Broadcaster Connectivity

Critical Dependency: All POI transitions require working broadcasters

• Purpose: Submit POI proofs to network, receive validations
• Status: "Broadcasters: Disconnected" blocks all POI operations
• Fix: Reset broadcaster connection, check network connectivity

Code References

1. State Determination: node_modules/@railgun-community/engine/dist/poi/poi.js:29 (getBalanceBucket)
2. Time Constants: node_modules/@railgun-community/shared-models/dist/models/proof-of-innocence.js
3. POI Tools: src/ui/main-ui.ts:154-214 (runPOIToolsPrompt)
4. Balance Buckets: node_modules/@railgun-community/shared-models/dist/models/balance.d.ts

Troubleshooting Checklist

1. Check Broadcaster Status: "Broadcasters: Available" required
2. Identify Current State: Which balance bucket are tokens in?
3. Choose Correct Tool: Based on state (see guidance above)
4. Monitor Transitions: Wait for network validation
5. Verify Result: Tokens should move to Spendable bucket

Key Insights

1. ShieldPending ≠ Time-based: Requires POI validation, not just time
2. MissingExternalPOI ≠ MissingInternalPOI: Different causes, different fixes
3. Broadcasters Essential: No POI operations work without them
4. Network Validation Required: Local generation ≠ network validation
5. Multiple POI Lists: Need valid POIs for ALL active lists%

[621625]

Looks like overkill to use an AI to reply. Just write a few lines manually please.