sigil-signing

Sigil MPC Signing

Sign blockchain transactions securely using 2-of-2 threshold ECDSA with physical key splitting via floppy disks.

Quick Start

1. Check Daemon Status

# Verify daemon is running
pgrep -x sigil-daemon || echo "Daemon not running"

# Check socket exists
ls -la /tmp/sigil.sock

2. Check Disk Status

Before any signing operation, verify the signing disk is inserted and valid:

# Using the CLI
sigil-cli check-disk

# Or via IPC directly
echo '{"type":"GetDiskStatus"}' | nc -U /tmp/sigil.sock

Expected output when disk is ready:

Disk detected (sigil_7a3f)
├─ Presigs: 847/1000 remaining
└─ Expires: 12 days

3. Sign a Transaction

# Sign a transaction hash
sigil-cli sign \
  --hash "0x1234567890abcdef..." \
  --chain-id 1 \
  --description "Transfer 0.1 ETH to vitalik.eth"

Core Workflow

When a user requests a blockchain transaction:

1. Prepare transaction - Build the unsigned transaction with proper nonce, gas, etc.
2. Check disk - Verify signing disk is inserted and has remaining presigs
3. Request insertion - If no disk, prompt user to insert their Sigil floppy
4. Sign - Execute signing via the daemon (uses one presignature)
5. Broadcast - Submit signed transaction to the network
6. Log - Update the disk's usage log with transaction hash

IPC Protocol

The daemon listens on /tmp/sigil.sock using JSON-line protocol.

Request: Check Disk Status

{"type":"GetDiskStatus"}

Response:

{
  "type": "DiskStatus",
  "detected": true,
  "child_id": "7a3f",
  "presigs_remaining": 847,
  "presigs_total": 1000,
  "days_until_expiry": 12,
  "is_valid": true
}

Request: Sign Transaction

{
  "type": "Sign",
  "message_hash": "0x1234...abcd",
  "chain_id": 1,
  "description": "Transfer 0.1 ETH"
}

Response:

{
  "type": "SignResult",
  "signature": "abc123...",
  "presig_index": 153,
  "proof_hash": "def456..."
}

Request: Update TX Hash

After broadcasting, record the actual transaction hash:

{
  "type": "UpdateTxHash",
  "presig_index": 153,
  "tx_hash": "0x8f2a..."
}

Error Handling

Security Properties

• Physical consent: Every signature requires disk insertion
• Bounded exposure: Stolen disk = max N signatures (typically 1000)
• Audit trail: All operations logged to disk with zkVM proofs
• Chain isolation: Chain ID prevents cross-chain replay

User Interaction Patterns

Transaction Confirmation

Always show transaction details before signing:

Transaction Summary:
├─ To: vitalik.eth (0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045)
├─ Amount: 0.1 ETH (~$370)
├─ Gas: ~21000 (0.0005 ETH / $1.85)
└─ Chain: Ethereum Mainnet

Please insert your signing disk to continue.

Disk Status Display

✓ Disk detected (sigil_7a3f)
├─ Presigs: 847/1000 remaining
└─ Expires: 12 days

✓ Signing... ✓ Proving... ✓ Broadcasting...
✓ Confirmed: 0x8f2a...

Logged to disk. You may remove it now.

Low Presig Warning

When presigs drop below 100:

⚠️ Warning: Only 87 presignatures remaining.
Consider generating a new disk from your mother device soon.

Reference Documentation

• REFERENCE.md - Complete API reference and data structures
• DAEMON-SETUP.md - Daemon installation and configuration

Supported Chains

Example: Complete Transaction Flow

# Pseudocode for agent transaction handling

async def handle_transfer_request(to_address, amount_eth, chain_id):
    # 1. Check disk status
    disk = await check_disk_status()

    if not disk.detected:
        return prompt_user("Please insert your signing disk.")

    if disk.presigs_remaining < 1:
        return error("No presignatures remaining. Generate new disk.")

    # 2. Build transaction
    tx = build_transaction(to_address, amount_eth, chain_id)

    # 3. Show confirmation
    show_transaction_summary(tx)

    # 4. Sign via daemon
    result = await sign_transaction(tx.hash, chain_id, tx.description)

    # 5. Broadcast
    tx_hash = await broadcast_transaction(tx, result.signature)

    # 6. Update log
    await update_tx_hash(result.presig_index, tx_hash)

    return success(f"Transaction confirmed: {tx_hash}")