{"_id":"@accord-protocol/rails-ergo","_rev":"3-816c6665417460c6bb1f4094a49cd5c3","name":"@accord-protocol/rails-ergo","dist-tags":{"latest":"0.4.2"},"versions":{"0.4.0":{"name":"@accord-protocol/rails-ergo","version":"0.4.0","keywords":["accord-protocol","rails","ergo","ergoscript","agent-payments","rail-adapter"],"author":{"name":"bez111"},"license":"MIT","_id":"@accord-protocol/rails-ergo@0.4.0","maintainers":[{"name":"accord-protocol","email":"alexander.bezkrovny@gmail.com"}],"homepage":"https://github.com/accord-protocol/accord-protocol/tree/main/packages/accord-rails-ergo","bugs":{"url":"https://github.com/accord-protocol/accord-protocol/issues"},"dist":{"shasum":"e39edc4b8bf2478445449362fc0919d91348a284","tarball":"https://registry.npmjs.org/@accord-protocol/rails-ergo/-/rails-ergo-0.4.0.tgz","fileCount":6,"integrity":"sha512-5Kxrmp+0mNF0YYmEu9+hjTtz63GfsidfXIGEj25BbX4aBU0MRCObIJAVaeVpTQdiwbxHrSDu8M5JTe0xo4LHmw==","signatures":[{"sig":"MEYCIQCDNUmJwr5W0wXqG+KJzj3JWA99PEyohRUjMeVhNf8COgIhAMlFj6dHHDM5bD0dQLOXKiCAN8UtdI0JNykwrsDFaHqU","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":56115},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"3de0b386d2e83302cac87206d198a8a799b6baa8","scripts":{"test":"npx tsx --test src/__tests__/*.test.ts","build":"tsup src/index.ts --format esm,cjs --dts --clean","typecheck":"tsc --noEmit"},"_npmUser":{"name":"accord-protocol","email":"alexander.bezkrovny@gmail.com"},"repository":{"url":"git+https://github.com/accord-protocol/accord-protocol.git","type":"git","directory":"packages/accord-rails-ergo"},"_npmVersion":"10.9.4","description":"Accord rail adapter for the Ergo Note primitive. verifyPayment fetches the Note from the chain, checks expiry / reserve binding / task-hash / value; settle calls redeemNote and emits a v0 Settlement Receipt with mode=note_redeemed.","directories":{},"_nodeVersion":"22.21.1","dependencies":{"@accord-protocol/core":"^0.4.0","@accord-protocol/rails":"^0.4.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","tsup":"^8.0.0","typescript":"^5.0.0","@types/node":"^20.0.0"},"peerDependencies":{"ergo-agent-pay":"^0.3.0"},"peerDependenciesMeta":{"ergo-agent-pay":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/rails-ergo_0.4.0_1778775559726_0.15421650603765968","host":"s3://npm-registry-packages-npm-production"}},"0.4.1":{"name":"@accord-protocol/rails-ergo","version":"0.4.1","keywords":["accord-protocol","rails","ergo","ergoscript","agent-payments","rail-adapter"],"author":{"name":"bez111"},"license":"MIT","_id":"@accord-protocol/rails-ergo@0.4.1","maintainers":[{"name":"accord-protocol","email":"alexander.bezkrovny@gmail.com"}],"homepage":"https://github.com/accord-protocol/accord-protocol/tree/main/packages/accord-rails-ergo","bugs":{"url":"https://github.com/accord-protocol/accord-protocol/issues"},"dist":{"shasum":"2cea2d6ef220e98e0f153f0a35cc67ff982c5b61","tarball":"https://registry.npmjs.org/@accord-protocol/rails-ergo/-/rails-ergo-0.4.1.tgz","fileCount":6,"integrity":"sha512-dTLiPl1kqtgJPzTQ84HhLS3y8rT5PgiYj7rRknNAXrdI/rVboIRzC3mwaaaNFBDeSYT6iRmB2FGbVU3qp7jw7g==","signatures":[{"sig":"MEQCIHEjbULpad6RCCUema6Zve6kfMGWpniKrkPyKMvMDBP2AiBcHoUNrD2i4rUlIVlP1nzrWJDeyKhmg7xCqNhDR5HshA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@accord-protocol%2frails-ergo@0.4.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":56123},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"e42de427235ef205df05351fb51e607b159d23b6","scripts":{"test":"npx tsx --test src/__tests__/*.test.ts","build":"tsup src/index.ts --format esm,cjs --dts --clean","typecheck":"tsc --noEmit"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:60c1c75d-10ff-49b1-b08a-a5b9b2a1cef9"}},"repository":{"url":"git+https://github.com/accord-protocol/accord-protocol.git","type":"git","directory":"packages/accord-rails-ergo"},"_npmVersion":"11.14.1","description":"Accord rail adapter for the Ergo Note primitive. verifyPayment fetches the Note from the chain, checks expiry / reserve binding / task-hash / value; settle calls redeemNote and emits a v0 Settlement Receipt with mode=note_redeemed.","directories":{},"_nodeVersion":"24.15.0","dependencies":{"@accord-protocol/core":"^0.4.1","@accord-protocol/rails":"^0.4.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","tsup":"^8.0.0","typescript":"^5.0.0","@types/node":"^20.0.0"},"peerDependencies":{"ergo-agent-pay":"^0.3.1"},"peerDependenciesMeta":{"ergo-agent-pay":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/rails-ergo_0.4.1_1778872903220_0.22891874282388347","host":"s3://npm-registry-packages-npm-production"}},"0.4.2":{"name":"@accord-protocol/rails-ergo","version":"0.4.2","description":"Accord rail adapter for the Ergo Note primitive. verifyPayment fetches the Note from the chain, checks expiry / reserve binding / task-hash / value; settle calls redeemNote and emits a v0 Settlement Receipt with mode=note_redeemed.","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup src/index.ts --format esm,cjs --dts --clean","typecheck":"tsc --noEmit","test":"npx tsx --test src/__tests__/*.test.ts"},"keywords":["accord-protocol","rails","ergo","ergoscript","agent-payments","rail-adapter"],"author":{"name":"bez111"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/accord-protocol/accord-protocol.git","directory":"packages/accord-rails-ergo"},"homepage":"https://accordprotocol.ai/learn/why-ergo-reference-rail/","bugs":{"url":"https://github.com/accord-protocol/accord-protocol/issues"},"dependencies":{"@accord-protocol/core":"^0.4.2","@accord-protocol/rails":"^0.4.2"},"peerDependencies":{"ergo-agent-pay":"^0.3.2"},"peerDependenciesMeta":{"ergo-agent-pay":{"optional":true}},"devDependencies":{"@types/node":"^20.0.0","tsup":"^8.0.0","tsx":"^4.0.0","typescript":"^5.0.0"},"engines":{"node":">=18"},"publishConfig":{"access":"public"},"gitHead":"437febb0a70b3162d4b10b19874f1a0026a59bdf","_id":"@accord-protocol/rails-ergo@0.4.2","_nodeVersion":"24.15.0","_npmVersion":"11.15.0","dist":{"integrity":"sha512-e52q0axfW3yN3M0QQXF3gjRjl58me+4kRENgKXzJdkISOn/qksuNBDNEyefW8TyfU/CSq6+xdm4h9v3zZWYnuw==","shasum":"812e04d51979daa964ecfb5984495d72b6675b7f","tarball":"https://registry.npmjs.org/@accord-protocol/rails-ergo/-/rails-ergo-0.4.2.tgz","fileCount":6,"unpackedSize":56491,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@accord-protocol%2frails-ergo@0.4.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBiaayiZnTERjyQVoLhIhEurUCA7J53b/qkO31k3/TdIAiEAye0bnE0bcRzA4YAoKHy1H1SLUM1jGKBto4QFp80YPKk="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:60c1c75d-10ff-49b1-b08a-a5b9b2a1cef9"}},"directories":{},"maintainers":[{"name":"accord-protocol","email":"alexander.bezkrovny@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/rails-ergo_0.4.2_1779582053787_0.7383093795082931"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-14T16:19:19.647Z","modified":"2026-05-24T00:20:54.220Z","0.4.0":"2026-05-14T16:19:19.868Z","0.4.1":"2026-05-15T19:21:43.372Z","0.4.2":"2026-05-24T00:20:53.931Z"},"bugs":{"url":"https://github.com/accord-protocol/accord-protocol/issues"},"author":{"name":"bez111"},"license":"MIT","homepage":"https://accordprotocol.ai/learn/why-ergo-reference-rail/","keywords":["accord-protocol","rails","ergo","ergoscript","agent-payments","rail-adapter"],"repository":{"type":"git","url":"git+https://github.com/accord-protocol/accord-protocol.git","directory":"packages/accord-rails-ergo"},"description":"Accord rail adapter for the Ergo Note primitive. verifyPayment fetches the Note from the chain, checks expiry / reserve binding / task-hash / value; settle calls redeemNote and emits a v0 Settlement Receipt with mode=note_redeemed.","maintainers":[{"name":"accord-protocol","email":"alexander.bezkrovny@gmail.com"}],"readme":"# `@accord-protocol/rails-ergo`\n\nAccord rail adapter for the **Ergo Note** primitive. Implements [`AccordRailAdapter`](../accord-rails) by reading a Note from the chain, checking expiry / reserve binding / task-hash / value, then redeeming it.\n\nPublic docs: [Website](https://accordprotocol.ai/) · [Why Ergo is the reference rail](https://accordprotocol.ai/learn/why-ergo-reference-rail/) · [Rail adapters](https://accordprotocol.ai/learn/rail-adapters/)\n\n## Install\n\n```bash\nnpm install @accord-protocol/rails-ergo @accord-protocol/rails @accord-protocol/core\n# plus the upstream Note SDK (peer dep):\nnpm install ergo-agent-pay\n```\n\n## Usage\n\n```ts\nimport { ErgoAgentPay } from \"ergo-agent-pay\";\nimport { createErgoRailAdapter } from \"@accord-protocol/rails-ergo\";\nimport { accordGateway } from \"@accord-protocol/gateway\";\n\nconst ergoAgent = new ErgoAgentPay({\n  address: process.env.SELLER_ERGO_ADDRESS!,\n  network: \"testnet\",\n  signer: mySigner,\n});\n\nconst rail = createErgoRailAdapter({ ops: ergoAgent });\n\napp.post(\"/api/run\", accordGateway({\n  rail,\n  resolveAgreement,\n  buildAgreementTemplate,\n  handler: async (req, { agreement, body }) => {\n    return { word_count: String(body?.text ?? \"\").split(/\\s+/).filter(Boolean).length };\n  },\n}));\n```\n\nThe adapter never touches `ergo-agent-pay` directly — it expects an `ErgoNoteOps` interface (`checkNote` + `redeemNote` + `network`). The `ErgoAgentPay` class is shape-compatible, so production code passes an instance; tests pass an in-memory stub.\n\n## Buyer payment-proof shape\n\nThe buyer's MCP / HTTP call sends:\n\n```json\n{\n  \"note_box_id\": \"<64 hex>\",\n  \"task_output\": \"{\\\"word_count\\\":2}\",\n  \"receiver_address\": \"9XSeller...\"\n}\n```\n\n`task_output` is the raw bytes the seller pre-committed to. `blake2b256(task_output)` MUST equal the Note's R6.\n\n## verifyPayment checks (in order)\n\n1. **Shape** — `note_box_id` is 64 hex, `task_output` present.\n2. **Note exists** on chain (rejection: `NOTE_NOT_FOUND`).\n3. **Not expired** (rejection: `NOTE_EXPIRED`).\n4. **Reserve binding** — `note.R4` matches `agreement.payment.reserve_ref` (rejection: `RESERVE_MISMATCH`).\n5. **Task-hash binding** — `note.R6` exists and equals `blake2b256(task_output)` (rejections: `TASK_HASH_MISSING`, `TASK_HASH_MISMATCH`).\n6. **Currency** — agreement asks for ERG (rejection: `CURRENCY_MISMATCH`; for rsUSDT/rsUSDC/rsBTC use `@accord-protocol/rails-rosen`, for USDC on Base use `@accord-protocol/rails-base`).\n7. **Value** — `note.value ≥ decimalToBaseUnits(price.amount, decimals)` (rejection: `INSUFFICIENT_VALUE`).\n\nOn success: `payment_id = note.boxId`. The wrapping layer (gateway / MCP) uses this for replay protection.\n\n## settle\n\nCalls `ops.redeemNote(...)` and emits a v0 Settlement Receipt:\n\n```json\n{\n  \"type\": \"accord.settlement_receipt.v0\",\n  \"version\": \"v0\",\n  \"rail\": \"ergo\",\n  \"mode\": \"note_redeemed\",\n  \"status\": \"settled\",\n  \"amount\": \"<agreement.price.amount>\",\n  \"currency\": \"ERG\",\n  \"decimals\": 9,\n  \"tx\": { \"network\": \"...\", \"tx_id\": \"...\", \"box_id\": \"...\" },\n  ...\n}\n```\n\nWhen `redeemNote` returns `submitted: false` (e.g. unsigned-tx flow), the receipt's `status` is `pending` instead of `settled`.\n\n## Error codes\n\n`ERGO_RAIL_ERROR_CODES`:\n\n```text\nINVALID_PAYMENT_SHAPE\nNOTE_NOT_FOUND\nNOTE_EXPIRED\nRESERVE_MISMATCH\nTASK_HASH_MISSING\nTASK_HASH_MISMATCH\nINSUFFICIENT_VALUE\nCURRENCY_MISMATCH\n```\n\n## What's NOT here\n\n- **Refunds.** Ergo Notes self-refund through the on-chain predicate: when the deadline passes without redemption, the value flows back to the issuer's reserve. There's nothing for the rail adapter to do.\n- **Ergo address parsing / NFT-id checks.** Bring your own validation if you don't trust the upstream `ErgoAgentPay`.\n- **Stablecoin rails** — `rails-rosen` (rsUSDT/rsUSDC/rsBTC) is a separate package even though it's still on the Ergo chain, because the value semantics + token-id checks differ.\n\n## License\n\nMIT.\n","readmeFilename":"README.md"}