Compare commits
4 Commits
feat/auto-
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
| 79a264da6a | |||
| 767ed80451 | |||
| 7dd0b7facb | |||
| 6b0bf3d57d |
18
README.md
18
README.md
@ -103,6 +103,19 @@ make run-demo # starts wal-backed ledger-core, auth, tenant-registry,
|
||||
./bin/tui # watch it live in a second terminal
|
||||
```
|
||||
|
||||
## NEAR Hackathon (Nov 1-14, 2026)
|
||||
|
||||
This submission anchors Ration's append-only, hash-chained audit trail to a
|
||||
NEAR smart contract we wrote and deployed ourselves, for the **AI Security &
|
||||
Defense** track at `nearhackathon.com`. See
|
||||
[`docs/near-hackathon/HACKATHON.md`](docs/near-hackathon/HACKATHON.md) for the
|
||||
submission writeup and run-it-yourself steps.
|
||||
|
||||
Same person, two separate entries: the owner of this repo is also submitting
|
||||
[Cred402](https://github.com/caelum0x/cred402) (Agent Economy track) to this
|
||||
same NEAR Hackathon — different repo, different NEAR Testnet contract, no
|
||||
shared code path.
|
||||
|
||||
## Airwallex mode
|
||||
|
||||
`AIRWALLEX_MODE=mock` (default) runs entirely against an in-process fake
|
||||
@ -149,3 +162,8 @@ never violate.
|
||||
## License
|
||||
|
||||
Apache-2.0 — see [LICENSE](LICENSE).
|
||||
## More from this account
|
||||
|
||||
- [Scribase](https://scribase.com) — hosted Postgres, one backend instead of stitching together Supabase + Neon + Clerk + Resend
|
||||
- [Toolgate](https://toolgate.scribase.com) — one key for agent tools, pay only for what you call
|
||||
- All repos: [git.ereboslab.com/caelum0x](https://git.ereboslab.com/caelum0x)
|
||||
|
||||
@ -7,12 +7,28 @@ independent — different repos, different NEAR Testnet contracts, no shared cod
|
||||
path — this note exists only to satisfy the hackathon's one-entrant/cross-reference
|
||||
expectation.
|
||||
|
||||
**🎬 Demo video:** [`media/near-demo-2026-11-10.mp4`](media/near-demo-2026-11-10.mp4) —
|
||||
a real, unedited recording of `near-anchor demo` run against a dedicated,
|
||||
freshly-deployed NEAR Testnet account (`ration-demo-23bd92e5.testnet`,
|
||||
created via the free public faucet). Shows two real audit-log records
|
||||
appended, the chain anchored on-chain, and the live on-chain anchor
|
||||
independently re-read and confirmed to match the local chain tip. Anchor tx:
|
||||
**🎬 Demo video (primary, submission-ready):** [`media/ration-near-demo-2026-11-11.mp4`](media/ration-near-demo-2026-11-11.mp4) —
|
||||
69.8s, 1920x1080, narrated (Deepgram Aura-2 TTS, burned-in captions,
|
||||
-14.5 LUFS / -1.9 dBTP). A real, unedited `near-anchor demo` run against
|
||||
a dedicated, freshly-deployed NEAR Testnet account
|
||||
(`ration-video-61849d567f.testnet`), **plus** an independent raw-RPC
|
||||
re-read and a deliberate replay attempt shown being rejected live
|
||||
on-chain — not just the append+anchor steps. Anchor tx:
|
||||
[`5YebAM2YRyoneabk8npkH3a8VnnevnLv9NLkBT5ome1t`](https://testnet.nearblocks.io/txns/5YebAM2YRyoneabk8npkH3a8VnnevnLv9NLkBT5ome1t);
|
||||
replay rejection tx:
|
||||
[`7v6m81jkbT2K5AjVBbDray9hXWVB2cHvTBWt3Uui469o`](https://testnet.nearblocks.io/txns/7v6m81jkbT2K5AjVBbDray9hXWVB2cHvTBWt3Uui469o)
|
||||
(failed on-chain exactly as intended — nearcore's own panic:
|
||||
*"sequence must strictly advance..."*). Pitch deck:
|
||||
[`PITCH-DECK.md`](PITCH-DECK.md) / `.pdf` / `.pptx` in this same
|
||||
directory.
|
||||
|
||||
**Earlier, shorter recording (kept, not deleted):** [`media/near-demo-2026-11-10.mp4`](media/near-demo-2026-11-10.mp4) —
|
||||
4.6s, a real, unedited recording of `near-anchor demo` run against a
|
||||
different dedicated, freshly-deployed NEAR Testnet account
|
||||
(`ration-demo-23bd92e5.testnet`, created via the free public faucet).
|
||||
Shows two real audit-log records appended, the chain anchored
|
||||
on-chain, and the live on-chain anchor independently re-read and
|
||||
confirmed to match the local chain tip. Anchor tx:
|
||||
[`z8GWsRVxDykJ55rTKgb4dbN9WTH1UGMzk4NhQfogFrt`](https://testnet.nearblocks.io/txns/z8GWsRVxDykJ55rTKgb4dbN9WTH1UGMzk4NhQfogFrt).
|
||||
(The repo's primary submission account/contract referenced elsewhere in this
|
||||
doc, `ration-anchor-286ca315f1.testnet`, is unchanged and separately live —
|
||||
|
||||
146
docs/near-hackathon/PITCH-DECK.md
Normal file
146
docs/near-hackathon/PITCH-DECK.md
Normal file
@ -0,0 +1,146 @@
|
||||
---
|
||||
marp: true
|
||||
theme: default
|
||||
paginate: true
|
||||
backgroundColor: "#0d1117"
|
||||
color: "#e6edf3"
|
||||
style: |
|
||||
section { font-family: -apple-system, 'Helvetica Neue', Arial, sans-serif; padding: 60px 70px; }
|
||||
h1 { color: #e6edf3; font-size: 44px; }
|
||||
h2 { color: #58a6ff; font-size: 30px; }
|
||||
a { color: #58a6ff; }
|
||||
code { background: #161b22; color: #7ee787; padding: 2px 8px; border-radius: 6px; }
|
||||
pre { background: #161b22; border: 1px solid #30363d; border-radius: 8px; }
|
||||
table { font-size: 22px; border-collapse: collapse; width: 100%; }
|
||||
th { background: #21262d; color: #e6edf3; border: 1px solid #30363d; padding: 10px 14px; text-align: left; }
|
||||
td { background: #0d1117; color: #e6edf3; border: 1px solid #30363d; padding: 10px 14px; }
|
||||
tr:nth-child(even) td { background: #11161d; }
|
||||
.kicker { color: #00ec97; letter-spacing: 4px; font-weight: 700; font-size: 18px; text-transform: uppercase; }
|
||||
footer { color: #6e7681; font-size: 16px; }
|
||||
footer: "Ration — NEAR Hackathon 2026 — AI Security & Defense"
|
||||
---
|
||||
|
||||
<!-- _paginate: false -->
|
||||
<span class="kicker">RATION — AUDIT ANCHOR</span>
|
||||
|
||||
# An AI agent just moved real money.
|
||||
## How do you know it wasn't tampered with afterward?
|
||||
|
||||
NEAR Hackathon 2026 — **AI Security & Defense** track ("Trust, but verify")
|
||||
`github.com/caelum0x/ration`
|
||||
|
||||
---
|
||||
|
||||
## The problem
|
||||
|
||||
- AI agents are increasingly trusted to **make real financial decisions** — bridge-funding, approvals, spend.
|
||||
- Every decision ends up in **somebody's database**. If that database can be edited, the "proof" of what the agent did is only as trustworthy as whoever operates it.
|
||||
- Today, a judge, an auditor, a regulator, or a counterparty has **no way to independently check** an AI agent's financial history without trusting the company that built it.
|
||||
|
||||
> Logging isn't proof. A log you can quietly edit isn't an audit trail — it's a story.
|
||||
|
||||
---
|
||||
|
||||
## Who actually has this problem
|
||||
|
||||
- **Fintechs and card-issuing platforms** running LLM-driven approval/decisioning loops (exactly where Ration lives today).
|
||||
- **Any AI-agent framework** that gives an agent spend authority — agent-commerce, autonomous procurement, agentic trading.
|
||||
- **Regulators and auditors** who are being asked to sign off on AI-operated money flows with no independent verification primitive.
|
||||
- **Counterparties** (banks, BaaS partners, card networks) who need proof an agent's decision trail wasn't rewritten after the fact.
|
||||
|
||||
---
|
||||
|
||||
## The solution
|
||||
|
||||
**Ration already runs AI agents inside a hard, deterministic spending envelope they can never override** — a real, running 11-service system (Rust ledger core + Go services).
|
||||
|
||||
Every agent decision was already journaled into `audit-log`: a genuine **append-only, hash-chained** trail, kept deliberately separate from the ledger's own write-ahead log.
|
||||
|
||||
**This submission anchors that chain's current tip on NEAR Testnet** — so *anyone*, not just Ration, can verify what the agent did, without ever touching Ration's own infrastructure.
|
||||
|
||||
---
|
||||
|
||||
## How it works
|
||||
|
||||
```
|
||||
agent / ledger-core audit-log (Go) NEAR Testnet
|
||||
─────────────────── ─────────────── ────────────
|
||||
financial decision ───► append-only hash chain
|
||||
sha256(prev_hash || record)
|
||||
│
|
||||
▼
|
||||
near-anchor commit ───────► audit_anchor (Rust/NEAR SDK)
|
||||
commit_anchor(seq, hash)
|
||||
├─ stores chain tip + history
|
||||
└─ rejects any sequence that
|
||||
doesn't strictly advance
|
||||
▲
|
||||
│
|
||||
near-anchor verify ◄─────── get_latest_anchor()
|
||||
(independent re-read, byte-for-byte compare)
|
||||
```
|
||||
|
||||
Hand-rolled Go NEAR transaction signer (Borsh + ed25519) — no maintained Go NEAR SDK exists — cross-checked byte-for-byte against `near-api-js`.
|
||||
|
||||
---
|
||||
|
||||
## Live proof — recorded today, not simulated
|
||||
|
||||
| Step | Real result |
|
||||
|---|---|
|
||||
| Append 2 real audit-log records | sequence advances, `VerifyChain` confirms intact |
|
||||
| Anchor the chain tip on NEAR Testnet | tx `5YebAM2YRyoneabk8npkH3a8VnnevnLv9NLkBT5ome1t` |
|
||||
| Independent raw-RPC re-read (not our own tool) | `EXPERIMENTAL_tx_status` → `SuccessValue`, matches local tip |
|
||||
| **Replay the same anchor again** | **nearcore itself rejects it**: *"sequence must strictly advance past the last anchored sequence"* |
|
||||
|
||||
Full unedited recording: `docs/near-hackathon/media/ration-near-demo-2026-11-11.mp4`
|
||||
Primary submission account separately live: `ration-anchor-286ca315f1.testnet` (3 real anchors, 1 rejected replay, see `HACKATHON.md`)
|
||||
|
||||
---
|
||||
|
||||
## Why this fits the track
|
||||
|
||||
**Track: AI Security & Defense — "Trust, but verify."**
|
||||
Ration gives an AI agent money *and* a hard, external, independently-checkable record of what it did with it — literally the track's own framing.
|
||||
|
||||
The hackathon's own FAQ states projects are evaluated on **technical implementation, design, impact, originality and sustainability** — mapped explicitly on the next slide.
|
||||
|
||||
---
|
||||
|
||||
## ...and the judging criteria
|
||||
|
||||
- **Technical implementation** — real contract, real signer, 5/5 Rust + Go tests, 4 real on-chain transactions this submission, zero regressions (15/15 ledger-core, full `go test ./... -race`).
|
||||
- **Design** — audit-log kept deliberately separate from ledger-core's own WAL; anchoring is additive, not a rewrite.
|
||||
- **Impact** — a reusable trust primitive for *any* AI-agent-with-money system, not Ration-specific.
|
||||
- **Originality** — not a payment rail; a verification layer, with a provably-enforced replay guard.
|
||||
- **Sustainability** — ships as a standalone CLI (`near-anchor`) today; wiring it into the agent's own poll loop is one small, obvious next step.
|
||||
|
||||
---
|
||||
|
||||
## Traction — honest
|
||||
|
||||
- **$0 revenue, pre-revenue infrastructure.** Ration is a real, running fiat-ledger + AI-agent platform (11 services, Rust + Go) already live for development/testing — not a hackathon-only demo app.
|
||||
- This submission is a **focused add-on**: one new capability (on-chain anchoring), not a rewrite.
|
||||
- No mainnet transactions, no claimed users of the anchor feature yet — Testnet only, exactly as the evidence above shows.
|
||||
- What's *not* done, on purpose: automatic periodic anchoring isn't wired into the agent's poll loop yet (manual/cron-invoked today) — scoped out to keep this submission honest about what was built and tested under the deadline.
|
||||
|
||||
---
|
||||
|
||||
## Roadmap
|
||||
|
||||
- **Next 2 weeks:** wire `near-anchor commit` into `services/agent`'s own poll loop (periodic, not manual) — the one concrete gap called out above.
|
||||
- **Next month:** per-tenant anchor namespacing (today: one global chain tip per contract); mainnet deployment path.
|
||||
- **Ongoing:** publish the Go NEAR signer as a standalone open-source package — no maintained Go NEAR SDK currently exists.
|
||||
|
||||
---
|
||||
|
||||
## Team & links
|
||||
|
||||
**Arhan Subaşı** (GitHub: [`caelum0x`](https://github.com/caelum0x)) — solo founder/engineer. Builds production infrastructure: distributed systems, payment ledgers, and now AI-agent safety rails.
|
||||
|
||||
- Repo: **github.com/caelum0x/ration**
|
||||
- Full writeup: `docs/near-hackathon/HACKATHON.md`
|
||||
- Demo video: `docs/near-hackathon/media/ration-near-demo-2026-11-11.mp4`
|
||||
- Sibling entry, same hackathon: [Cred402 — SpendGuard](https://github.com/caelum0x/cred402) (Agent Economy track)
|
||||
|
||||
**Thank you — questions welcome.**
|
||||
BIN
docs/near-hackathon/PITCH-DECK.pdf
Normal file
BIN
docs/near-hackathon/PITCH-DECK.pdf
Normal file
Binary file not shown.
BIN
docs/near-hackathon/PITCH-DECK.pptx
Normal file
BIN
docs/near-hackathon/PITCH-DECK.pptx
Normal file
Binary file not shown.
@ -1,4 +1,4 @@
|
||||
# NEAR Hackathon submission checklist (dev deadline Nov 14 2026 23:59 UTC, judging Nov 16-18)
|
||||
# NEAR Hackathon submission checklist (dev deadline Nov 14 2026 23:59 UTC, results by Nov 18 2026 23:59 UTC)
|
||||
|
||||
Code, contract, tests, and docs are done and verified live on NEAR
|
||||
Testnet. What's left is short and owner-only (identity + a social post +
|
||||
@ -59,7 +59,24 @@ checklist for the same hackathon.
|
||||
account/contract id and every transaction hash above, and
|
||||
`plans/INDEX.md` updated to point at it.
|
||||
|
||||
## Done (demo video, added 2026-11-10)
|
||||
## Done (demo video + pitch deck, added 2026-11-11)
|
||||
|
||||
- [x] **Primary submission demo video, narrated** — 69.8s, 1920x1080,
|
||||
Deepgram Aura-2 narration with burned-in captions
|
||||
(-14.5 LUFS / -1.9 dBTP), built entirely from real captures: a
|
||||
real `near-anchor demo` run plus a raw-RPC re-read plus a
|
||||
deliberate replay attempt shown being rejected live on-chain
|
||||
(not just append+anchor). Committed:
|
||||
[`media/ration-near-demo-2026-11-11.mp4`](media/ration-near-demo-2026-11-11.mp4)
|
||||
(+ `.cast`). Anchor tx `5YebAM2YRyoneabk8npkH3a8VnnevnLv9NLkBT5ome1t`;
|
||||
replay-rejection tx `7v6m81jkbT2K5AjVBbDray9hXWVB2cHvTBWt3Uui469o`.
|
||||
Full detail in `HACKATHON.md`'s "🎬 Demo video" line.
|
||||
- [x] **Pitch deck** — `PITCH-DECK.md` (Marp), exported to
|
||||
`PITCH-DECK.pdf` and `PITCH-DECK.pptx`, 11 slides covering
|
||||
problem/market/solution/architecture/live proof/track fit +
|
||||
judging-criteria mapping/honest traction/roadmap/team/links.
|
||||
|
||||
## Done (earlier demo video, added 2026-11-10 — kept, not deleted)
|
||||
|
||||
- [x] **Demo video recorded** — a real, unedited `near-anchor demo` run
|
||||
(`asciinema` + `agg` + `ffmpeg`, same tooling cred402 used for its
|
||||
@ -71,8 +88,9 @@ checklist for the same hackathon.
|
||||
raw `EXPERIMENTAL_tx_status` RPC call outside the tool itself.
|
||||
Committed: [`media/near-demo-2026-11-10.mp4`](media/near-demo-2026-11-10.mp4)
|
||||
(+ `.gif`/`.cast`), commit `da8f906`. Anchor tx:
|
||||
`z8GWsRVxDykJ55rTKgb4dbN9WTH1UGMzk4NhQfogFrt`. Full detail in
|
||||
`HACKATHON.md`'s "🎬 Demo video" line.
|
||||
`z8GWsRVxDykJ55rTKgb4dbN9WTH1UGMzk4NhQfogFrt`. Superseded as the
|
||||
primary attachment by the narrated video above, but kept as a
|
||||
shorter alternate.
|
||||
|
||||
## Owner-only (fill in before submitting)
|
||||
|
||||
|
||||
@ -25,8 +25,8 @@ tampered with.
|
||||
This clip is a real, unedited terminal session: two real audit-log
|
||||
records appended, anchored on-chain against a live NEAR Testnet
|
||||
contract, then independently re-read via raw RPC to confirm the match.
|
||||
We also deliberately tried replaying an already-anchored sequence on a
|
||||
sibling contract — nearcore itself rejected it on-chain.
|
||||
We also deliberately tried replaying an already-anchored sequence on
|
||||
the same contract — nearcore itself rejected it on-chain.
|
||||
|
||||
@NEARProtocol #NEARHackathon
|
||||
|
||||
|
||||
15
docs/near-hackathon/media/near-demo-2026-11-11.cast
Normal file
15
docs/near-hackathon/media/near-demo-2026-11-11.cast
Normal file
@ -0,0 +1,15 @@
|
||||
{"version":3,"term":{"cols":104,"rows":26},"timestamp":1794347199,"command":"bash /tmp/ration-video-build/record_demo.sh","env":{"SHELL":"/bin/zsh"}}
|
||||
[0.009, "o", "\u001b[3J\u001b[H\u001b[2J"]
|
||||
[0.000, "o", "$ near-anchor demo\r\n"]
|
||||
[1.529, "o", "[1/4] appending two real records to the audit-log chain at /tmp/ration-video-dryrun-data/audit.log ...\r\n"]
|
||||
[0.005, "o", " appended AgentDecision: sequence=5 hash=a0878e47be6a6eafac15ec0c65e28e410baff24c01af33c32776dcd586d8f8a1\r\n"]
|
||||
[0.003, "o", " appended LedgerEntry: sequence=6 hash=a7545efedefccc1b9882e36b9fe832d2c96e20d17dd533164d8ac6c113955389\r\n[2/4] local chain integrity: intact=true records_checked=6, tip is now sequence=6 hash=a7545efedefccc1b9882e36b9fe832d2c96e20d17dd533164d8ac6c113955389\r\n"]
|
||||
[0.000, "o", "[3/4] anchoring sequence=6 hash=a7545efedefccc1b9882e36b9fe832d2c96e20d17dd533164d8ac6c113955389 on NEAR Testnet (contract ration-video-61849d567f.testnet) ...\r\n"]
|
||||
[1.565, "o", " committed. tx=5YebAM2YRyoneabk8npkH3a8VnnevnLv9NLkBT5ome1t\r\n https://testnet.nearblocks.io/txns/5YebAM2YRyoneabk8npkH3a8VnnevnLv9NLkBT5ome1t\r\n[4/4] independently re-reading the local chain tip and the live on-chain anchor to confirm they match ...\r\n"]
|
||||
[0.093, "o", " on-chain anchor matches the real local chain tip\r\n\r\nnear-anchor demo: PASSED — a real audit-log entry was written, the hash chain advanced, the anchor transaction was confirmed on NEAR Testnet, and the on-chain stored hash matches the real local chain tip.\r\n"]
|
||||
[6.017, "o", "\r\n$ curl https://rpc.testnet.fastnear.com # raw NEAR RPC, independent of our own tool\r\n"]
|
||||
[1.123, "o", " independent RPC response (not our tool):\r\n {\"tenant_id\":\"tenant-near-hackathon-demo\",\"chain_tip_hash\":\"a7545efedefccc1b9882e36b9fe832d2c96e20d17dd533164d8ac6c113955389\",\"sequence\":6,\"occurred_at_unix\":1794347200,\"anchored_at_block_timestamp\":1794347201577590715}\r\n"]
|
||||
[8.520, "o", "\r\n$ near-anchor commit # replay the SAME anchor again -- no new records appended\r\n"]
|
||||
[1.024, "o", "near-anchor: local chain tip is sequence=6 hash=a7545efedefccc1b9882e36b9fe832d2c96e20d17dd533164d8ac6c113955389 tenant=tenant-near-hackathon-demo\r\n"]
|
||||
[1.588, "o", "near-anchor commit: nearanchor: broadcast commit_anchor: nearanchor: transaction 7v6m81jkbT2K5AjVBbDray9hXWVB2cHvTBWt3Uui469o failed on-chain: {\"ActionError\":{\"index\":0,\"kind\":{\"FunctionCallError\":{\"ExecutionError\":\"Smart contract panicked: audit_anchor: sequence must strictly advance past the last anchored sequence (stale or replayed anchor rejected)\"}}}}\r\n"]
|
||||
[6.023, "x", "0"]
|
||||
BIN
docs/near-hackathon/media/ration-near-demo-2026-11-11.mp4
Normal file
BIN
docs/near-hackathon/media/ration-near-demo-2026-11-11.mp4
Normal file
Binary file not shown.
136
docs/soonami/PITCH-DECK.md
Normal file
136
docs/soonami/PITCH-DECK.md
Normal file
@ -0,0 +1,136 @@
|
||||
---
|
||||
marp: true
|
||||
theme: default
|
||||
paginate: true
|
||||
backgroundColor: "#0d1117"
|
||||
color: "#e6edf3"
|
||||
style: |
|
||||
section { font-family: -apple-system, 'Helvetica Neue', Arial, sans-serif; padding: 60px 70px; }
|
||||
h1 { color: #e6edf3; font-size: 44px; }
|
||||
h2 { color: #58a6ff; font-size: 30px; }
|
||||
a { color: #58a6ff; }
|
||||
code { background: #161b22; color: #7ee787; padding: 2px 8px; border-radius: 6px; }
|
||||
pre { background: #161b22; border: 1px solid #30363d; border-radius: 8px; }
|
||||
table { font-size: 22px; border-collapse: collapse; width: 100%; }
|
||||
th { background: #21262d; color: #e6edf3; border: 1px solid #30363d; padding: 10px 14px; text-align: left; }
|
||||
td { background: #0d1117; color: #e6edf3; border: 1px solid #30363d; padding: 10px 14px; }
|
||||
tr:nth-child(even) td { background: #11161d; }
|
||||
.kicker { color: #00ec97; letter-spacing: 4px; font-weight: 700; font-size: 18px; text-transform: uppercase; }
|
||||
.warn { color: #f0883e; font-weight: 700; }
|
||||
footer { color: #6e7681; font-size: 16px; }
|
||||
footer: "Ration — soonami Venturethon 11 — On the Fast Track"
|
||||
---
|
||||
|
||||
<!-- _paginate: false -->
|
||||
<span class="kicker">RATION</span>
|
||||
|
||||
# Deterministic safety rails for AI agents with money.
|
||||
|
||||
soonami **Venturethon 11** (with KPMG) — **"On the Fast Track"**
|
||||
`github.com/caelum0x/ration`
|
||||
|
||||
---
|
||||
|
||||
## The problem
|
||||
|
||||
AI agents are getting **real spending authority** — approving refunds, funding cards against expected deposits, moving money between accounts — faster than anyone has built a trust layer for it.
|
||||
|
||||
Every team in this space runs into the same question:
|
||||
|
||||
> **"Who proves the agent didn't exceed what it was allowed to do — and can that proof be checked by someone who isn't the vendor?"**
|
||||
|
||||
Today's answer is almost always: **"we log it, trust us."**
|
||||
|
||||
---
|
||||
|
||||
## Who has this problem (the market)
|
||||
|
||||
- **Fintechs & card-issuing platforms** running LLM-driven approval/decisioning loops — Ration's own home turf today.
|
||||
- **Agent-commerce and agent-economy platforms** giving agents wallets, procurement authority, or negotiation power.
|
||||
- **Auditors, regulators, and BaaS/bank partners** being asked to sign off on AI-operated money flows with no independent verification primitive.
|
||||
- **KPMG's own lens on this problem** — audit and assurance for systems nobody can fully black-box trust — is exactly the gap Ration closes.
|
||||
|
||||
---
|
||||
|
||||
## The product
|
||||
|
||||
**Ration: a deterministic rule envelope an LLM can never override, plus a tamper-evident, independently-verifiable audit trail.**
|
||||
|
||||
- Every money-moving decision is re-verified **three separate times** (agent → card-issuance → ledger-core) before it's allowed to happen.
|
||||
- Journaled through a crash-safe write-ahead log, mirrored into a separate, **append-only, hash-chained** audit trail.
|
||||
- That chain's tip is anchored to a **real NEAR Testnet smart contract** we wrote and deployed — so anyone, not just us, can verify the trail wasn't tampered with.
|
||||
- A real, running **11-service system** (Rust ledger core + Go services) — not a hackathon-only demo app.
|
||||
|
||||
---
|
||||
|
||||
## Proof — verifiable right now, not a slide
|
||||
|
||||
| Claim | Evidence |
|
||||
|---|---|
|
||||
| Deployed, correct NEAR contract | `code_hash` independently re-read via raw RPC, matches our build exactly |
|
||||
| 3 real on-chain anchor commits | each independently re-confirmed via `EXPERIMENTAL_tx_status`, not just our own tooling |
|
||||
| Replay/tamper guard enforced **by the chain**, not our code | deliberate replay attempt rejected on-chain: *"sequence must strictly advance..."* |
|
||||
| Zero regressions | 15/15 ledger-core tests, full `go test ./... -race` clean, 9 new NEAR integration tests |
|
||||
| Judge can run it live, not just watch a recording | one command: `near-anchor demo` — recorded run already in the public repo |
|
||||
|
||||
Built to **two independent external rubrics**: Airwallex's Agentic Banking Hackathon (original build) and NEAR's AI Security & Defense track — not self-graded.
|
||||
|
||||
---
|
||||
|
||||
## Business model (hypothesis — not yet priced)
|
||||
|
||||
Ration is infrastructure, not an app — the buyer is **any platform that is about to give an AI agent spending authority**:
|
||||
|
||||
- **Verification-as-a-service**: usage-based pricing per anchored audit event, for platforms that want a third-party-checkable trust primitive without building one.
|
||||
- **Licensed deterministic-envelope engine**: embed Ration's rule-envelope + audit core directly into a fintech's or agent platform's own stack.
|
||||
- **Open-source top-of-funnel**: the hand-rolled Go NEAR signer (no maintained SDK exists) ships as a standalone open-source package — a credible, developer-first way to reach the exact platforms above.
|
||||
|
||||
Honest flag: **no pricing has been tested with a real customer yet.** This is a hypothesis to validate, not a confirmed model.
|
||||
|
||||
---
|
||||
|
||||
## Go-to-market
|
||||
|
||||
- **Lineage, not a cold start**: born at Airwallex's Agentic Banking Hackathon, hardened across 21+ real iteration rounds since — not a weekend demo left untouched.
|
||||
- **Outbound to fintechs and agent-platform teams** already shipping LLM-driven money decisions (the exact audience in "Who has this problem").
|
||||
- **Open-source the Go NEAR signer** as a developer-facing distribution channel into the NEAR/Web3 developer base.
|
||||
- **Hackathon rubric validation as credibility signal**: two independent external judging processes (Airwallex, NEAR) as proof points in outbound conversations.
|
||||
|
||||
---
|
||||
|
||||
## Traction — honest
|
||||
|
||||
- **$0 revenue, 0 paying customers today.**
|
||||
- What exists instead of a revenue chart: **tech a panel can verify themselves, live** — real public repo, real on-chain transactions, a real one-command judge-facing demo.
|
||||
- What's genuinely still missing: no production customers, no scheduled/automatic on-chain anchoring yet (today a manually-invoked tool, not wired into the live agent loop), no mainnet transaction — hardened infrastructure proven on Testnet, not a commercial product yet.
|
||||
- That gap — proven safety primitive → sellable product — is exactly what this sprint is for.
|
||||
|
||||
---
|
||||
|
||||
## The ask — what the 10-day sprint delivers
|
||||
|
||||
Per soonami's own rules (a genuinely **new** feature, not a restated NEAR-hackathon submission):
|
||||
|
||||
1. **Wire `near-anchor` into the live agent loop** as a scheduled, automatic anchoring job — today it's a manually-invoked CLI command, not triggered by the system itself.
|
||||
2. **A judge-facing live dashboard** showing real-time anchor status, that lets a reviewer **trigger a tamper attempt themselves** and watch nearcore reject it live — instead of only watching a recorded run.
|
||||
3. Validate the business-model hypothesis above with at least one real outbound conversation with a fintech/agent-platform team.
|
||||
|
||||
---
|
||||
|
||||
## Team
|
||||
|
||||
**Arhan Subaşı** (GitHub: [`caelum0x`](https://github.com/caelum0x)) — solo founder/engineer. Builds production infrastructure: distributed systems, payment ledgers, AI-agent safety rails.
|
||||
|
||||
<span class="warn">soonami's rules require at least 2 co-founders per team ("no 1-person teams").</span>
|
||||
**Co-founder: [PLACEHOLDER — not yet recruited].** This is a real, open gap — not filled with an invented name. Recruiting a real co-founder/teammate (via Foundance's "create a Role" feature, or soonami's Discord) is an explicit prerequisite before this submission is eligible, and is tracked as an owner-only action, not a doc-fixable one.
|
||||
|
||||
---
|
||||
|
||||
## Links
|
||||
|
||||
- Repo: **github.com/caelum0x/ration**
|
||||
- Track: **On the Fast Track** (existing venture, not a new idea formed during this event)
|
||||
- Demo video (same recording used for the NEAR Hackathon submission): `docs/near-hackathon/media/ration-near-demo-2026-11-11.mp4`
|
||||
- Full technical writeup: `docs/near-hackathon/HACKATHON.md`
|
||||
|
||||
**Thank you — questions welcome.**
|
||||
BIN
docs/soonami/PITCH-DECK.pdf
Normal file
BIN
docs/soonami/PITCH-DECK.pdf
Normal file
Binary file not shown.
BIN
docs/soonami/PITCH-DECK.pptx
Normal file
BIN
docs/soonami/PITCH-DECK.pptx
Normal file
Binary file not shown.
@ -17,13 +17,6 @@
|
||||
// initialize it (one transaction)
|
||||
// near-anchor commit read the real local audit-log chain
|
||||
// tip and anchor it on-chain
|
||||
// near-anchor schedule long-running: repeat `commit`'s
|
||||
// decide-then-anchor logic on a fixed
|
||||
// interval (RATION_NEAR_ANCHOR_INTERVAL,
|
||||
// default 5m) forever, skipping ticks
|
||||
// where nothing new has been appended
|
||||
// since the last on-chain anchor — see
|
||||
// internal/nearanchor/scheduler.go
|
||||
// near-anchor verify compare the real local chain tip
|
||||
// against what is currently anchored
|
||||
// on-chain and report match/mismatch
|
||||
@ -46,8 +39,6 @@ import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"os"
|
||||
"os/signal"
|
||||
"syscall"
|
||||
"time"
|
||||
|
||||
"github.com/caelum0x/ration/services/audit-log/internal/nearanchor"
|
||||
@ -73,8 +64,6 @@ func run(args []string) int {
|
||||
return cmdDeploy(ctx, args[1:])
|
||||
case "commit":
|
||||
return cmdCommit(ctx)
|
||||
case "schedule":
|
||||
return cmdSchedule(ctx)
|
||||
case "verify":
|
||||
return cmdVerify(ctx)
|
||||
case "demo":
|
||||
@ -95,10 +84,6 @@ Subcommands:
|
||||
deploy <wasm> deploy contracts-near/audit_anchor's wasm to the
|
||||
signer account and initialize it
|
||||
commit anchor the real local audit-log chain tip on-chain
|
||||
schedule long-running: repeat commit's decide-then-anchor
|
||||
logic every RATION_NEAR_ANCHOR_INTERVAL (default 5m)
|
||||
until SIGINT/SIGTERM, skipping ticks where nothing
|
||||
new has been appended since the last anchor
|
||||
verify compare the local chain tip against what is
|
||||
currently anchored on-chain
|
||||
demo append two real audit-log records, anchor the real
|
||||
@ -223,35 +208,6 @@ func cmdCommit(ctx context.Context) int {
|
||||
return 0
|
||||
}
|
||||
|
||||
// cmdSchedule runs the auto-anchoring loop (internal/nearanchor's
|
||||
// RunScheduler) until the process receives SIGINT or SIGTERM, at which
|
||||
// point signal.NotifyContext cancels ctx and RunScheduler returns
|
||||
// cleanly after finishing (not aborting mid-flight) whatever tick is
|
||||
// currently in progress. This is the real fix for the "anchoring is
|
||||
// manual" gap: instead of an operator remembering to run `near-anchor
|
||||
// commit` by hand, this runs unattended, batching however many new
|
||||
// audit-log records have landed since the last tick into exactly one
|
||||
// anchor transaction, and doing nothing (not even a failed on-chain
|
||||
// call) on a tick where nothing changed.
|
||||
func cmdSchedule(ctx context.Context) int {
|
||||
cfg, err := nearanchor.LoadForCommit()
|
||||
if err != nil {
|
||||
fmt.Fprintf(os.Stderr, "near-anchor schedule: %v\n", err)
|
||||
return 1
|
||||
}
|
||||
|
||||
ctx, stop := signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM)
|
||||
defer stop()
|
||||
|
||||
interval := nearanchor.ScheduleInterval()
|
||||
rpc := nearanchor.NewRPCClient(cfg.RPCURL)
|
||||
if err := nearanchor.RunScheduler(ctx, cfg, rpc, interval, os.Stdout); err != nil {
|
||||
fmt.Fprintf(os.Stderr, "near-anchor schedule: %v\n", err)
|
||||
return 1
|
||||
}
|
||||
return 0
|
||||
}
|
||||
|
||||
func cmdVerify(ctx context.Context) int {
|
||||
cfg, err := nearanchor.LoadForCommit()
|
||||
if err != nil {
|
||||
|
||||
@ -3,7 +3,6 @@ package nearanchor
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"time"
|
||||
)
|
||||
|
||||
// defaultFunctionCallGas is 100 Tgas — nearcore's own convention for a
|
||||
@ -68,21 +67,3 @@ func getenvDefault(key, def string) string {
|
||||
}
|
||||
return def
|
||||
}
|
||||
|
||||
// ScheduleInterval reads RATION_NEAR_ANCHOR_INTERVAL as a Go duration
|
||||
// string (e.g. "5m", "30s", "1h") for `near-anchor schedule`, falling
|
||||
// back to DefaultScheduleInterval if it is unset, empty, unparsable, or
|
||||
// non-positive — a scheduler should never start with a zero or
|
||||
// negative tick interval, since that would spin as fast as the RPC
|
||||
// round-trip allows instead of waiting at all.
|
||||
func ScheduleInterval() time.Duration {
|
||||
v := os.Getenv("RATION_NEAR_ANCHOR_INTERVAL")
|
||||
if v == "" {
|
||||
return DefaultScheduleInterval
|
||||
}
|
||||
d, err := time.ParseDuration(v)
|
||||
if err != nil || d <= 0 {
|
||||
return DefaultScheduleInterval
|
||||
}
|
||||
return d
|
||||
}
|
||||
|
||||
@ -1,179 +0,0 @@
|
||||
// Scheduler support for near-anchor: the auto-anchoring loop that
|
||||
// turns the previously-manual "run `near-anchor commit` by hand
|
||||
// whenever you remember to" workflow into an unattended, interval-based
|
||||
// background job (see cmd/near-anchor's `schedule` subcommand).
|
||||
//
|
||||
// Design choices worth stating plainly, since they're the actual
|
||||
// answer to "batch, idempotent, skip-when-nothing-new, survives
|
||||
// restarts" rather than something bolted on after the fact:
|
||||
//
|
||||
// - "Batch" is structural, not a buffer this package manages: because
|
||||
// every record is hash-chained to the one before it
|
||||
// (services/audit-log/internal/store), anchoring the *current tip*
|
||||
// already cryptographically commits to every record appended since
|
||||
// the last anchor, no matter how many there were. A tick that fires
|
||||
// after 50 new audit-log records still does exactly one
|
||||
// commit_anchor call, and that one anchor is just as strong a proof
|
||||
// for all 50 as 50 separate anchors would have been. There is
|
||||
// nothing to batch in memory — the chain itself already is the
|
||||
// batch.
|
||||
// - Idempotency and "skip when nothing new" are the same check: before
|
||||
// ever signing a transaction, RunOnce reads the contract's own
|
||||
// get_latest_anchor() (a free view call) and only calls CommitAnchor
|
||||
// if the local chain has advanced past what is already anchored.
|
||||
// This also means two schedulers (or a human running `near-anchor
|
||||
// commit` by hand) can never double-anchor the same sequence —
|
||||
// contracts-near/audit_anchor's own `sequence > prev.sequence` guard
|
||||
// would reject it on-chain even if this check were skipped, so the
|
||||
// Go-side check is a courtesy that avoids a wasted/failing
|
||||
// transaction, not the only line of defense.
|
||||
// - "Survives restarts" needs no local checkpoint file at all: the
|
||||
// scheduler's only state is "what does the chain say right now?",
|
||||
// read fresh from the local audit-log file and the live contract on
|
||||
// every tick (including the very first tick after a restart). A
|
||||
// crash between deciding to commit and the transaction landing is
|
||||
// safe too — on restart, the next tick re-asks the chain, and
|
||||
// either the transaction never made it (so it anchors now) or it
|
||||
// did (so the on-chain sequence already matches and it skips).
|
||||
package nearanchor
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"io"
|
||||
"time"
|
||||
|
||||
"github.com/caelum0x/ration/services/audit-log/internal/store"
|
||||
)
|
||||
|
||||
// DefaultScheduleInterval is how often `near-anchor schedule` checks
|
||||
// for new records when RATION_NEAR_ANCHOR_INTERVAL is unset. Five
|
||||
// minutes is frequent enough that a judge or operator watching the
|
||||
// on-chain anchor count doesn't wait long to see it move, without
|
||||
// spamming NEAR Testnet RPC/gas on an idle chain (a tick where nothing
|
||||
// is new costs exactly one free view call, never a transaction).
|
||||
const DefaultScheduleInterval = 5 * time.Minute
|
||||
|
||||
// decideAnchor is the pure decision rule RunOnce applies: given the
|
||||
// real local chain tip and whatever is currently anchored on-chain,
|
||||
// should this tick submit a new anchor transaction, or skip because
|
||||
// nothing has happened since the last anchor? Split out from RunOnce
|
||||
// (which also has to make two network calls) so the actual rule this
|
||||
// scheduler promises — "idempotent, skip when nothing new" — has a
|
||||
// plain table-driven unit test that needs no network and no testnet
|
||||
// credentials.
|
||||
func decideAnchor(local store.Record, onChain AnchorRecord) (shouldCommit bool, reason string) {
|
||||
if onChain.Sequence == 0 && onChain.ChainTipHash == "" {
|
||||
return true, "nothing anchored on-chain yet"
|
||||
}
|
||||
if local.Sequence <= int64(onChain.Sequence) {
|
||||
return false, fmt.Sprintf(
|
||||
"local tip sequence=%d is not ahead of the on-chain anchor sequence=%d — nothing new to anchor",
|
||||
local.Sequence, onChain.Sequence)
|
||||
}
|
||||
return true, fmt.Sprintf(
|
||||
"local tip sequence=%d is ahead of the on-chain anchor sequence=%d",
|
||||
local.Sequence, onChain.Sequence)
|
||||
}
|
||||
|
||||
// TickResult is what one RunOnce call decided and (if it committed)
|
||||
// did.
|
||||
type TickResult struct {
|
||||
Committed bool
|
||||
Reason string
|
||||
Local store.Record // zero value if there were no local records at all
|
||||
HadLocal bool
|
||||
Commit CommitResult // zero value unless Committed
|
||||
}
|
||||
|
||||
// RunOnce performs exactly one scheduler tick: read the real local
|
||||
// chain tip, read the real on-chain latest anchor (a free view call,
|
||||
// no gas, no transaction), apply decideAnchor, and — only if it says
|
||||
// to — sign and submit exactly one commit_anchor transaction for the
|
||||
// current tip. Safe to call repeatedly and concurrently with a human
|
||||
// running `near-anchor commit`/`verify` by hand: it never anchors a
|
||||
// sequence that is already on-chain, and relies on nothing but what it
|
||||
// reads fresh on every call (see this file's package-level doc comment
|
||||
// for why that's what makes the scheduler restart-safe with zero
|
||||
// checkpoint state of its own).
|
||||
func RunOnce(ctx context.Context, cfg Config, rpc *RPCClient) (TickResult, error) {
|
||||
path := cfg.AuditLogPath
|
||||
if path == "" {
|
||||
path = cfg.DataDir + "/audit.log"
|
||||
}
|
||||
|
||||
local, ok, err := store.ReadTip(path)
|
||||
if err != nil {
|
||||
return TickResult{}, fmt.Errorf("nearanchor: read local tip: %w", err)
|
||||
}
|
||||
if !ok {
|
||||
return TickResult{Committed: false, Reason: "no local audit-log records yet"}, nil
|
||||
}
|
||||
|
||||
var onChain AnchorRecord
|
||||
if err := rpc.CallFunctionView(ctx, cfg.ContractID, "get_latest_anchor", map[string]string{}, &onChain); err != nil {
|
||||
return TickResult{}, fmt.Errorf("nearanchor: read on-chain latest anchor: %w", err)
|
||||
}
|
||||
|
||||
should, reason := decideAnchor(local, onChain)
|
||||
if !should {
|
||||
return TickResult{Committed: false, Reason: reason, Local: local, HadLocal: true}, nil
|
||||
}
|
||||
|
||||
result, err := CommitAnchor(ctx, cfg, rpc, local)
|
||||
if err != nil {
|
||||
return TickResult{}, fmt.Errorf("nearanchor: commit anchor for sequence=%d: %w", local.Sequence, err)
|
||||
}
|
||||
|
||||
return TickResult{Committed: true, Reason: reason, Local: local, HadLocal: true, Commit: result}, nil
|
||||
}
|
||||
|
||||
// RunScheduler runs RunOnce immediately and then on every tick of
|
||||
// interval until ctx is cancelled, writing a one-line outcome for each
|
||||
// tick to out. It never returns on a tick-level error (a transient RPC
|
||||
// hiccup, or losing a race against another anchoring process) — those
|
||||
// are logged and the loop keeps going, because an unattended scheduler
|
||||
// that exits on the first flaky RPC call is strictly worse than one
|
||||
// that logs and retries next interval. It only returns when ctx is
|
||||
// cancelled (nil error) — the caller (cmd/near-anchor's `schedule`
|
||||
// subcommand) wires ctx to SIGINT/SIGTERM so the process shuts down
|
||||
// cleanly instead of being killed mid-transaction.
|
||||
func RunScheduler(ctx context.Context, cfg Config, rpc *RPCClient, interval time.Duration, out io.Writer) error {
|
||||
fmt.Fprintf(out, "near-anchor schedule: starting, interval=%s contract=%s signer=%s\n",
|
||||
interval, cfg.ContractID, cfg.SignerAccountID)
|
||||
|
||||
tick := func() {
|
||||
result, err := RunOnce(ctx, cfg, rpc)
|
||||
if err != nil {
|
||||
fmt.Fprintf(out, "near-anchor schedule: tick error (will retry next interval): %v\n", err)
|
||||
return
|
||||
}
|
||||
if result.Committed {
|
||||
fmt.Fprintf(out, "near-anchor schedule: anchored sequence=%d hash=%s tx=%s %s\n",
|
||||
result.Local.Sequence, result.Local.Hash, result.Commit.TransactionHash, result.Commit.ExplorerURL)
|
||||
return
|
||||
}
|
||||
fmt.Fprintf(out, "near-anchor schedule: skipped — %s\n", result.Reason)
|
||||
}
|
||||
|
||||
// Run once immediately on start, not just after the first
|
||||
// interval elapses — after a restart (or on first launch) there
|
||||
// may already be a batch of unanchored records waiting, and
|
||||
// nothing should sit for a full interval before that gets picked
|
||||
// up. decideAnchor's idempotency check makes this safe to do
|
||||
// unconditionally: if there's genuinely nothing new, this call
|
||||
// just skips.
|
||||
tick()
|
||||
|
||||
ticker := time.NewTicker(interval)
|
||||
defer ticker.Stop()
|
||||
for {
|
||||
select {
|
||||
case <-ctx.Done():
|
||||
fmt.Fprintln(out, "near-anchor schedule: stopping")
|
||||
return nil
|
||||
case <-ticker.C:
|
||||
tick()
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -1,192 +0,0 @@
|
||||
package nearanchor
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/caelum0x/ration/services/audit-log/internal/store"
|
||||
)
|
||||
|
||||
// TestDecideAnchor is the plain, no-network unit test for the exact
|
||||
// rule RunOnce relies on to be "idempotent, skip when nothing new":
|
||||
// whether to submit an anchor transaction depends only on comparing the
|
||||
// real local tip's sequence against whatever is already anchored
|
||||
// on-chain.
|
||||
func TestDecideAnchor(t *testing.T) {
|
||||
cases := []struct {
|
||||
name string
|
||||
local store.Record
|
||||
onChain AnchorRecord
|
||||
want bool
|
||||
}{
|
||||
{
|
||||
name: "nothing anchored yet — first commit always proceeds",
|
||||
local: store.Record{Sequence: 1, Hash: "h1"},
|
||||
onChain: AnchorRecord{},
|
||||
want: true,
|
||||
},
|
||||
{
|
||||
name: "local ahead of on-chain — new records since last anchor",
|
||||
local: store.Record{Sequence: 7, Hash: "h7"},
|
||||
onChain: AnchorRecord{Sequence: 5, ChainTipHash: "h5"},
|
||||
want: true,
|
||||
},
|
||||
{
|
||||
name: "local equal to on-chain — nothing new, must skip",
|
||||
local: store.Record{Sequence: 5, Hash: "h5"},
|
||||
onChain: AnchorRecord{Sequence: 5, ChainTipHash: "h5"},
|
||||
want: false,
|
||||
},
|
||||
{
|
||||
name: "local behind on-chain — must never resubmit a stale sequence",
|
||||
local: store.Record{Sequence: 3, Hash: "h3"},
|
||||
onChain: AnchorRecord{Sequence: 5, ChainTipHash: "h5"},
|
||||
want: false,
|
||||
},
|
||||
}
|
||||
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
got, reason := decideAnchor(tc.local, tc.onChain)
|
||||
if got != tc.want {
|
||||
t.Fatalf("decideAnchor() = %v (%q), want %v", got, reason, tc.want)
|
||||
}
|
||||
if reason == "" {
|
||||
t.Fatal("decideAnchor returned an empty reason")
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// TestRunOnceSkipsOnEmptyLocalLog guards the same "anchoring nothing
|
||||
// looks identical to a real anchor" failure mode
|
||||
// TestLocalTipErrorsOnEmptyLog (integration_test.go) guards for
|
||||
// LocalTip/CommitAnchor: RunOnce must report a clean skip, not an
|
||||
// error and not a commit, when the local audit-log has no records at
|
||||
// all yet. No real RPC call should happen in this case (and none does
|
||||
// — this test supplies no valid signer/contract config, so any attempt
|
||||
// to reach the network would fail loudly rather than silently pass).
|
||||
func TestRunOnceSkipsOnEmptyLocalLog(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
path := filepath.Join(dir, "audit.log")
|
||||
if _, err := os.Create(path); err != nil {
|
||||
t.Fatalf("create empty file: %v", err)
|
||||
}
|
||||
|
||||
cfg := Config{AuditLogPath: path}
|
||||
result, err := RunOnce(context.Background(), cfg, nil)
|
||||
if err != nil {
|
||||
t.Fatalf("RunOnce on an empty local log returned an error: %v", err)
|
||||
}
|
||||
if result.Committed {
|
||||
t.Fatal("RunOnce committed with no local records at all")
|
||||
}
|
||||
if result.HadLocal {
|
||||
t.Fatal("RunOnce reported HadLocal=true with no local records at all")
|
||||
}
|
||||
}
|
||||
|
||||
// TestRunSchedulerAgainstRealTestnet is the real, non-mocked
|
||||
// integration test for the auto-anchoring loop itself (not just
|
||||
// decideAnchor's pure logic): it appends a fresh real record to a real
|
||||
// audit-log file, runs RunScheduler for a couple of short ticks against
|
||||
// real NEAR Testnet, and checks that (a) the first tick actually
|
||||
// anchors the new tip and (b) every subsequent tick correctly skips
|
||||
// because nothing changed — proving the scheduler's idempotency holds
|
||||
// against the real chain, not just against decideAnchor's unit test.
|
||||
//
|
||||
// Skipped unless real signer/contract credentials are configured — see
|
||||
// TestCommitAndVerifyAgainstRealTestnet's doc comment
|
||||
// (integration_test.go) for the same gating convention. Point this at
|
||||
// the dedicated demo account (ration-demo-*.testnet), never the
|
||||
// primary submission account, so a verification run never advances
|
||||
// that account's on-chain history.
|
||||
func TestRunSchedulerAgainstRealTestnet(t *testing.T) {
|
||||
cfg, err := LoadForCommit()
|
||||
if err != nil {
|
||||
t.Skipf("skipping real NEAR Testnet scheduler integration test (set RATION_NEAR_ANCHOR_SIGNER_ACCOUNT_ID / RATION_NEAR_ANCHOR_SIGNER_SECRET_KEY / RATION_NEAR_ANCHOR_CONTRACT_ID to run it for real): %v", err)
|
||||
}
|
||||
if cfg.AuditLogPath == "" {
|
||||
cfg.AuditLogPath = filepath.Join(cfg.DataDir, "audit.log")
|
||||
}
|
||||
if err := os.MkdirAll(filepath.Dir(cfg.AuditLogPath), 0o755); err != nil {
|
||||
t.Fatalf("mkdir audit log dir: %v", err)
|
||||
}
|
||||
|
||||
st, err := store.Open(cfg.AuditLogPath)
|
||||
if err != nil {
|
||||
t.Fatalf("open audit log: %v", err)
|
||||
}
|
||||
now := time.Now().Unix()
|
||||
// RefID is time-varying (matching cmd/near-anchor's own cmdDemo
|
||||
// convention), not a fixed string: Store.Append is itself
|
||||
// idempotent on (source_service, kind, ref_id) — see store.go's
|
||||
// doc comment — so a fixed RefID would make a second run of this
|
||||
// test return the already-appended record instead of a genuinely
|
||||
// new one, making it impossible to tell "the scheduler skipped
|
||||
// because nothing is new" apart from "the test never appended
|
||||
// anything new to begin with."
|
||||
rec, err := st.Append(store.AppendInput{
|
||||
SourceService: "agent",
|
||||
Kind: store.SourceKindAgentDecision,
|
||||
TenantID: "tenant-scheduler-integration-test",
|
||||
RefID: fmt.Sprintf("scheduler-integration-test-decision-%d", time.Now().UnixNano()),
|
||||
PayloadJSON: `{"action":"RationBridge","amount_minor_units":4321}`,
|
||||
OccurredAtUnix: now,
|
||||
}, now)
|
||||
if err != nil {
|
||||
_ = st.Close()
|
||||
t.Fatalf("append: %v", err)
|
||||
}
|
||||
_ = st.Close() // RunOnce re-opens read-only via store.ReadTip
|
||||
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 90*time.Second)
|
||||
defer cancel()
|
||||
rpc := NewRPCClient(cfg.RPCURL)
|
||||
|
||||
first, err := RunOnce(ctx, cfg, rpc)
|
||||
if err != nil {
|
||||
t.Fatalf("first RunOnce against real NEAR Testnet: %v", err)
|
||||
}
|
||||
if !first.Committed {
|
||||
t.Fatalf("first RunOnce did not commit a new tip (sequence=%d): reason=%q", rec.Sequence, first.Reason)
|
||||
}
|
||||
if first.Commit.TransactionHash == "" {
|
||||
t.Fatal("first RunOnce committed but returned an empty transaction hash")
|
||||
}
|
||||
t.Logf("tick 1: anchored sequence=%d hash=%s tx=%s %s", rec.Sequence, rec.Hash, first.Commit.TransactionHash, first.Commit.ExplorerURL)
|
||||
|
||||
// Give the RPC node(s) a moment to reflect the just-finalized
|
||||
// commit before reading it back. Real-world findings from this
|
||||
// test (first observed empirically, not assumed): calling
|
||||
// get_latest_anchor() within ~1-2s of broadcast_tx_commit
|
||||
// returning can still see the pre-commit state on a different
|
||||
// backend node behind fastnear's public endpoint, and (separately)
|
||||
// re-deriving the access key nonce that fast can race the
|
||||
// just-used nonce before it's visible, failing a same-sequence
|
||||
// retry with a transaction-layer InvalidNonce error rather than a
|
||||
// clean decideAnchor skip. Neither corrupts on-chain state or
|
||||
// double-anchors (confirmed live: get_anchor_count stayed
|
||||
// unchanged across that race) — it only means two ticks fired
|
||||
// faster than RPC propagation, which a real scheduler interval
|
||||
// (minutes, see DefaultScheduleInterval) never does. This sleep
|
||||
// makes the test reflect that real operating condition instead of
|
||||
// deliberately hammering the race.
|
||||
time.Sleep(5 * time.Second)
|
||||
|
||||
// Re-run without appending anything new: the real on-chain anchor
|
||||
// now matches the real local tip exactly, so this must be a clean
|
||||
// skip, not a duplicate (and on-chain-rejected) commit.
|
||||
second, err := RunOnce(ctx, cfg, rpc)
|
||||
if err != nil {
|
||||
t.Fatalf("second RunOnce against real NEAR Testnet: %v", err)
|
||||
}
|
||||
if second.Committed {
|
||||
t.Fatal("second RunOnce committed again with nothing new since the first — idempotency check failed against the real chain")
|
||||
}
|
||||
t.Logf("tick 2: correctly skipped — %s", second.Reason)
|
||||
}
|
||||
Loading…
x
Reference in New Issue
Block a user