Compare commits

..

1 Commits

Author SHA1 Message Date
f5b6c6a75e feat(near-anchor): add scheduled auto-anchoring (near-anchor schedule)
Audit-log's NEAR Testnet anchoring was manual-only (an operator running
`near-anchor commit` by hand). Add a `schedule` subcommand that repeats
the decide-then-anchor flow on a fixed interval
(RATION_NEAR_ANCHOR_INTERVAL, default 5m) until SIGINT/SIGTERM:

- Batching is structural, not buffered: anchoring the current hash-chain
  tip already cryptographically commits every record appended since the
  last anchor, so one tick = one anchor tx no matter how many new
  records landed.
- Idempotent / skips when nothing new: decideAnchor compares the local
  tip's sequence against the contract's own get_latest_anchor() (a free
  view call) before ever signing a transaction, so a tick with no new
  records costs nothing and two concurrent anchorers can't double-commit
  (the contract's own sequence guard is the backstop either way).
- Survives restarts with zero checkpoint state: every tick re-reads the
  real local file and the real on-chain state fresh, so a crash
  mid-tick is safe — the next tick just re-decides from the chain
  itself.

Verified for real against NEAR Testnet (dedicated demo account
ration-demo-23bd92e5.testnet, never the primary submission account):
found a real pre-existing backlog of 3 un-anchored local records
(sequence 2 on-chain vs. sequence 5 local), ran the scheduler, and
confirmed exactly one batched anchor tx closed the gap
(tx HP5VcN88FbDzTw3VBD7fgaftgzhoM5f8fc6Yibx5w9qM, sequence 6), with a
second tick correctly skipping. A follow-up run (tx
6w6FUTWTSKGhnmJWqzYGuNBrZrkFW6Ux4g32wqEP9SDq, sequence 8) re-confirmed
the same batch-then-skip behavior after fixing a race the first attempt
surfaced (back-to-back ticks faster than RPC view-propagation lag can
see a stale on-chain state — safe, since no corruption/double-anchor
occurred, but real and worth a comment; irrelevant at any real
multi-minute interval). All on-chain state independently re-verified via
raw JSON-RPC against rpc.testnet.fastnear.com outside the Go tooling.

On branch feat/auto-anchoring — not merged to main, since the NEAR
hackathon entry is submitted from main and must not change before then.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-11-10 17:13:37 +03:00
16 changed files with 446 additions and 361 deletions

View File

@ -103,19 +103,6 @@ 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
@ -162,8 +149,3 @@ 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)

View File

@ -7,28 +7,12 @@ 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 (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:
**🎬 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:
[`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 —

View File

@ -1,146 +0,0 @@
---
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.**

Binary file not shown.

Binary file not shown.

View File

@ -1,4 +1,4 @@
# NEAR Hackathon submission checklist (dev deadline Nov 14 2026 23:59 UTC, results by Nov 18 2026 23:59 UTC)
# NEAR Hackathon submission checklist (dev deadline Nov 14 2026 23:59 UTC, judging Nov 16-18)
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,24 +59,7 @@ 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 + 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)
## Done (demo video, added 2026-11-10)
- [x] **Demo video recorded** — a real, unedited `near-anchor demo` run
(`asciinema` + `agg` + `ffmpeg`, same tooling cred402 used for its
@ -88,9 +71,8 @@ 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`. Superseded as the
primary attachment by the narrated video above, but kept as a
shorter alternate.
`z8GWsRVxDykJ55rTKgb4dbN9WTH1UGMzk4NhQfogFrt`. Full detail in
`HACKATHON.md`'s "🎬 Demo video" line.
## Owner-only (fill in before submitting)

View File

@ -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
the same contract — nearcore itself rejected it on-chain.
We also deliberately tried replaying an already-anchored sequence on a
sibling contract — nearcore itself rejected it on-chain.
@NEARProtocol #NEARHackathon

View File

@ -1,15 +0,0 @@
{"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"]

View File

@ -1,136 +0,0 @@
---
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.**

Binary file not shown.

Binary file not shown.

View File

@ -17,6 +17,13 @@
// 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
@ -39,6 +46,8 @@ import (
"encoding/json"
"fmt"
"os"
"os/signal"
"syscall"
"time"
"github.com/caelum0x/ration/services/audit-log/internal/nearanchor"
@ -64,6 +73,8 @@ 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":
@ -84,6 +95,10 @@ 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
@ -208,6 +223,35 @@ 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 {

View File

@ -3,6 +3,7 @@ package nearanchor
import (
"fmt"
"os"
"time"
)
// defaultFunctionCallGas is 100 Tgas — nearcore's own convention for a
@ -67,3 +68,21 @@ 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
}

View File

@ -0,0 +1,179 @@
// 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()
}
}
}

View File

@ -0,0 +1,192 @@
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)
}