Opening

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,50 @@
+## Description
+
+<!-- What does this PR do and why? -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor / cleanup
+- [ ] Documentation
+- [ ] Test coverage
+- [ ] Infrastructure / CI
+
+---
+
+## Capability-claim checklist
+
+Every PR that touches **contracts, backend routes, or the agent script** must complete this section.
+Skip it only for docs-only or CI-only changes.
+
+### For each README capability claim affected by this PR:
+
+- [ ] I have verified the claim against the code in this PR (or confirmed it was already correct)
+- [ ] If I am **adding** a new capability, the README or docs reflect _exactly_ what the code enforces — not what it _intends_ to enforce eventually
+- [ ] If I am **removing or relaxing** a guarantee, the README correction is included in this PR
+- [ ] If a gap remains after this PR (i.e. the claim is still aspirational), a tracking issue exists and the README links to it
+
+### Specific claims to re-verify if you touched the relevant code:
+
+| Claim | Code location to check |
+|---|---|
+| `list_services_page` returns results sorted by reputation within a page | `contract/src/lib.rs` `list_services_page` |
+| Pre-payment spend check runs before x402 call | `backend/src/routes/agents.js` `can-spend` handler + `agent/agent.js` `checkSpend` |
+| `record_payment` updates daily-spend counter | `contract/agents/src/lib.rs` `record_payment` |
+| Score changes: +10 success, −25 failure | `contract/agents/src/lib.rs` `SCORE_SUCCESS` / `SCORE_FAILURE` |
+| `is_eligible` gates access by minimum score | `contract/agents/src/lib.rs` `is_eligible` |
+| Duplicate registration is rejected | `contract/src/lib.rs` `active_service_exists` |
+
+### Open known gaps (do not re-introduce misleading claims about these):
+
+- **#1** Global reputation sort is per-page only, not globally guaranteed
+- **#2** `record_payment` does not call `check_spending_allowed` on-chain; enforcement is backend-only
+
+---
+
+## Testing
+
+- [ ] Existing tests pass (`npm test` / `cargo test`)
+- [ ] New behaviour is covered by tests
+- [ ] Any contract change has a corresponding Soroban unit test

CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and maintainers of the **Lodestar** project pledge to make participation in our community a harassment-free experience for everyone, regardless of:
+- Age
+- Body size
+- Disability
+- Ethnicity
+- Gender identity and expression
+- Level of experience
+- Nationality
+- Personal appearance
+- Race
+- Religion
+- Sexual identity and orientation
+- Socioeconomic status
+- Technical skill level
+
+We commit to act and interact in ways that contribute to a positive, welcoming, and inclusive environment.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior include:
+- The use of sexualized language or imagery and unwelcome sexual attention or advances
+- Trolling, insulting or harassing comments, or personal or political attacks
+- Public or private harassment
+- Publishing private information about another person without explicit permission
+- Any other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the **Lodestar Project Lead** at **opensource@0xninx.org**. All complaints will be reviewed and investigated promptly and fairly.
+
+The project lead is empowered to take any action they deem appropriate, including but not limited to:
+- Warning the offender
+- Temporary or permanent banning from the project’s communication channels
+- Reporting to relevant authorities if required by law
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).

CONTRIBUTING.md

@@ -1,5 +1,6 @@
 # Contributing to Lodestar
 
+Please review our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
 ## Prerequisites
 
 - Node.js ≥ 22

README.md

@@ -1,10 +1,16 @@
 # Lodestar
 ### Navigate the agent economy — discover, pay, and build trust.
 
-Lodestar solves the missing discovery layer in the x402 agentic payments ecosystem on Stellar — today AI agents can pay for services but cannot find them autonomously because every service URL is hardcoded by a human, so Lodestar ships two Soroban smart contracts: the first is a permanent neutral on-chain registry where any service provider registers their x402 endpoint once with a price and category and it becomes discoverable forever, and the second tracks every AI agent's on-chain identity giving each agent a credit score from 0 to 1000 that rises with successful payments and falls with failures, enforces programmable per-transaction and daily spending limits at the contract level, and allows service providers to gate access to premium services by minimum score — all of this is exposed through an Express backend with real x402-protected demo endpoints for weather and search, a Next.js frontend where providers can register services and agents can view their scores, and a standalone autonomous agent script that starts with zero hardcoded URLs, queries the registry, discovers the best service by reputation, pays via USDC on Stellar testnet through the x402 protocol, receives real data back, and updates its own credit score on-chain — making Lodestar the complete infrastructure layer for the agentic economy covering discovery, payment, and trust in a single production-grade open source project that directly addresses all three requirements the Stellar Hacks judges explicitly called out in the hackathon brief.
+AI agents on Stellar can already pay for services via the x402 protocol — but they can't find those services on their own. Every URL is still hardcoded by a human. Lodestar fixes that.
 
