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
4 changed files with 434 additions and 0 deletions

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)
}