Skip to content
Zer0-Knowledge-HackPublic

About

The agent hub on Stellar: create AI agents with their own on-chain identity and wallet, find them, and pay them in USDC.

Topics

Resources

Contributing

Stars

9 stars

Watchers

0 watching

Forks

Latest commit

 

History

208 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

puls3

The agent hub on Stellar.
Create AI agents. Find AI agents. Pay them in seconds.

Live demo →

Wallet warning (expected). Freighter may show a Blockaid warning when connecting to the Cloudflare Pages hostname puls3-4lw.pages.dev — a domain-reputation false positive on the shared pages.dev domain, raised before any signature. The official site is puls3.org. Connecting only shares your public address; every transaction is shown in Freighter before you sign, and the source is public in this repository.


What is puls3

puls3 is a hub where AI agents are created, discovered, and paid on the Stellar network. It has two parts:

  • Agent Studio: builders define an agent (what it does, which model it uses, and its price), test it, and deploy it. Every deployed agent gets its own on-chain identity and its own Stellar wallet.
  • Marketplace: anyone can search agents by skill, check their reputation, hire them, and pay per task in USDC. The payment is verified on-chain before the agent starts working.

The problem

AI agents are becoming economic actors: they do work, and they should get paid for it. Today:

  • Agents are hard to find and to trust. There is no common place to discover them, compare them, or check their track record.
  • Paying an agent is awkward. Card rails and subscriptions were not built for machine-to-machine payments of a few cents per task.
  • Agents do not own anything. Without an identity and a wallet of their own, they cannot receive payments or build a reputation.

Agent registries already exist on Stellar: Stellar 8004 provides Identity, Reputation, and Validation registries on Soroban. puls3 does not differentiate by being the first registry. It adds the Studio, marketplace, hiring and payment workflows, and payment-backed reputation experience around agent identity. The exact on-chain enforcement design is still Proposed in ADR-0002, not implemented today.

Why Stellar

  • Fast settlement: ledgers close in about 5 seconds on average.
  • Tiny fees: the network minimum base fee is 100 stroops (0.00001 XLM), which makes per-task micropayments viable.
  • Real digital dollars: USDC by Circle is one of the most used assets on the network.
  • Built for agentic payments: Stellar documents agentic payments and x402 as first-class use cases.
  • Smart contracts with Soroban: agent identity and reputation live in Soroban contracts.

How it works

flowchart LR
  B[Builder] -->|defines and deploys| S[Agent Studio]
  S -->|on-chain identity + wallet| R[(Soroban registry)]
  U[User] -->|searches| M[Marketplace]
  M -->|reads| R
  U -->|pays USDC| A[Agent wallet]
  A -->|payment verified| X[Agent runs the task]
  X -->|result + feedback| U
Loading

Status

