DevLens Stellar 🔍

A developer intelligence layer for Stellar — simulate before you submit, debug when things fail, verify before you trust.

DevLens Stellar fills a critical gap in the Stellar developer ecosystem: there is no single tool that helps developers confidently build on Stellar by predicting outcomes before submission, explaining failures in plain English, and verifying the trustworthiness of accounts and assets.

---

🔍 The Problem

Every Stellar developer hits these walls:

• "Why did my transaction fail?" — Horizon returns cryptic XDR error codes with no explanation
• "Will this transaction succeed?" — No way to know without actually submitting it
• "Can I trust this account or asset?" — No quick verification tool exists

DevLens Stellar solves all three.

---

✨ Three Modules

🔮 Simulate

Predict what will happen before you spend a fee submitting to the network.

• Simulate full transaction XDRs
• Simulate simple payment outcomes
• Get smart fee recommendations based on live network conditions

🐛 Debug

When something goes wrong, understand exactly why — in plain English.

• Debug failed transactions by hash
• Decode raw result XDRs
• Look up any Stellar error code instantly
• Decode transaction envelope XDRs into readable JSON

✅ Verify

Before you interact with an unknown account or asset, know if you can trust it.

• Account trust score (home domain, stellar.toml, age, flags)
• Asset verification (issuer identity, toml listing, authorization flags)
• Transaction pre-flight checks before submission

---

🚀 Getting Started

Prerequisites

• Node.js >= 18
• npm >= 9

Installation

git clone https://github.com/stellarkit-lab-devtools/devlens-stellar.git
cd devlens-stellar
npm install
cp .env.example .env
npm run dev

---

📡 API Endpoints

Simulate

Method	Endpoint	Description
POST	/simulate/transaction	Simulate a full transaction XDR
POST	/simulate/payment	Simulate a simple payment
GET	/simulate/fee-estimate	Get recommended fee tiers

Debug

Method	Endpoint	Description
POST	/debug/transaction	Debug a failed transaction by hash
POST	/debug/xdr	Decode a result XDR
POST	/debug/error-code	Look up a single error code
GET	/debug/error-codes	List all known error codes
POST	/debug/decode-envelope	Decode a transaction envelope XDR

Verify

Method	Endpoint	Description
GET	/verify/account/:id	Verify account trust score
GET	/verify/asset/:code/:issuer	Verify asset legitimacy
POST	/verify/transaction	Pre-flight check a transaction

---

📝 Usage Examples

Debug a Failed Transaction

curl -X POST http://localhost:3000/debug/transaction \
  -H "Content-Type: application/json" \
  -d '{ "hash": "abc123...64chars" }'

Response:

{
  "success": true,
  "data": {
    "status": "failed",
    "diagnosis": {
      "transaction": {
        "code": "tx_bad_seq",
        "message": "The transaction sequence number is incorrect.",
        "fix": "Fetch the account current sequence number and use it + 1."
      }
    }
  }
}

Verify an Account

curl http://localhost:3000/verify/account/GAAZI4TCR3TY5OJHCTJC2A4QSY6CJWJH5IAJTGKIN2ER7LBNVKOCCWN

Response:

{
  "success": true,
  "data": {
    "trustScore": "high",
    "summary": "This account has a high trust score based on 5/5 checks passed.",
    "checks": [...]
  }
}

Simulate a Payment

curl -X POST http://localhost:3000/simulate/payment \
  -H "Content-Type: application/json" \
  -d '{
    "senderAccount": "GAAZI4...",
    "destinationAccount": "GBVFTZ...",
    "amount": "100",
    "assetCode": "XLM"
  }'

---

🧪 Running Tests

npm test

---

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting a PR.

---

📁 Project Structure

devlens-stellar/
├── src/
│   ├── config/
│   │   └── stellar.js          # Stellar SDK + Horizon setup
│   ├── middleware/
│   │   └── errorHandler.js     # Centralised error handling
│   ├── routes/
│   │   ├── simulate.js         # Simulate module endpoints
│   │   ├── debug.js            # Debug module endpoints
│   │   └── verify.js           # Verify module endpoints
│   ├── utils/
│   │   ├── errorDecoder.js     # Stellar error code translator
│   │   └── validators.js       # Input validation helpers
│   └── index.js                # App entry point
├── tests/
│   └── api.test.js
├── .env.example
├── package.json
└── README.md

---

🌐 Stellar Resources

• Stellar Developers Portal
• Stellar JavaScript SDK
• Horizon API Reference
• Stellar Error Codes
• Stellar Discord

---

📄 License

MIT