----
+- **Service Registry** — A permanent, permissionless Soroban contract. Providers register an x402 endpoint once; agents query it by category and get back a live, reputation-ranked list. No hardcoded URLs, no gatekeepers.
+- **Agent Credit Scoring** — A second Soroban contract that gives each agent a verifiable on-chain score (0–1000). Scores rise with successful payments and fall with failures. Providers can require a minimum score; spending limits are enforced at contract level and cannot be bypassed.
+- **Autonomous agent demo** — A standalone script that starts with zero hardcoded URLs, discovers the best service by reputation, pays via USDC on Stellar testnet, and updates its own score on-chain — the full loop in one run.
+- **Full stack** — Express backend with x402-protected demo endpoints, Next.js frontend for registration and score inspection, and both contracts deployed on Stellar testnet with live transactions.
 
+**Docs:** [Contract reference](docs/contracts.md) · [Deployment guide](contract/DEPLOY.md) · [Contributing](CONTRIBUTING.md)
+**Code of Conduct:** [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+---
 Lodestar ships two Soroban contracts: the **Service Registry** (discovery + reputation) and the **Agent Credit Scoring** system (identity + trust + spending policies).
 
 ---
@@ -61,8 +67,8 @@ Lodestar is a Soroban smart contract that acts as a neutral, on-chain registry.
 5. Your service is now permanently discoverable by any agent querying the registry
 
 ### Agent flow
-1. Call `list_services(category)` — returns active services sorted by reputation
-2. Pick the top result (highest reputation, lowest price, or newest)
+1. Call `list_services_page(page, page_size, category)` — returns active services for the requested page, sorted by reputation descending within each page
+2. Select a service — the reference agent uses weighted-random selection among the top-N candidates so higher-reputation services are proportionally preferred without being the sole option
 3. Make an HTTP request to the endpoint — receive a `402 Payment Required` response
 4. Build and sign an x402 payment transaction on Stellar using the agent's keypair
 5. Retry the request with the payment header — receive the data
@@ -192,8 +198,8 @@ Every agent is anonymous. Services cannot distinguish a reliable agent from a br
 - Agents register on-chain and start with score **100**
 - Every successful x402 payment increases score by **+10**
 - Every failed payment decreases score by **−25**
-- Services can set minimum score requirements
-- Spending policies are enforced at contract level — cannot be bypassed
+- Services can call `is_eligible(address, min_score)` to gate access by minimum score
+- Spending policies are stored on-chain; the pre-payment check (`check_spending_allowed`) currently runs in the backend before the x402 call ([tracking: #2](#known-gaps))
 
 ### Score Tiers
 
@@ -212,7 +218,7 @@ Each agent has a programmable spending policy:
 - Maximum USDC per day (resets every ~17,280 ledgers ≈ 24 hours)
 - Allowed service categories
 
-Enforced at smart contract level — cannot be bypassed even if the agent wallet has sufficient balance.
+The policy is stored on-chain and `check_spending_allowed` is a pure read-only contract query. The backend enforces it before initiating any x402 payment. The `record_payment` entrypoint updates the on-chain daily-spend counter after a successful payment but does not currently re-check the limit at write time — see [Known Gaps](#known-gaps) below.
 
 ### Deploy the Agent Contract
 
@@ -233,6 +239,30 @@ cd backend && npm run seed-agents
 
 ---
 
+## Known Gaps
+
+These are capabilities documented elsewhere as planned; the current implementation differs in the ways described below. Each gap has an open tracking issue.
+
+### \#1 — Global reputation sort across pages
+
+`list_services_page` sorts by reputation **within a single page**. Because the IDs array is stored in registration order, a service with a high reputation on page 2 will not appear ahead of a lower-reputation service on page 1. A globally sorted view requires either a sorted index at write time or an off-chain sort at the API layer.
+
+**Workaround:** the backend's `GET /api/services` response includes all active services in one call; clients that need a globally sorted list should consume that endpoint.
+
+**Tracking:** [GitHub issue #1 — Global reputation sort across registry pages](https://github.com/0xNinx/lodestar/issues/1)
+
+---
+
+### \#2 — Pre-payment spending-limit enforcement is backend-only
+
+The `SpendingPolicy` struct and `check_spending_allowed` query are on-chain. `record_payment` updates the `daily_spent_stroops` counter on-chain after a successful payment. However, `record_payment` does **not** call `check_spending_allowed` internally before writing; if a caller bypasses the backend (e.g. invokes `record_payment` directly via the Stellar CLI), the per-transaction and daily caps are not re-checked at write time.
+
+Concretely: the backend always calls `check_spending_allowed` before initiating an x402 payment, so clients going through the API are protected. Direct contract callers are not.
+
+**Tracking:** [GitHub issue #2 — record_payment should enforce spending limits on-chain](https://github.com/0xNinx/lodestar/issues/2)
+
+---
+
 ## Agent Leaderboard
 
 The `/agents` page (`frontend/app/agents/page.tsx`) is a paginated leaderboard of all registered agents, sorted by score, activity, or registration date.