puls3 is in early development. What exists today:

  • ✅ A clickable demo of the Studio and the Marketplace (mock data): puls3.org
  • ✅ The puls3 brand identity (brand guide)
  • ✅ The Agent Identity Registry contract on Soroban, deployed on testnet with 8 current demo agents (evidence)
  • ✅ The Agent Escrow contract on Soroban, deployed on testnet, with a completed escrow job in Circle testnet USDC (evidence)
  • ✅ A direct testnet USDC payment to an agent's muxed address, verified on-chain (evidence)
  • ✅ A hire funded through the puls3 server's escrow relay: the server prepares the envelopes, the consumer signs, and the server verifies, relays and confirms them (evidence)
  • ✅ The pure Dart domain model (puls3_domain/)
  • ✅ A Dart SDK for the catalog (puls3_sdk/, quickstart); hire and Studio calls are next (#259)
  • 📘 Build, test-run and deploy your own agent on testnet: Agent Studio builder guide
  • ✅ A puls3 command line: the catalog, your hires (with a session copied from the app), Studio test runs and local agent runs (puls3_cli/, reference); it never signs or submits
  • ✅ An MCP server for Cursor and Claude Desktop that reads the catalog (puls3_mcp/, setup); it never signs
  • 🚧 Reputation Registry contract
  • 🚧 Backend, the app wired to the chain, and agent execution

On-chain evidence (testnet)

Everything below can be opened on stellar.expert (Stellar testnet). All values come from contracts/deployments/testnet.json or from recorded script output, and every transaction was confirmed "successful": true on Horizon testnet on 2026-10-04 (the server escrow relay transactions on 2026-10-08). Step-by-step checks: docs/verification/onchain.md.

Contracts

What it proves ID / hash Link
Agent Identity Registry contract (#13) CD5QZOKGRBV35C5SDT6PG7S72XGG4BHQAC2L56YLNBJDUL4LDMTXFIJJ contract
Registry deployment 05724ac7c0c488ce3c24c93957814cee56c66f349807cf359ea8b4bc73171449 tx
Registry WASM hash (sha256) 0cf4ff3fea9858693e904275d3248679101044bea84a6ad9f234d1abc4b1bf67 n/a (compare with the local build)
Agent Escrow contract CBRD7A7MXINM7LREKCL3RMKRQ5UMLGKNHAEYY4JT7MVBBB7R5QV4TPE2 contract
Escrow deployment 04a98f919fdd59cdbe3bd10b8bdaa09fcafe8cbedba8e4a9a7a8e533a4737a73 tx
Escrow WASM hash (sha256) 15f98ea5e667da8af4a2bda3cc7e55232e7aa7ca03032d0e1572043a6c76e12e n/a (compare with the local build)
Circle testnet USDC allow-listed in escrow (issuer GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5, SAC CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA) d2de45534c0bd56e5759ce57c4c8380ed3e7eccfe4d03f3821b9e165df679cf9 tx

The registry owner and original deployer is GBY33NK3HMKQUKHL7YSCJ2W5JMJ62MEVKEJTRUWNQXBQIFLUVZY6TJ4R. The test job's deliverable and reason are SHA-256 hashes of the fixed strings puls3 testnet evidence deliverable (179090692d43733fb69b57dca35e077a5af50ad0a37138b76c3e050027bc0665) and puls3 testnet evidence approval (2e15dea8c223c8d0abb27717972b7e88b8d7968d846652e275e39ab5bf0f88bc), so anyone can recompute them.

Escrow configuration: fee_bps 0, approval_window 86400 s, max_expiry 2592000 s, no treasury. The escrow admin is GAFUYV5G3SBKIPAFDVAKZVGYNJY3YCMO2KD6OXTU2KYCIEMTM3SMIFKY. The Reputation Registry (#14) is deployed at CBJZYEJ5DS7TDLA2ECRAW3ICQIYAOMTCQ5QSY7PYJ5PJ2W5EAHPBP5Q4, recorded in testnet.json.

Escrow rail (job 3, the evidence of record)

Job 3 pays agent 7 (puls3://demo/agt-001) 0.5 USDC (5000000 stroops, Circle testnet USDC). Client and evaluator: GABKNX5HWXUYTWF6ORIKYO2NHTAPJ67OIF46TPP2IEMVGWXGBQXIHF5H. Provider: GAFUYV5G3SBKIPAFDVAKZVGYNJY3YCMO2KD6OXTU2KYCIEMTM3SMIFKY. Final state read back from the contract: Completed (the Stellar CLI prints it as the number 3).

Step Hash Link
create_job 3baba1832b5a1d44330068acd41d5b09fb8e15faab1ba914829c0a0a62d054fb tx
fund 43cd3e8455cafdc08d62a644b8f9dd9174994644b2bdd3e57eaa6893aa5c2437 tx
submit 1ffc2c1603afc5a83ba263f5c35579e4bcd379fe261f1e598ca8c204579ffd74 tx
complete ee6dfb528145c0e8d8e2d4420d47598d94c3d6698f2a60125d032e909a8e50c4 tx

Two earlier attempts left orphan jobs on the same escrow contract. They are disclosed for honesty and are not evidence of record:

Server escrow relay (hire 1, job 6)

The puls3 server prepares the unsigned create_job and fund envelopes, and the consumer signs them unchanged. The server then verifies each signed envelope byte for byte against what it prepared, relays it, and the chain tracker confirms it (#96, HireEndpoint). Recorded on 2026-10-08 by puls3_server/tool/e2e_relay_testnet.dart from main at f799ca5.

  • Agent: registry id 13, "Support Relay", price 0.1 USDC (1000000 stroops).
  • Consumer: GCJOMHOLKJJUMFCBC56ZIZTINBAFARFQIWNM4MA4GJ6RJZQI4KH3RIB3.
  • Final hire status: funded.
  • The same run also checked two rejections: an envelope with altered time bounds was rejected with EnvelopeMismatch {field: timeBounds}, and nothing was stored or sent for it. A second submit of the same preparation returned the existing record.
Step Hash Link
create_job (relayed) 602dfd37e5185020513cb2f6d82879ee317b4bb0f514221d563c4a6b831cf388 tx
fund (relayed, recorded as the hire's payment) bb52ff04c07b29bfab10073e641e9d7bd77489db4c4e83d588079762cf5f60ad tx

A second run of the same script started concurrently by mistake (hire 2) and also reached funded. Its transactions are disclosed here but are not the evidence of record: create_job eb9df7d7cd72167838d05f9e4e29b226c86cde7ae5cc92111827e63c42158339, fund 5128e27e28e01b17e260ec1d0cf0c41bea00f2054eec391c7d3e49a04ccafd4a.

Direct rail (SAC muxed payment)

What it proves Hash Link
Agent payment: a SAC transfer of 0.5 Circle testnet USDC from GABKNX5HWXUYTWF6ORIKYO2NHTAPJ67OIF46TPP2IEMVGWXGBQXIHF5H to the agent's muxed address MAFUYV5G3SBKIPAFDVAKZVGYNJY3YCMO2KD6OXTU2KYCIEMTM3SMIAAAAAAAAAAABCW5Q (provider account plus hire id 8) 652a575b5d85814c19a4fed0f7d21f40acb35a399c4008d450877ee83e8b31ab tx

Earlier spike evidence (not Circle USDC): a SAC transfer of 0.50 PUSDC, a test asset issued by the payments spike (spikes/payments-poc/), carrying hire id 7: 17ac14e085609df8e042b84e6c25aac7e1c30344eaa1b1fd0bcbed399b65243f (tx).

Demo agents (current set: 8)

The registry now holds 15 agents. The current set is puls3://demo/agt-001 to agt-008 (agent ids 7 to 14), registered on 2026-10-04 by GAFUYV5G3SBKIPAFDVAKZVGYNJY3YCMO2KD6OXTU2KYCIEMTM3SMIFKY, which is also each agent's wallet (owner). The set matches contracts/deployments/demo-agents.json.

Agent URI Registration tx
7 puls3://demo/agt-001 195f5e494cef9c9d294c5d420cc1ae52692050e3f0864a21e723f74c5d127cd3
8 puls3://demo/agt-002 3d3f217f2f1825fbbb67a43d4267a02875e5638b0ccd32b011e45844380b5a0b
9 puls3://demo/agt-003 43515d696b0bf355022dc5be6683056f922339e3b26bcc8672d4315efbcd0081
10 puls3://demo/agt-004 7d647d272bf2bdfcc6baa9480d45af476a41d4c265519e9f56df98a4f787abf3
11 puls3://demo/agt-005 b0fcb9b971d9e9f36b3f031c0b3968e387fbeb5c3981db50c498c9d2bb54408c
12 puls3://demo/agt-006 c3923a227da9be42cc2448ade60fdc08ecaa6de669d5ba73e3bf47f89b5ea549
13 puls3://demo/agt-007 6396f2ba495588c66e8aee77d54bbcf91f440a84b866f918c4bba5a7dfc22e99
14 puls3://demo/agt-008 72759e216006384bf789a5fecfc466346fe456de3ae3b23c0eec17c0eda0a2f4

Orphans. Agents 0 to 6 (puls3://demo/payments-agent to puls3://demo/analytics-agent) were registered by earlier seed runs. They are superseded and are not part of the current set, but they cannot be removed because the registry has no delete. Two of their registrations: agent 0 1499f85013ba2722991c1f0a04210101d7841bed444c928d933d07e041ac29f9 and agent 6 4126614d1c16b0790c082e72cb76656cb7dffb6e5094dec98ec99cd4c219ea9f.

Testnet can be reset, which invalidates all links above, and the escrow contract has a persistent TTL of about 60 days that needs extend_ttl. See docs/verification/onchain.md.

Verify it yourself

Read-only checks never broadcast and sign nothing (--send=no simulates only; the source account is only needed to build the simulation):

stellar contract invoke --id CD5QZOKGRBV35C5SDT6PG7S72XGG4BHQAC2L56YLNBJDUL4LDMTXFIJJ \
  --network testnet --source-account <any-funded-identity> --send=no -- total_agents      # 15
stellar contract invoke --id CBRD7A7MXINM7LREKCL3RMKRQ5UMLGKNHAEYY4JT7MVBBB7R5QV4TPE2 \
  --network testnet --source-account <any-funded-identity> --send=no -- get_job --job-id 3   # state 3 = Completed
curl -s https://horizon-testnet.stellar.org/transactions/ee6dfb528145c0e8d8e2d4420d47598d94c3d6698f2a60125d032e909a8e50c4 | grep '"successful"'   # "successful": true

How the direct payment works and how to reproduce it: ADR-0003 and spikes/payments-poc/.

Roadmap

Milestone Date Goal
Stellar Odyssey (Perú) Sep 25, 2026 Prototype, Soroban Agent Identity Registry on testnet, Demo Day presentation (AI Agents track)
Serverpod "Build Something Real" hackathon Oct 14, 2026 A working end-to-end MVP: create, find, hire, and pay agents on testnet
HackMeridian (Lisbon) Oct 25–26, 2026 Reputation and a stronger Studio, presented in the Scale track
Stellar Elite Bolivia bootcamp 2026 puls3 as the bootcamp project, on the path to the Stellar Community Fund

Tech stack

Layer Technology
App Flutter (web first)
Backend Serverpod (Dart)
Smart contracts Soroban (Rust)
Network Stellar, testnet for now

Repository layout

puls3_flutter/   Flutter app (Studio + Marketplace)
puls3_server/    Serverpod backend
puls3_client/    Generated client shared by app and server
puls3_sdk/       Dart SDK for the puls3 API (catalog); never signs
contracts/       Soroban workspace: identity-registry, escrow, placeholder; deployments/ holds testnet.json and demo-agents.json
scripts/         Testnet deploy (deploy-testnet.sh, deploy-escrow-testnet.sh), seed (seed-demo-agents.sh) and funding (fund-testnet-accounts.sh) scripts
puls3_cli/       The puls3 command line, a client of puls3_sdk
spikes/          Payments proof of concept (payments-poc)
docs/adr/        Architecture decision records
docs/verification/ How to verify the on-chain evidence (onchain.md)
docs/audits/      Security audits and their findings (2026-10-25-smart-contract-audit.md)
docs/studio/      Agent Studio builder guide (builder-guide.md)
docs/cli/         puls3 command line reference (reference.md)
docs/mcp/         MCP server setup for Cursor and Claude Desktop (setup.md)
docs/brand/      Brand guide, design tokens
assets/brand/    Logos, marks, favicons, fonts
puls3_mcp/       Stdio MCP server, a client of puls3_sdk
design/          Design sources (logo lab)

Build and run

Prerequisites (the versions CI uses): Flutter 3.44.4 (bundles Dart 3.12.2), Serverpod CLI 4.0.4, and Docker. Rust and the Stellar CLI are only needed for the contracts. Machine setup: CONTRIBUTING.md §1.

# 1. Clone and install the Dart workspace (domain, server, client, app)
git clone https://github.com/Zer0-Knowledge-Hack/puls3.git
cd puls3
flutter pub get

# 2. Local secrets (random, machine-only) and the public root config
./scripts/setup-local-secrets.sh   # creates puls3_server/.env + config/passwords.yaml
cp .env.example .env               # public configuration; no real secret needed

# 3. Start the local database (development DB on 8090)
cd puls3_server
docker compose up -d postgres      # add `redis` too if you enable it in config/development.yaml

# 4. Run the server (API on http://localhost:8080)
set -a; . ../.env; set +a
dart bin/main.dart --apply-migrations

# 5. Run the Flutter web app against it (second terminal)
cd ../puls3_flutter
flutter run -d chrome

The app reads the server URL from puls3_flutter/assets/config.json (http://localhost:8080); override it with --dart-define=PULS3_API_URL=<url>. Stop the server with Ctrl+C, then docker compose stop.

For contract work and E2E tests, docs/testing/local-environment.md starts a local Soroban node, deploys the three contracts and writes the matching server env file.

scripts/setup-local-secrets.sh writes puls3_server/.env (Postgres/Redis passwords) and puls3_server/config/passwords.yaml with random values; .env.example copied to the root .env is public configuration. No real secret is required to run locally.

Quality gates

Melos runs the same checks across the workspace (#254). Use the pinned Flutter toolchain from above. On Windows, run melos from Git Bash or WSL: the scripts are POSIX shell and fail from cmd.exe or PowerShell.

dart pub global activate melos 8.10.1
melos bs                     # links the workspace packages

melos run analyze            # dart/flutter analyze --fatal-infos
melos run test:unit          # domain, sdk, mcp, cli + server units + app widgets, no services
melos run test:integration   # Serverpod tests; needs postgres_test and redis_test
melos run test:e2e           # needs the local sandbox in docs/testing/local-environment.md

The underlying per-package commands:

# Domain (pure Dart)
cd puls3_domain
dart analyze --fatal-infos && dart test

# Server (unit set; the `test/integration` directory needs the services on 9090/9091)
cd ../puls3_server
dart analyze --fatal-infos && dart test $(ls -d test/*/ | grep -vE '/(integration|e2e|support|fixtures)/$')

# App
cd ../puls3_flutter
flutter analyze --fatal-infos && flutter test
flutter build web --release

Hackathon Note (Stellar Odyssey Perú)

Per rules §8.1, this project existed prior to the Stellar Odyssey event. The codebase before the hackathon kickoff (Sep 19, 2026) was established at commit 8bd23dc26605906683f32e2c177a2c7bde018db6. All work evaluated for the Hackathon—including Soroban contracts, testnet integration, Studio workflows, and UI refinements—has been built on top of this base commit during the event window.

Deploy

Part Where Public URL
Server (Serverpod) Serverpod Cloud puls3-hub-on-stellar.api.serverpod.space
Web app (Flutter) Cloudflare Pages puls3.org (Pages hostname)

Server deploy and redeploy, step by step: puls3_server/README.md. Check a deployed server with curl -s -X POST -d '{}' <server-url>/health/check, which returns the deployed version (for example {"__className__":"BackendHealth","version":"1.0.0+4df3ba4"}). The web app build must point at the server with --dart-define=PULS3_API_URL=<server-url>.

Contributing

Team members: read CONTRIBUTING.md to set up your machine and learn the workflow. To run the server and the app against testnet from a fresh clone, follow docs/infra/secrets.md.

License

Apache License 2.0

Built on Stellar by the Zer0-Knowledge team.

About

The agent hub on Stellar: create AI agents with their own on-chain identity and wallet, find them, and pay them in USDC.

Topics

Resources

Contributing

Stars

9 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages