Catallax Skill

Interact with Catallax — a decentralized contract work protocol on Nostr using Lightning/Cashu payments and trusted escrow arbiters.

Protocol Overview

Read references/NIP-3400.md for the full spec. Key concepts:

• - Patron: Creates tasks, funds escrow, assigns workers
• Arbiter: Escrow agent who judges work and handles payment
• Free Agent: Applies for tasks, delivers work, gets paid
• Kinds: 33400 (arbiter service), 33401 (task proposal), 3402 (task conclusion)
• Status flow: proposed → funded → in_progress → submitted → concluded

Querying Tasks

Use nak to query kind 33401 events from relays:

CODEBLOCK0

Parse the content field as JSON to get title, description, requirements. Parse tags for amount, status, categories.

Display Format

When presenting tasks to the user, show:

• - Title (from content.title)
• Bounty (from amount tag, in sats — show "?" if missing)
• Status (from status tag)
• Date (from created_at)
• Categories (from t tags)
• Description (from content.description, truncated)
• Funding type (from funding_type tag: "patron" or "crowdfunding")

Querying Arbiters

CODEBLOCK1

Parse content for name, about, policy. Parse tags for feetype, feeamount, min/max amounts, categories.

Display Format

When presenting arbiters:

• - Name (from content.name)
• Fee (feetype + feeamount — e.g. "5%" or "1000 sats flat")
• Min/Max (from minamount/maxamount tags)
• Categories (from t tags)
• About (from content.about)

Creating a Task Proposal

To create a task as a Patron, publish a kind 33401 event:

CODEBLOCK2

Generate the d-tag slug from the title (lowercase, hyphenated, with random suffix for uniqueness).

Important: The content field must be valid JSON with title, description, and optionally requirements and deadline.

Updating Task Status

Since kind 33401 is addressable replaceable, publish a new event with the same d-tag to update. Include all original tags plus changes:

CODEBLOCK3

Submitting Work (as Free Agent)

Work delivery is coordinated out-of-band per the protocol. However, agents may use kind 951 (work delivery) as a convention:

CODEBLOCK4

Task Conclusion (Arbiter only)

CODEBLOCK5

Common Queries

Reference Client

For visual browsing: https://catallax-reference-client.netlify.app/catallax

Key Relays

Query multiple relays for best coverage:

• - wss://relay.damus.io
• wss://nos.lol
• wss://relay.primal.net

Note: Some relays may not return results for nak req -k 33401 due to kind filtering. If nak returns empty results, fall back to a WebSocket script approach — open a WebSocket connection, send a REQ with {"kinds":[33401],"limit":50}, and collect EVENT responses until EOSE.

Edge Cases

• - Missing amount tag: Some tasks use crowdfunding (funding_type=crowdfunding) with a NIP-75 goal tag instead of a fixed amount. Display bounty as "crowdfunded" in this case.
• Content format: Content should be JSON but some early tasks used plain text. Try JSON.parse first, fall back to treating content as description.
• Stale tasks: Tasks with status=proposed older than 30 days may be abandoned. Note age when displaying.
• Multiple relays: Always publish to 3+ relays for discoverability. Query from multiple relays and deduplicate by event id.