Laminar Field Manual

The complete operational guide for treasurers processing batch disbursements using Laminar. This manual covers the core workflow, data formats, validation rules, and troubleshooting procedures.

Overview

Key Properties

Core Concepts

Understanding the architecture and philosophy behind Laminar's design.

The Spreadsheet Gap

Brain vs. Muscle

Payment Intents

Laminar constructs Payment Intents, not transactions. A Payment Intent contains all information needed to create a transaction (recipients, amounts, memos) but has no signing authority. The mobile wallet receives the intent and executes it using locally-stored keys.

Critical Invariants

Architectural constraints that are enforced at all times. Violation of any invariant is a critical defect.

• INV-01 Laminar NEVER stores, generates, or requests spending keys or seed phrases.
• INV-02 Laminar NEVER signs transactions. It constructs Payment Intents only.
• INV-03 Laminar NEVER broadcasts transactions. The mobile wallet handles network communication.
• INV-04 ALL monetary arithmetic uses integer zatoshis (bigint). Floating-point is PROHIBITED.
• INV-05 All cross-boundary data MUST be validated against versioned schemas.
• INV-06 Sensitive IndexedDB fields (memos, labels) MUST be encrypted with session key.
• INV-07 Memo encoding: UTF-8 bytes to standard base64. Maximum 512 bytes.
• INV-08 Handoff results MUST conform to HandoffResult schema.
• INV-09 No telemetry. No analytics. No external network requests.
• INV-10 If ANY row fails validation, the ENTIRE batch is rejected. No partial processing.

Workflow

The standard batch disbursement workflow consists of seven steps, from CSV preparation to receipt generation.

1. Prepare CSV

   Create a CSV file with recipient addresses, amounts, and optional memos. Use UTF-8 encoding. See CSV Format for schema details.

2. Import Batch

   Drag the CSV file into Laminar Terminal or use the file picker. Select the network (Mainnet or Testnet) before import.

3. Review & Validate

   Laminar validates every row: address format, network match, amount bounds, memo length. Review the batch summary showing total ZEC and recipient count. If any row fails, the entire batch is rejected.

4. Generate QR

   Click "Proceed" to construct ZIP-321 payment requests. Laminar generates static QR (small batches) or animated UR sequence (large batches) automatically.

5. Scan with Wallet

   Open Zashi or YWallet on your mobile device. Use the scan function to capture the QR code. For animated sequences, hold steady until all frames are captured.

6. Sign & Broadcast

   Review the transaction details on your mobile wallet. Confirm to sign with your locally-stored keys. The wallet broadcasts to the Zcash network.

7. Save Receipt

   Return to Laminar and click "Generate Receipt". Save the JSON receipt bundle for your records. This provides an audit trail of the constructed batch.

CSV Format

Laminar accepts CSV files with flexible column naming. The first row must contain headers. Files must use UTF-8 encoding.

Column Specification

*Either amount OR amount_zatoshis is required. If both are present, amount_zatoshis takes precedence.

Example CSV

address,amount,memo,label
u1abc123...,10.5,"January payment",Alice
u1def456...,25.0,"January payment",Bob
u1ghi789...,15.75,,Carol

Encoding Requirements

• File encoding: UTF-8 (with or without BOM)
• Line endings: LF or CRLF
• Delimiter: Comma (,)
• Quote character: Double quote (")
• Escape: Doubled double quotes ("")

JSON Format

For programmatic batch generation, Laminar accepts JSON files conforming to the Laminar Batch Schema.

{
  "version": "1.0",
  "network": "mainnet",
  "recipients": [
    {
      "address": "u1...",
      "amount_zatoshis": 100000000,
      "memo": "January payment",
      "label": "Alice"
    }
  ]
}

{
  "laminar_version": "1.0.0",
  "timestamp": "2025-01-28T12:00:00Z",
  "batch_id": "a1b2c3d4",
  "network": "mainnet",
  "total_zatoshis": 5000000000,
  "total_zec": "50.0",
  "recipient_count": 25,
  "zip321_payload_hash": "sha256:...",
  "segments": 1
}

Validation Rules

All data is validated before batch construction. If any row fails, the entire batch is rejected.

QR Generation

Laminar automatically selects between static QR and animated UR sequences based on payload size.

ZIP-321 URI Format

zcash:<address>?amount=<zec>&memo=<base64>
    &address.1=<addr>&amount.1=<zec>&memo.1=<base64>

UR Animation Parameters

Payload Limits

Understanding size constraints for each handoff mode.

Size Limits by Mode

Recipient Capacity

Wallet Compatibility

Tested wallet versions and supported features. Results tracked by version.

Error Codes

All errors use standardized codes. No string literals in error handling.

Constants Reference

Critical constants used throughout the system. Reference implementations must use exact values.

ZATOSHI_PER_ZEC = 100,000,000
ZATOSHI_MIN     = 1
ZATOSHI_MAX     = 2.1e15
DUST_THRESHOLD  = 10,000

QR_STATIC    = 2510
QR_ANIMATED  = 29000
DEEPLINK     = 7200

MEMO_MAX       = 512
MAX_RECIPIENTS = 500
UR_FRAGMENT    = 150
UR_FRAME_MS    = 100

Glossary

Key terms and definitions used throughout Laminar documentation.