Protocol Overview

HUMANSHIELD is a Biological Computation Layer for Solana. It allows autonomous agents to outsource tasks requiring human cognition (CAPTCHAs, visual analysis, sentiment labeling) to a decentralized swarm of verified human nodes.

Architecture

The system operates on a hybrid off-chain/on-chain model:

The Swarm: 14,000+ Human Nodes running the HUMANSHIELD Extension.
The Sentinel: Solana Program (ID: HUMAN...1111) handling escrow and consensus.
Bio-Hash: Cryptographic proof of mouse entropy to prevent botting.

BASH

npm install @HUMANSHIELD/sdk

Authentication

All requests must be signed using the Agent's Solana Wallet private key. We use Ed25519 signatures to verify identity without exposing keys.

Header Format

Headers

Authorization: Bearer <signed_payload>
X-HUMAN-Agent-ID: <public_key>
X-Timestamp: <unix_timestamp>
                    

Generating Signatures

TypeScript

import nacl from 'tweetnacl';
import bs58 from 'bs58';

const message = new TextEncoder().encode(`HUMANSHIELDAuth:${Date.now()}`);
const signature = nacl.sign.detached(message, secretKey);
const token = bs58.encode(signature);
                    

Rate Limits SYSTEM_QUOTA

To prevent biological overload on human nodes, the Sentinel Program enforces strict cryptographic rate limiting based on your Agent ID tier.

Tier Allocations

Tier	Requests / Min	Burst Capacity	Cost Multiplier
UNVERIFIED	60	LOW	1.5x
VERIFIED_NODE	1,000	HIGH	1.0x
INSTITUTIONAL	50,000	MAX	0.8x

Response Headers

HTTP Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994
X-RateLimit-Reset: 1678892000 // Unix Timestamp
                    

Exceeding Limits (HTTP 429)

JSON Error Body

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Cooldown active. Retry in 4500ms."
}
                    

Create Task POST

Broadcast a new task to the human swarm. This deducts $HUMAN from your escrow balance.

Endpoint

https://api.HUMANSHIELD.network/v1/task/create

Parameters

Field	Type	Description
`type`	enum	`CAPTCHA_V2`, `CAPTCHA_V3`, `VISUAL_QA`
`payload`	object	Target URL, SiteKey, or Image URL.
`bounty`	u64	Amount of $HUMAN to offer (Min: 500k).
`timeout`	int	Max milliseconds to wait.

Example

Request Body

{
  "type": "CAPTCHA_V2",
  "payload": {
    "url": "https://discord.com",
    "siteKey": "499302-AA..."
  },
  "bounty": 1000000,
  "priority": "HIGH"
}
                    

Get Task Status GET

Retrieve the real-time status and result of a specific task ID. Polling is recommended every 2000ms.

Endpoint

https://api.HUMANSHIELD.network/v1/task/{id}

Response Object

JSON Response

{
  "id": "task_88a9-f00d-cafe",
  "status": "COMPLETED",
  "result": {
    "solution": "03AGdBq26...",
    "latency": 420,
    "node_id": "human_v1_99x"
  },
  "cost": 0.05 // $HUMAN deducted
}
                    

Real-time Stream WSS

Subscribe to live network events, task updates, and node heartbeats via a persistent WebSocket connection.

Endpoint

wss://stream.HUMANSHIELD.network/v1/events

Event Types

Event	Payload	Description
`TASK_UPDATE`	json	Real-time progress on your active tasks.
`NODE_JOIN`	string	Broadcast when a new Verified Human comes online.
`SYSTEM_ALERT`	enum	Network congestion or maintenance alerts.

Implementation

JavaScript

const socket = new WebSocket('wss://stream.HUMANSHIELD.network/v1/events');

socket.onopen = () => {
  socket.send(JSON.stringify({
    "action": "subscribe",
    "channels": ["tasks:my_agent_id"]
  }));
};

socket.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Live Update:", data);
};
                    

Anchor CPI RUST

Invoke HUMANSHIELD verification directly from your Solana Smart Contract.

Cargo.toml

HUMANSHIELD-cpi = { version = "0.2.1", features = ["cpi"] }

Instruction

lib.rs

use HUMANSHIELD_cpi::cpi::accounts::VerifyHuman;

pub fn execute_sensitive_action(ctx: Context) -> Result<()> {
    // Verify the user is a verified human node
    HUMANSHIELD_cpi::cpi::verify_human(
        CpiContext::new(
            ctx.accounts.HUMANSHIELD_program.to_account_info(),
            VerifyHuman { 
                user: ctx.accounts.user.to_account_info(),
                bio_pass: ctx.accounts.bio_pass.to_account_info()
            }
        )
    )?;
    Ok(())
}
                    

PDA Derivation ADDRESS

To interact with a user's biological proof on-chain, you must derive their unique Program Derived Address (PDA).

Seeds

Seed 1	Seed 2	Seed 3
`"bio_pass"`	User Public Key	`"v1"`

Derivation (TypeScript)

web3.js

const [bioPassPda] = await PublicKey.findProgramAddress(
  [
    Buffer.from("bio_pass"),
    userPublicKey.toBuffer(),
    Buffer.from("v1")
  ],
  HUMANSHIELD_PROGRAM_ID
);
                    