{"id":44025602,"url":"https://github.com/dotandev/hintents","last_synced_at":"2026-02-07T17:34:47.524Z","repository":{"id":333484289,"uuid":"1137458714","full_name":"dotandev/hintents","owner":"dotandev","description":"A CLI tool for the Stellar Soroban ecosystem that replays failed transactions locally to generate verbose, colorized stack traces and diagnostic events, making smart contract debugging significantly easier.","archived":false,"fork":false,"pushed_at":"2026-01-28T22:26:30.000Z","size":5297,"stargazers_count":3,"open_issues_count":140,"forks_count":26,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-29T01:15:28.047Z","etag":null,"topics":["cli","stellar-blockchain","stellar-network"],"latest_commit_sha":null,"homepage":"https://github.com/dotandev/hintents/internal/rpc","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dotandev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-19T11:53:16.000Z","updated_at":"2026-01-28T22:26:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dotandev/hintents","commit_stats":null,"previous_names":["dotandev/hintents"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dotandev/hintents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotandev%2Fhintents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotandev%2Fhintents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotandev%2Fhintents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotandev%2Fhintents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dotandev","download_url":"https://codeload.github.com/dotandev/hintents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotandev%2Fhintents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29201289,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-07T16:28:23.579Z","status":"ssl_error","status_checked_at":"2026-02-07T16:28:22.566Z","response_time":63,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","stellar-blockchain","stellar-network"],"created_at":"2026-02-07T17:34:46.864Z","updated_at":"2026-02-07T17:34:47.514Z","avatar_url":"https://github.com/dotandev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Erst By Hintents\n\n**Erst** is a specialized developer tool for the Stellar network, designed to solve the \"black box\" debugging experience on Soroban.\n\n\u003e **Status**: Active Development (Pre-Alpha)\n\u003e **Focus**: Soroban Error Decoding \u0026 Transaction Replay\n\n## Scope \u0026 Objective\n\nThe primary goal of `erst` is to clarify **why** a Stellar smart contract transaction failed.\n\nCurrently, when a Soroban transaction fails on mainnet, developers receive a generic XDR error code. `erst` aims to bridge the gap between this opaque network error and the developer's source code.\n\n**Core Features (Planned):**\n\n1.  **Transaction Replay**: Fetch a failed transaction's envelope and ledger state from an RPC provider.\n2.  **Local Simulation**: Re-execute the transaction logically in a local environment.\n3.  **Trace decoding**: Map execution steps and failures back to readable instructions or Rust source lines.\n4.  **Source Mapping**: Map WASM instruction failures to specific Rust source code lines using debug symbols.\n\n## Usage (MVP)\n\n### Debugging a Transaction\n\nFetches a transaction envelope from the Stellar Public network and prints its XDR size (Simulation pending).\n\n```bash\n./erst debug \u003ctransaction-hash\u003e --network testnet\n```\n\n### Interactive Trace Viewer\n\nLaunch an interactive terminal UI to explore transaction execution traces with search functionality.\n\n```bash\n./erst debug \u003ctransaction-hash\u003e --interactive\n# or\n./erst debug \u003ctransaction-hash\u003e -i\n```\n\n**Features:**\n\n- **Search**: Press `/` to search through traces (contract IDs, functions, errors)\n- **Tree Navigation**: Expand/collapse nodes, navigate with arrow keys\n- **Syntax Highlighting**: Color-coded contract IDs, functions, and errors\n- **Fast Navigation**: Jump between search matches with `n`/`N`\n- **Match Counter**: See \"Match 2 of 5\" status while searching\n\nSee [internal/trace/README.md](internal/trace/README.md) for detailed documentation.\n\n### Audit log signing (software / HSM)\n\n`erst` includes a small utility command to generate a deterministic, signed audit log from a JSON payload.\n\n#### Software signing (Ed25519 private key)\n\nProvide a PKCS#8 PEM Ed25519 private key via env or CLI:\n\n- Env: `ERST_AUDIT_PRIVATE_KEY_PEM`\n- CLI: `--software-private-key \u003cpem\u003e`\n\nExample:\n\n```bash\nnode dist/index.js audit:sign \\\n  --payload '{\"input\":{},\"state\":{},\"events\":[],\"timestamp\":\"2026-01-01T00:00:00.000Z\"}' \\\n  --software-private-key \"$(cat ./ed25519-private-key.pem)\"\n```\n\n#### PKCS#11 HSM signing\n\nSelect the PKCS#11 provider with `--hsm-provider pkcs11` and configure the module/token/key via env vars.\n\nRequired env vars:\n\n- `ERST_PKCS11_MODULE` (path to the PKCS#11 module `.so`)\n- `ERST_PKCS11_PIN`\n- `ERST_PKCS11_KEY_LABEL` **or** `ERST_PKCS11_KEY_ID` (hex)\n- `ERST_PKCS11_PUBLIC_KEY_PEM` (SPKI PEM public key for verification/audit metadata)\n\nOptional:\n\n- `ERST_PKCS11_SLOT` (numeric index into the slot list)\n- `ERST_PKCS11_TOKEN_LABEL`\n\nExample:\n\n```bash\nexport ERST_PKCS11_MODULE=/usr/lib/softhsm/libsofthsm2.so\nexport ERST_PKCS11_PIN=1234\nexport ERST_PKCS11_KEY_LABEL=erst-audit-ed25519\nexport ERST_PKCS11_PUBLIC_KEY_PEM=\"$(cat ./ed25519-public-key-spki.pem)\"\n\nnode dist/index.js audit:sign \\\n  --hsm-provider pkcs11 \\\n  --payload '{\"input\":{},\"state\":{},\"events\":[],\"timestamp\":\"2026-01-01T00:00:00.000Z\"}'\n```\n\nThe command prints the signed audit log JSON to stdout so it can be redirected to a file.\n\n## Documentation\n\n- **[Architecture Overview](docs/architecture.md)**: Deep dive into how the Go CLI communicates with the Rust simulator, including data flow, IPC mechanisms, and design decisions.\n- **[Project Proposal](docs/proposal.md)**: Detailed project proposal and roadmap.\n- **[Source Mapping](docs/source-mapping.md)**: Implementation details for mapping WASM failures to Rust source code.\n- **[Debug Symbols Guide](docs/debug-symbols-guide.md)**: How to compile Soroban contracts with debug symbols.\n\n## Technical Analysis\n\n### The Challenge\n\nStellar's `soroban-env-host` executes WASM. When it traps (crashes), the specific reason is often sanitized or lost in the XDR result to keep the ledger size small.\n\n### The Solution Architecture\n\n`erst` operates by:\n\n1.  **Fetching Data**: Using the Stellar RPC to get the `TransactionEnvelope` and `LedgerFootprint` (read/write set) for the block where the tx failed.\n2.  **Simulation Environment**: A Rust binary (`erst-sim`) that integrates with `soroban-env-host` to replay transactions.\n3.  **Execution**: Feeding the inputs into the VM and capturing `diagnostic_events`.\n\nFor a detailed explanation of the architecture, see [docs/architecture.md](docs/architecture.md).\n\n## How to Contribute\n\nWe are building this open-source to help the entire Stellar community.\n\n### Prerequisites\n\n- Go 1.21+\n- Rust (for building the simulator binary)\n- Stellar CLI (for comparing results)\n\n### Getting Started\n\n1.  Clone the repo:\n    ```bash\n    git clone https://github.com/dotandev/hintents.git\n    cd hintents\n    ```\n2.  Build the Rust simulator:\n    ```bash\n    cd simulator\n    cargo build --release\n    cd ..\n    ```\n3.  Run tests:\n    ```bash\n    go test ./...\n    ```\n\n### Development Roadmap\n\nSee [docs/proposal.md](docs/proposal.md) for the detailed proposal.\n\n1.  [x] **Phase 1**: Research RPC endpoints for fetching historical ledger keys.\n2.  [x] **Phase 2**: Build a basic \"Replay Harness\" that can execute a loaded WASM file.\n3.  [x] **Phase 3**: Connect the harness to live mainnet data.\n4.  [ ] **Phase 4**: Advanced Diagnostics \u0026 Source Mapping (Current Focus).\n\n## Contributors\n\nThanks goes to these wonderful people:\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/dotandev\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/105521093?v=4\" width=\"100px;\" alt=\"dotdev.\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003edotdev.\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#code-dotandev\" title=\"Code\"\u003eCode\u003c/a\u003e \u003ca href=\"#doc-dotandev\" title=\"Documentation\"\u003eDocumentation\u003c/a\u003e \u003ca href=\"#ideas-dotandev\" title=\"Ideas \u0026 Planning\"\u003eIdeas \u0026 Planning\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n\n---\n\n_Erst is an open-source initiative. Contributions, PRs, and Issues are welcome._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotandev%2Fhintents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdotandev%2Fhintents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotandev%2Fhintents/lists"}