Skip to content

README.md

Latest commit

 

History

History
99 lines (79 loc) · 4.51 KB

README.md

File metadata and controls

99 lines (79 loc) · 4.51 KB

PFT Test Client

Programmatic client for the Post Fiat Task Node. Enables automated task discovery, acceptance, evidence submission, verification handling, and reward collection.

Quick Start (TypeScript)

cd ts && npm install && npm run build

# Set credentials
export PFT_TASKNODE_JWT="<your-jwt>"
export PFT_WALLET_MNEMONIC="<24-word-phrase>"

# Run a complete E2E task loop (5-6 minutes)
npx pft-cli loop:test --type personal

This single command executes the full task lifecycle: request → accept → evidence → verification → reward.

Repository Structure

pft-test-client/
├── ts/                      # TypeScript CLI (recommended)
│   ├── src/
│   │   ├── cli.ts           # CLI entry point
│   │   ├── tasknode_api.ts  # Task Node API client
│   │   ├── loop.ts          # TaskLoopRunner orchestrator
│   │   ├── signer.ts        # XRPL transaction signing
│   │   ├── pointer.ts       # Memo encoding (protobuf-style)
│   │   └── ...
│   └── README.md            # Full TypeScript documentation
│
├── sdk/                     # Python SDK (legacy)
│   ├── client.py            # Core client
│   ├── pointer.py           # Memo encoding
│   └── README.md            # Python documentation
│
├── proto/                   # Protocol definitions
│   └── pft_tasknode.proto   # Protobuf schema reference
│
└── docs/
    └── TASK_LOOP_PROTOCOL.md  # Complete E2E protocol documentation

Implementations

Language Location Status Features
TypeScript ts/ ✅ Active Full CLI, E2E loop, API client
Python sdk/ 🔶 Legacy Core signing, pointer encoding

Key Features

  • Complete Task Loop: Request tasks, submit evidence, handle verification, collect rewards
  • Transaction Signing: Built-in XRPL signing via seed or mnemonic
  • IPFS Pinning: Automatic evidence upload to web3.storage
  • Pointer Encoding: Protobuf-style memo encoding for on-chain submissions
  • Polling Utilities: Smart polling for async state transitions
  • Pending Recovery: Resume failed submissions from local storage

Documentation

Task Loop Overview

┌─────────────────────────────────────────────────────────────────┐
│                     TASK LOOP LIFECYCLE                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. REQUEST    "request a personal task: Build X"               │
│       ↓        → Magic phrase triggers task generation          │
│                                                                 │
│  2. ACCEPT     POST /api/tasks/{id}/accept                      │
│       ↓        → Status: pending → in_progress                  │
│                                                                 │
│  3. EVIDENCE   Upload → IPFS pin → XRPL tx → Submit             │
│       ↓        → Evidence linked on-chain                       │
│                                                                 │
│  4. VERIFY     Poll for question → Respond → XRPL tx → Submit   │
│       ↓        → AI evaluates evidence + response               │
│                                                                 │
│  5. REWARD     Poll until rewarded/refused                      │
│                → PFT tokens transferred on-chain                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

For AI Agents

See CLAUDE.md for AI-specific documentation and quick setup instructions.

License

MIT License - see LICENSE