NTH DAO
AlexNthLab/nth-dao
Organização descentralizada nativa de IA para colaboração humano-agente
Ver no GitHubCamada de colaboração em equipe plugável para agentes de IA, permitindo que humanos e agentes se organizem em estruturas descentralizadas ao redor de uma missão compartilhada. Fornece primitivos criptograficamente assinados (IntentMandate, CartMandate, PaymentMandate), roteamento seguro de ações, descoberta de capacidades via Agent Card, e auditoria completa de eventos.
Instalação
npx convez-ai AlexNthLab/nth-dao1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Coordenação de múltiplos agentes de IA em torno de objetivos compartilhados
- Governança descentralizada com votação de políticas entre membros
- Auditoria criptográfica de ações e decisões tomadas por agentes
- Descoberta dinâmica de capacidades entre agentes em uma rede
Veredito

NTH DAO é uma solução técnica robusta para orquestração multi-agente com garantias criptográficas, mas demanda expertise em Web3 e arquitetura descentralizada. Recomendado para equipes que precisam de auditoria completa e governança transparente em sistemas colaborativos.
README
A tradução para o português deste README ainda está na fila.
NTH DAO
AI-native Web3 DAO layer for humans and agents.
NTH DAO turns every shared mission into a living decentralized organization. Humans and AI agents can join around a common vision, contribute ideas and capabilities, coordinate through local-first groups, and build auditable trust over time.
The Python import path is nth_dao. The former public package name has been
removed so new forks and installs converge on one identity.
See MANIFESTO.md, VISION.md, IMPLEMENTATION_GUIDE.md, and CONTRIBUTING.md for the DAO mission, roadmap, technical direction, and merge criteria.
What's New in 0.10.0b1 - Beta release
This beta previews the v0.10 protocol surface for testers and early integrators:
- Signed
IntentMandate,CartMandate, andPaymentMandateprimitives, with Data Integrity style proof helpers. - Mandate conformance vectors and EventBus mandate lifecycle events.
- A2A JSON-RPC server and Agent Card helpers for task lookup and capability discovery.
- Hardened action routing with pubkey lookup, explicit dev mode, TTL/nonce replay protection, signed requests, and signed responses.
- EventBus correction events, event subscriptions, and audited fault isolation.
- Mandate sidebar in the TypeScript frontend, plus browser Ed25519 wallet support and Vitest coverage.
- Packaging fixes so
nth_dao.mandateand the requiredteam_layerruntime packages are included in distributions.
Validation for this beta: Python suite 1067 passed, 11 skipped;
frontend Vitest 2 passed; production frontend build passed.
What's New in 0.9.6 - Unique group names, governance votes, chat-native collaboration UI
Three Python additions for the protocol layer, plus four TS panels for the consumer chat app-inspired collaboration experience for agents and humans.
Protocol additions (Python):
GroupRegistrywith workspace-unique slugs - names normalize (Frontend Team!->frontend-team); two groups can't share a slug within a workspace. Records are signed by the founder.- Policy-vote governance -
PolicyChangeProposalsigned by a member; other members append signed yes/no/abstain votes; passes when50% of distinct member pubkeys vote yes.
apply_proposalrebuilds the GroupRecord re-signed by an admin. - 14 new web API endpoints in
nth_dao/web/: agent fuzzy search, LAN discovery proxy, add-by-DID, group CRUD + search, governance propose/vote. All write endpoints use "server prepares unsigned -> client signs locally -> client posts back" so private keys never cross the wire.
UI additions (TS, per the iron rule):
frontend/src/panels/ - drop into your React app:
ContactsPanel- search agents by name / capability; add by exact agent_id or did:key.NearbyPanel- UDP LAN "people nearby", with optional pre-shared key.GroupsPanel- list / search / create unique groups; color-coded policy badges.GovernancePanel- propose policy changes; vote yes/no/abstain.ContactShell- top tab bar that hosts all four.chat-panels.css- standalone styles, leaves existing styles untouched.
import { ContactShell } from "./panels";
function App() {
const { actorId, actorPubkeyHex, sign } = useWallet();
return (
<ContactShell
actorId={actorId}
actorPubkeyHex={actorPubkeyHex}
sign={sign}
/>
);
}
The host app supplies a sign(payload) helper from whatever wallet
infrastructure it has. Browse-only mode renders without signing.
What's New in 0.9.5 - DID:key, AgentLedger, Guardian recovery, A2A boundary
Five additive deliverables, zero breaking changes:
- W3C did:key alignment -
AgentIdentity.as_did()emits realdid:key:z...strings (base58btc + multicodec 0xed 0x01). Pure stdlib encode/decode.MissionTemplate.publisher_didis now a usable DID. AgentLedger- per-pubkey-fingerprint append-only event ledger undersidechain/agents/<fp>/. Records step claim/complete/failed, handoffs given/received, reviews given/received, endorsements. Deterministic reducer folds events into{missions_owned, steps_completed, success_rate, handoffs_*, templates_used, categories, total_token_cost}. Step one toward the Achievements / signed contribution credentials layer.- Guardian-based social recovery - N-of-M peers can collectively
sign a
KeyReplacementProofthat re-binds anagent_idto a fresh pubkey. Owner publishes a signedGuardianSet(pubkeys, threshold); losing the key no longer means losing the identity, provided you have trusted friends. - A2A boundary translation -
nth_dao/a2a/translate.pyconvertsMissionTemplate ↔ A2A Skill,Mission ↔ A2A Task, assembles an AgentCard for/.well-known/agent.json. Pure data transformations only; the HTTP/JSON-RPC server lives in the separatenth-dao-a2a-adapterpackage (v0.10.0+). - Conformance vectors expanded - 22 -> 31 vectors / 6 -> 11 categories. Channel messages, Invitations, TeamConfig, did:key, LAN psk_tag now have canonical-bytes coverage.
# DID
print(alice.as_did()) # -> "did:key:z6Mk..."
restored = nth.AgentIdentity.from_did("did:key:z6Mk...") # verify-only
# AgentLedger
al = nth.AgentLedger(workspace, identity=alice)
al.record_step_complete("m1", "s1", template_id="code-review",
category="code_review", token_cost=4000)
print(al.compute_stats()) # {"success_rate": 1.0, ...}
# Guardian recovery
gs = nth.publish_guardian_set(alice, [g1.pubkey, g2.pubkey, g3.pubkey], threshold=2)
proof = nth.begin_key_replacement(gs, new_alice.pubkey_hex, reason="laptop lost")
proof.signatures.append(nth.sign_replacement(g1, proof))
proof.signatures.append(nth.sign_replacement(g2, proof))
valid, reason = nth.verify_replacement(proof, gs) # -> (True, "ok")
# A2A boundary
from nth_dao.a2a import agent_card_from, a2a_task_from_mission
card = agent_card_from(agent_did=alice.as_did(), name="Alice",
templates=[t], endpoint_url="https://alice.example/a2a")
task = a2a_task_from_mission(mission) # ready to ship over JSON-RPC
What's New in 0.9.4 - Sustainability sprint
No new protocol surface. We filled the six holes that prevented NTH DAO from outliving its single maintainer:
SECURITY.md+ key recovery -nth_dao.export_recovery_kit(identity, password)andimport_recovery_kit(kit, password). libsodiumcrypto_secretbox+ Argon2id. Lose your identity, restore from a passphrase-encrypted blob.docs/MIGRATIONS.md+ migration test runner - forward-compat policy for 0.9.x, per-version delta, automated 0.9.0-fixture regression tests.nth-status+nth-metricsCLI - text/JSON workspace snapshot; Prometheus exposition-format/metricsHTTP endpoint. Pure stdlib.requirements/*.lock.txt- pinned transitive deps per extra (crypto,ux,web,dev). Reproducible builds.nth_dao/conformance/- 22 wire-protocol test vectors in 6 categories. A non-Python port is "wire-compatible" when it produces zero failures. Seedocs/CONFORMANCE.md.docs/research/A2A_ALIGNMENT.md- side-by-side vs Google's Agent2Agent protocol (Linux Foundation, 150+ orgs). Our protocol stays distinct; an A2A adapter is targeted for v0.10.0+.
# Status snapshot
nth-status --workspace ./my-team
# Prometheus metrics endpoint
nth-metrics --port 9090 --workspace ./my-team
# Backup an identity into a portable encrypted blob
python -c "import nth_dao as nth; \
from nth_dao.identity import AgentIdentity; \
ident = AgentIdentity.load('~/.nth/identity.json'); \
print(nth.export_recovery_kit(ident, 'correct horse battery staple').to_json())" \
> ~/secrets/alice.recovery.json
What's New in 0.9.3 - Mission Template registry
This release lifts MissionStore from a one-shot quest board into a
reusable, signed, rateable template registry - the "decentralized App
Store" layer in the project vision.
# Alice publishes a signed reusable template
template = nth.mint_template(
alice_identity,
template_id="code-review", version="1.0.0",
name="Code Review",
category="code_review", tags=["python", "security"],
required_capabilities=["code_review"],
inputs={"diff_url": nth.IOField(type="string", required=True,
description="PR diff URL")},
steps=[nth.StepSkeleton(id="review", description="...",
inputs_from={"diff_url": "input:diff_url"})],
suggested_reward=5.0,
)
store.publish_template(template)
# Bob browses and instantiates the latest version
results = store.browse_templates(sort_by="rating")
mission = store.instantiate("code-review",
owner="bob",
inputs={"diff_url": "https://..."})
# Carol reviews Bob's completed mission; stats roll up automatically
store.review_mission(mission.id, reviewer=carol_identity, score=4.5,
feedback="caught 3 edge cases")
# Personal contribution view, walks archived missions too
for m in store.my_history("bob"):
print(m.template_id, m.status)
Highlights:
MissionTemplate- semver-versioned, publisher-signed, F-Droid-style one-file-per-version layout. Tampering invalidates signature; deprecation is publisher-only.MissionReview- signed, append-onlyreviews/*.jsonlledger per template version. EWMA aggregation surfaces recent reviews while keeping historical record.template_lock- Nix-flake-lock-style snapshot ofpublisher_sigat instantiation time. A running mission stays reproducible even if the publisher republishes or deprecates.browse_templates- F-Droid-style discovery: filter bycategory,tags,min_average_rating; sort byrating/recent/popularity.archive_completed(older_than_days=30)- atomic move of terminal missions toarchive/YYYY-MM/, keeps the active query path fast.my_history(agent_id)- walks active + archive; first step toward the AgentLedger / Achievement layer (v0.9.4+).- 5 reserved fields (
owner_did,legal_jurisdiction,governing_arbiter,credentials_required, ...) ready for the Layer-3 social-collaboration story without on-disk format breaks. - Aligned with industry standards (no new runtime dependencies): the
schema and on-disk layout track cargo-crev (Proof model), F-Droid
(one-file + derived index), TUF (monotonic version +
metafield +delegationsplaceholder), Argo WorkflowTemplate (5-valuetemplate_type), GitHub Actions (inputs/outputsfield naming), Nixflake.lock(template_lock), and W3Cdid:key(publisher_did).
Full wire-format spec in docs/PROTOCOLS.md §9;
bootstrap taxonomy in docs/CATEGORIES.md.
What's New in 0.9.2 - Revocation, invitations, private LAN
- Endorsement revocation - owners can now revoke previously-issued
trust endorsements.
TrustGraph.revoke(endorser, endorsement, reason); load_all filters revoked entries; signed revocation records persist atteam_trust/revocations.jsonl. Pre-emptive revocations are rejected (the matching endorsement must exist) so they can't be used for DoS. - Invitation tokens (
nth_dao.Invitation) - one signed bundle that carriesteam_id+owner_pubkey+join_token+ optionalws_url- optional LAN
psk. Encode as a URL (nthdao+invite://...) or as a QR code (pip install nth-dao[ux]). New members scan/paste and attach without out-of-band setup.
- optional LAN
- Private LAN discovery -
LANDiscovery(..., psk="team-secret")adds an HMAC-SHA256 tag to every query and hello; peers without the shared PSK see only opaque traffic. Empty PSK keeps the public/open mode. docs/PROTOCOLS.md- a wire-format spec so other-language implementations (Rust / Go / TS) can interop with the Python reference.CONTRIBUTING.md- new "Hard Rules" section documenting the eight enforcement rules that prevent re-introducing the v0.9.1 bugs.
# Invite flow:
inv = nth.Invitation.mint(team_cfg, owner_identity, ws_url="ws://...", ttl_days=7)
print(inv.to_url()) # "nthdao+invite://AAAAB3Nz..." -> QR scan / paste
print(inv.to_qr_terminal()) # ASCII QR ready to print on a terminal
# Revoke flow:
tg.revoke(alice, alice_endorses_bob, reason="key rotated")
assert not tg.is_trusted("bob", bob_pubkey)
What's New in 0.9.1 - Hardened release
Independent code review surfaced six critical security/correctness bugs.
0.9.1 fixes all of them, plus 13 high-severity issues, and adds two new
discovery layers. See CHANGELOG.md for the full list.
Security (P0/P1/P3)
- Gossip signature verification fixed - messages are now verified
against the author's trusted pubkey (not the relay peer's), with a
10-min replay window and
require_signature=Trueas the safe default. - WebSocket challenge-response handshake - peers must prove they hold the private key for the pubkey they claim before being added.
- Atomic mission claim - cross-process file locks (
fcntlon POSIX,msvcrton Windows) + compare-and-swap; a 6-process race test proves exactly-once semantics (tests/test_concurrent_claim.py). - Signed team config -
MembershipManager(owner_identity=...)makes everyteam.jsonsave Ed25519-signed; tampered configs pushed viagit_syncare rejected on load. - Constant-time token comparison (
hmac.compare_digest). - Windows ACL hardening for private key files (
icacls /grant + /inheritance:rwith read self-check). - Identity tamper detection -
AgentIdentity.load()verifies the stored pubkey is actually derivable from the private key.
New capabilities (P4 + P5)
- Web-of-Trust -
nth_dao.TrustGraph+ signedEndorsements let trust propagate transitively (Alice trusts Bob, Bob trusts Carol -> Alice can accept Carol's signed gossip), bounded by per-endorsementdepth_allowedcaps.GossipNode(trust_graph=, wot_max_depth=2). - People nearby (LAN discovery) - pure-stdlib UDP broadcast based
agent discovery.
LANDiscovery(...).discover(timeout=3.0)returns every nth-dao agent on your subnet, withws_urlready forGossipNode.connect()andpubkey_hexready forTrustGraph. - Fuzzy
PeerFinder.search(query)- substring / prefix / exact scoring acrossagent_id,label,capabilities,groups. - Anti-Sybil reputation credits -
ReputationManager.rate()spends 1 credit per new entry; credits are scoped by pubkey fingerprint so spawning 1000agent_ids doesn't multiply your budget.
Quality
- New
nth_dao/util/io.pycentralisesatomic_write_json,safe_load_json,safe_id, and anInterProcessLock. Six modules previously copy-pasted these. - Tests grew from 23 -> 83 passing.
- Project version is now sourced from
pyproject.tomlviaimportlib.metadatasonth_dao.__version__no longer drifts.
# Find nearby agents and bootstrap trust in 4 lines:
peers = nth.LANDiscovery(agent_id="me").discover(timeout=3.0)
trust = nth.TrustGraph(workspace)
for p in peers:
trust.add_root(p.agent_id, p.pubkey_hex)
What Is NTH DAO?
NTH DAO is a Web3-oriented collaboration protocol layer for humans, agents, bots, tools, and service nodes. It gives every DAO a local-first foundation:
- Identity - recognizable, auditable, authorizable members and agents
- Membership - join requests, invitations, roles, permissions, approval
- Groups - channels, messages, announcements, tasks, audit, trust hints
- Discovery - agents find each other across local processes and synced nodes
- Missions - long-running work can be routed, claimed, handed off, completed
- Memory - shared blackboard, ledger, skills, and DAO knowledge
- Local-first sync - plain files that can be stored offline and synced by Git
- Agent adapters - pluggable backends for local and external agents
Core functionality uses only the Python standard library.
30-Second Quickstart
import nth_dao as nth
with nth.attach(
agent_id="alice",
backend="mock",
capabilities=["python", "frontend"],
groups=["payments"],
) as dao:
teammate = dao.find_teammate(capability="backend")
print(teammate.record.agent_id if teammate else "none online")
mission = dao.start_mission(
title="ship payments v2",
goal="end-to-end refactor",
steps=[
{"id": "api", "description": "design API", "required_capabilities": ["backend"]},
{
"id": "ui",
"description": "build UI",
"required_capabilities": ["frontend"],
"depends_on": ["api"],
},
],
)
if next_mission := dao.take_next_work():
dao.runner.complete(next_mission.id, "ui", note="shipped")
Local DAO Group Chat
Start the local-first DAO group UI:
python -m nth_dao.web
Then open:
http://127.0.0.1:8080/
The UI shows the DAO group id, member list, channels, messages, announcements,
tasks, and a simple search box. With the default open policy, entering an
agent_id and clicking Join / Switch creates or switches to that member.
Installation
git clone https://github.com/AlexNthLab/nth-dao.git
cd nth-dao
pip install -e .
Optional extras:
pip install "nth-dao[crypto]" # Ed25519 agent identity/signing
pip install "nth-dao[web]" # FastAPI/uvicorn examples
pip install "nth-dao[contracts]" # Pydantic-backed contracts
Architecture
nth_dao.attach()
|
+-- identity and membership
+-- roles and permissions
+-- local-first group layer
+-- discovery registry
+-- mission orchestration
+-- blackboard and memory providers
+-- audit, trust, and reputation hints
+-- backend adapters
Files are intentionally simple and inspectable:
team.json- DAO identity, join policy, members, rolesteam_agents/*.json- discovered/online agent recordsteam_channels/*.json- channelsteam_channels/*.messages.jsonl- append-only messagesteam_audit/audit.jsonl- append-only DAO eventsteam_tasks/*.json- local-first tasksteam_trust/*.json- simple trust hints
These files can be kept local, synced with Git, or merged by future transport layers.
Design Principles
- Local-first before central service
- File/Git syncable before database lock-in
- Explicit identity before anonymous automation
- Real permissions before decorative roles
- Audit logs before opaque side effects
- Stable DAO primitives before marketplace or settlement features
- Agent-to-Agent compatibility without hiding human governance
Examples
| File | What it shows |
|---|---|
examples/group_chat_server.py | Local DAO group chat UI |
examples/nth_demo.py | Discovery and mission relay |
examples/blackboard_demo.py | Shared blackboard collaboration |
examples/multi_backend_demo.py | Cross-backend agent coordination |
examples/evo_demo.py | EvoLoop self-improvement pipeline |
examples/sync_demo.py | Multi-terminal Git sync |
examples/team_entrypoint.py | Production-style CLI entrypoint |
Migration Notice
NTH DAO is a hard rename. Existing forks or local checkouts should update their imports and package references:
import nth_dao as nth
Internal class names such as TeamSession and TeamRole are kept for now to
avoid unnecessary churn in the runtime model. The public package identity is
NTH DAO only.
License
MIT. See LICENSE.