Skip to content
AngeYoboPublic

About

OxWrit is an on-chain Policy Enforcement Point (PEP) for NEAR: a vault contract that moves funds only when presented with a valid OxWrit, a policy-signed, intent-bound, single-use authorization.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

8 Commits

Folders and files

Repository files navigation

OxWrit

For judges

Run these four steps from the repository root, in the same shell. No private key or NEAR transaction is needed. Requirements: Rust (tested with 1.99.1), Git and Python 3; network access for the pinned spec, Rust dependencies and public testnet RPC. The public xcheck/cases.json fixture is included, so running the tests does not require Node or fixture regeneration.

  1. Fetch the pinned normative spec:

    export OXDEAI_REPO="$(mktemp -d /tmp/oxwrit-spec.XXXXXX)" && git clone https://github.com/oxdeai/oxdeai "$OXDEAI_REPO" && git -C "$OXDEAI_REPO" checkout --detach c6764fdc90f4fe6c57189e2dff3cd825e5dcd5eb

    Expected: checkout at c6764fdc.

  2. Test the default ASCII verifier and contract in the mocked NEAR runtime:

    cargo test --workspace --locked

    Expected: 18 tests passed, 0 failed (10 vault, 8 verifier integration tests); doc tests pass. Mocked contract tests schedule receipts; they do not execute real transfers.

  3. Test NFC canonicalization and the verifier against the same pinned spec:

    cargo test -p oxdeai-verify --features nfc --locked

    Expected: 9 tests passed, 0 failed, including 12 authorization vectors, 11 canonicalization vectors and 5 core/Rust cross-check cases inside the integration tests.

  4. Verify the current V2 deployment and V2/V1 transaction evidence:

    ./evidence/verify-onchain.sh

    Expected: Summary: 16 PASS, 0 FAIL, 4 NOT_TESTED, exit 0. The four local-only scenarios are not rerun; a missing or unavailable required RPC check never counts as PASS. See evidence scope. This RPC script does not independently rebuild the source.

No OxWrit, no execution. Enforced on-chain.

OxWrit is an on-chain Policy Enforcement Point (PEP) for NEAR: a vault contract that moves funds only when presented with a valid OxWrit, a policy-signed, intent-bound, single-use authorization.

An OxWrit is an OxDeAI AuthorizationV1, verified inside the contract before any side effect is reachable.

agent ──proposes──▶ PDP (policy) ──ALLOW──▶ OxWrit (Ed25519-signed AuthorizationV1)
                                               │
agent ──execute(action, OxWrit)──▶ vault.oxwrit.testnet
                                     ├─ verify signature against trusted issuer key
                                     ├─ recompute intent hash from the action it is about to run
                                     ├─ check audience and expiry against block time
                                     ├─ consume auth_id (persistent, before any effect)
                                     ├─ transfer
                                     └─ emit executed: auth_id -> ok | failed

The agent holds a NEAR function-call access key that can only call execute on the vault. It cannot sign a transfer, and it cannot call any other method. The only path to the funds goes through the OxWrit check.

Why

Agents now act with real money. Most controls around them are prompt guardrails (probabilistic) or monitoring (after the fact). OxWrit makes the effect itself conditional: the contract refuses anything that was not explicitly authorized for that exact action, once.

Logs explain what happened. An OxWrit proves what was allowed, and the chain proves it was enforced.

What was built during NEAR HACKATHON, and what already existed

Already existed (before Nov 1, 2026) Built during the hackathon
The OxDeAI protocol: AuthorizationV1 spec, canonicalization-v1, locked test vectors verify/: a fail-closed Rust AuthorizationV1 verifier for constrained runtimes
@oxdeai/core (TypeScript reference implementation, npm) vault/: the NEAR contract (on-chain PEP)
pdp/: a policy decision point that signs OxWrits with @oxdeai/core@2.0.2 from npm
xcheck/: cross-verification of core-signed artifacts against the Rust verifier
Deployment and the on-chain evidence below

On-chain evidence (NEAR testnet, V2 contract)

Contract: vault.oxwrit.testnet. V2 means the second deployed OxWrit contract; its authorization format is still AuthorizationV1 / Ed25519, not AuthorizationV2 or HMAC.

The deployed WASM was downloaded through archive RPC and compared byte-for-byte with the local artifact: 187167 bytes, SHA-256 b2f18a62c156b70b1318e9877f6509ec99f06581e6d53f512483b5165312376f, base58 D3XC1qr9Atc6tqjCJzXsSrwH1iUas1jrKgUgczeKUCMc. Declared source commit: 64337b52353ab704dcb535ad534fd0746818466c; its source snapshot and full build-image digest are embedded in the WASM build metadata and match vault/Cargo.toml. Local/deployed equality alone does not establish an independent rebuild. An independent clean-clone build of that commit in the pinned image also completed successfully: its WASM matches the deployed bytes exactly. See Verify the deployed code and the verification record.

Scenario Expected Observed Exact rejection reason Enforcement layer Transaction RPC gas (Tgas)
ALLOW Transfer 0.1 NEAR once authorized + executed ok; return true — OxDeAI / OxWrit: signed authorization checks FSZ29Zdgb6c8xd17po1TGqXyNjkxra4P5zw8T5tLrc54 5.547274198043
REPLAY Reject reused authorization Failed receipt DENY:AUTH_REPLAY OxDeAI / OxWrit: auth_id anti-replay 9ep442TKBunQiLm1mz5VALUYdi7s75LVpztnkcbqAyQR 2.497705079199
NOT COVERED Reject changed amount Failed receipt DENY:INTENT_HASH_MISMATCH OxDeAI / OxWrit: action/authorization binding 9aaYNcvCrxPYdfh7G9N5JgSdFnA38R6iYyiDM134YAMN 2.002320955298
PDP DENY: receiver Refuse forbidden receiver DENY in preserved local log RECEIVER_NOT_ALLOWED PDP policy None: no authorization issued and no transaction submitted —
PDP DENY: amount Refuse amount over policy DENY in preserved local log AMOUNT_OVER_LIMIT PDP policy None: no authorization issued and no transaction submitted —
BYPASS: direct transfer Reject restricted key Signed attempt rejected by protocol Transaction requires a full permission access key. NEAR native permissions, not OxDeAI No accepted/included transaction; see qualification below —
BYPASS: call new Reject method outside execute Signed attempt rejected by protocol Transaction method name <new> isn't allowed by the access key. NEAR native permissions, not OxDeAI No accepted/included transaction; see qualification below —

The four local outcomes are recorded in evidence/raw/v2/runs.txt, not independently rerun by the read-only script. The BYPASS log shows signed invalid attempts: there is no accepted on-chain transaction/hash. That does not prove that the signed payload was never sent to an RPC; protocol rejection before inclusion and absence of any submission are different claims. The PDP refusals stop before authorization issuance and transaction creation. The original logs are retained without rewriting this distinction.

Gas is calculated using integer RPC values: transaction_outcome.outcome.gas_burnt + sum(receipts_outcome[].outcome.gas_burnt), divided by 10^12 Tgas. The CLI's rounded 5.6 / 2.5 / 2.1 figures are not substituted for these exact totals.

./evidence/verify-onchain.sh uses https://archival-rpc.testnet.fastnear.com by default (RPC=... override). It checks the current V2 fingerprint and downloaded WASM checksum/size, PDP key tuple, native agent permission and FullAccess limitation, all three V2 transactions, and eight historical V1 transactions. It verifies execute, signers where recorded, matching auth_id in authorized/executed events and exact failure reasons. It never signs or submits a transaction. Expected: 16 PASS, 0 FAIL, 4 NOT_TESTED, exit 0. The four NOT_TESTED entries are explicitly local-only scenarios; a required RPC check that cannot run produces NOT_TESTED and exit 2. Invalid/incomplete responses, missing transactions or incorrect outcomes produce FAIL and exit 1.

Earlier runs (v1 contract)

Old code hash: 754WzekJ6JY6fL6rHM4mXBzqo5wWRP9ABk8LCdvVWZaW. These are historical outcomes from the earlier contract, not evidence of V2 execution. The old WASM is not linked to an identified reproducible source commit in this repository. The original run and the 13 November rerun remain unchanged in evidence/raw/v1/, including rerun-2026-11-13.txt.

Scenario Historical result verified by RPC Transaction RPC gas (Tgas)
Original ALLOW authorized → executed ok FZkv4P2Q8br3gcLtfdRbkMcDYVZyoJ3LFqiYb7VuvDo1 5.514210549211
Original agent ALLOW authorized → executed ok CSFNmFoqPobY4QV3NoVW5EvDDNfh8JubKvT25ivtSxU8 5.523330549211
Original REPLAY DENY:AUTH_REPLAY 7tnyWvuvCEGTWLS2Vbgaeb8kmQfPfzx558gqUjKuHDAL 2.478047839461
Original NOT COVERED DENY:INTENT_HASH_MISMATCH 8Ynv1g6T92cDSW4xPPMWjFihdwdGiFXmgsVAMQdQkefD 1.989639470300
Agent key added FunctionCall execute only CVc3gdPeDm7oW3QsnDk6b7U4SfEdMM7P42pEzvU5pCu 0.643767617796
2026-11-13 rerun ALLOW authorized → executed ok 94coPy1mb2hEtGGaXiM75uAwJkNhMwL1zsyzJrPFLkin 5.528991463803
2026-11-13 rerun REPLAY DENY:AUTH_REPLAY CDi6UmmPh2pmo4C2pKuT2DhR6hk1vTcouVm7NTg6G25g 2.488268754053
2026-11-13 rerun NOT COVERED DENY:INTENT_HASH_MISMATCH 8eBPFMEKrDaZZnvHjuY5GLd5jqvxfQtYyMVq98g6yNwB 1.995195894880

The historical BYPASS terminal outputs are also retained in v1; they have no accepted on-chain transaction IDs. Reading a historical transaction does not independently reconstruct the code hash at that execution height; the v1/v2 attribution also relies on the deployment record and supplied logs.

Verify the deployed code

Use a separate clean clone; do not change the checkout used for ongoing work. Requirements: Git, Docker Engine with daemon access, the exact build image below, and cargo-near supporting build reproducible-wasm. The outer CLI observed in this verification is cargo-near 0.23.0; the pinned container supplies cargo-near 0.22.0 and Rust 1.99.1. Host Rust was 1.99.1; Docker client was 29.1.3. The read-only account-summary example uses near-cli-rs 0.31.1. Python 3 is required by verify-onchain.sh; SHA-256 examples use sha256sum.

Full build image, checked against both vault/Cargo.toml and embedded WASM build metadata:

sourcescan/cargo-near:0.22.0-rust-1.99.1@sha256:c9655eaf7436b90c87ea8b25739f91063032c5c30ba24cfeafe72c142943b5bb
REPRO_DIR="$(mktemp -d /tmp/oxwrit-repro.XXXXXX)"
git clone https://github.com/AngeYobo/oxwrit "$REPRO_DIR"
git -C "$REPRO_DIR" checkout --detach 64337b52353ab704dcb535ad534fd0746818466c
cd "$REPRO_DIR/vault"
cargo near build reproducible-wasm
sha256sum ../target/near/oxdeai_vault/oxdeai_vault.wasm
wc -c < ../target/near/oxdeai_vault/oxdeai_vault.wasm

Expected SHA-256: b2f18a62c156b70b1318e9877f6509ec99f06581e6d53f512483b5165312376f; expected size: 187167. This path assumes CARGO_TARGET_DIR is unset; custom target paths must be reflected in the checksum command. The configured inner command is cargo near build non-reproducible-wasm --locked inside the digest-pinned container; the outer reproducible command checks out committed sources and records the source snapshot.

Read the live checksum without signing or sending a transaction:

near account view-account-summary vault.oxwrit.testnet network-config testnet now

Expected Local Contract (SHA-256 checksum hex): b2f18a62c156b70b1318e9877f6509ec99f06581e6d53f512483b5165312376f. The public RPC view_account.code_hash uses the base58 encoding above. Successful checksum comparison establishes the artifact identity; only a completed independent build establishes reproducibility. The actual build attempt and its status are recorded in evidence/V2-VERIFICATION.md.

Guarantees, and their limits

What holds today:

  • Execution binding. The vault, receiver, amount and nonce are inside the signed intent hash. The contract recomputes it from the action it is about to execute. Any change is rejected.
  • Bounded use. Each auth_id is consumed in persistent contract storage before any effect is scheduled. There is no capacity-based eviction.
  • Trusted time. Expiry is checked against block time, not the agent's clock.
  • Effect evidence. The transfer callback emits executed with auth_id -> ok | failed. This is a prototype of OxDeAI's planned ExecutionReceiptV1, not the specified artifact.
  • Agent non-bypass. The agent's key can only call execute. NEAR itself rejects transfers and other method calls signed with it.

What does not hold yet, stated plainly:

  • The vault account's full-access key is outside the boundary. Whoever holds it can redeploy the contract or move funds. Deleting that key makes the contract immutable and closes this gap; it also rules out upgrades.
  • No state binding on-chain. The PDP signs a state_hash, but the vault does not re-derive it.
  • Three failure cases. (1) If the initial execute receipt fails (verification, insufficient balance while reserving the transfer, gas exhaustion, or insufficient storage stake), its state changes and promises roll back: no durable consumption or callback is guaranteed. (2) If execute succeeds but the later transfer receipt fails (for example, a missing named receiver), auth_id stays consumed and a successful callback emits executed: failed. (3) If the callback itself fails, prior transfer/consumption are not undone, and the final event may be missing. Do not retry on the assumption that every failed transaction is unconsumed; inspect the receipts and is_consumed.
  • Per-authorization policy only. The PDP limits a single amount and receiver, not a cumulative budget. Reissuing the same action/nonce with a new auth_id creates a separate authorization. The nonce is intent-bound but is not tracked on-chain; only auth_id is consumed.
  • No issuer-key rotation or owner withdrawal method. owner remains stored for Borsh layout compatibility but grants no contract permissions. An upgrade without an init call preserves the existing owner, keys and consumed IDs; new initializer validation applies only to fresh initialization.
  • Storage is paid by the vault. Each consumed ID remains permanently; growth is unbounded. For this LookupSet layout, a mocked-runtime measurement of a 36-byte UUID adds 81 storage bytes (45 bytes overhead plus the ID length). At the mock's 10^19 yoctoNEAR/byte this locks 0.00081 NEAR per UUID (128-byte ID: estimated 173 bytes / 0.00173 NEAR), excluding code/base state and gas. This is an estimate, not a live-chain measurement; use actual storage deltas and the runtime storage price for funding. Keep a reserve: insufficient storage stake can block execution. There is no automatic funding, quota or pruning mechanism.
  • Input bounds in the current source. Authorization JSON is limited to 16 KiB before parsing; action nonce, optional authorization nonce and auth_id are limited to 128 UTF-8 bytes. Oversized authorization/identifier returns AUTH_MALFORMED; oversized action nonce returns NONCE_TOO_LONG. JSON decoding by near-sdk happens before the method body; these are application checks, not a limit on the outer transaction argument decoder.
  • Subset of OxDeAI verification. Ed25519 with explicit trusted keys only. No HMAC path, no delegation. The default wasm is ASCII-only: nfc is not enabled. Non-ASCII canonicalized input fails closed rather than being NFC-normalized. Enabling nfc in verifier tests does not enable it in a default wasm build.
  • Not audited. This is a hackathon prototype. @oxdeai/core remains the reference implementation.

Conformance of the Rust verifier

Check Result
OxDeAI locked vectors authorization-v1.json 12/12
OxDeAI locked vectors canonicalization-v1.json 11/11 with nfc; ASCII build rejects the one non-ASCII vector by design
Artifacts signed by @oxdeai/core (domain-prefixed preimage): Rust verdict vs core verdict 5/5 identical
OxWrit from pdp/sign.mjs (npm @oxdeai/core@2.0.2) executed by the vault accepted, auth_id consumed

Repository layout

Path Content
verify/ AuthorizationV1 verifier and canonicalization-v1, no NEAR dependency. Signature check injected (dalek in tests, env::ed25519_verify on-chain).
vault/ near-sdk contract. execute(action, authorization) is the only fund-moving method.
pdp/ Policy decision point: evaluates (intent, state, policy) against policy.json, signs on ALLOW.
xcheck/ Generates core-signed artifacts for cross-verification.

Libraries and spec baseline

The normative OxDeAI spec and locked vectors are pinned to c6764fdc90f4fe6c57189e2dff3cd825e5dcd5eb. Cargo.lock and the npm lockfiles record resolved dependency versions.

Library Use
near-sdk Contract serialization, storage, promises and NEAR host functions; unit-testing is test-only.
ed25519-dalek Rust tests only: signing test artifacts and native signature verification; wasm uses env::ed25519_verify.
serde / serde_json Parsing and serialization in verifier/contract.
sha2 Canonical SHA-256 hashes in the verifier.
base64 Signature decoding in verifier; also test artifact encoding.
unicode-normalization Optional verifier nfc feature; used by NFC tests, absent from default wasm.
@oxdeai/core 2.0.2 npm reference signer/verifier in PDP and xcheck, exact version in both package manifests/locks.

The manifests also declare rand (vault tests only) and hex (verifier tests only). The OxDeAI protocol, spec, locked vectors and TypeScript library predate this NEAR integration.

Reproduce

Requirements: Rust 1.95+, cargo-near, near-cli-rs, Node 20+.

# Fetch the spec as shown in For judges, then run the checked-in public fixture.
# OXDEAI_REPO must point at commit c6764fdc90f4fe6c57189e2dff3cd825e5dcd5eb.
cargo test -p oxdeai-verify --features nfc --locked

# Optional fixture regeneration: disposable Ed25519 key generated in memory, never written to disk.
# Only the public key, intent, signed authorizations and reference verdicts are written.
npm ci --prefix xcheck --ignore-scripts
node xcheck/gen.mjs
# This intentionally generates new signatures/public key; the same five verdicts are expected.

# Contract scenarios in the NEAR mocked runtime
cargo test -p oxdeai-vault

# Build the contract
(cd vault && cargo near build non-reproducible-wasm --locked)

# PDP: sign an OxWrit (the private key never lives in this repo)
npm ci --prefix pdp --ignore-scripts
OXWRIT_PDP_KEY=~/.oxwrit/pdp.pem node pdp/sign.mjs oxwrit.testnet 100000000000000000000000 n1   # ALLOW
OXWRIT_PDP_KEY=~/.oxwrit/pdp.pem node pdp/sign.mjs mallory.testnet 1 n2                         # DENY: receiver
OXWRIT_PDP_KEY=~/.oxwrit/pdp.pem node pdp/sign.mjs oxwrit.testnet 2000000000000000000000000 n3  # DENY: amount

Operator-only examples below require the existing PDP private-key path and restricted agent key-file path. They sign and broadcast testnet transactions; they are not part of the judge path. Run from the repository root. A new replay requires a fresh authorization within its 300-second TTL; old evidence authorizations have expired. Use the existing agent key for execution, and a full-access key only for a separately authorized deployment.

ARGS=$(OXWRIT_PDP_KEY=~/.oxwrit/pdp.pem node pdp/sign.mjs oxwrit.testnet 100000000000000000000000 n1 2>/dev/null)
near contract call-function as-transaction vault.oxwrit.testnet execute json-args "$ARGS" \
  prepaid-gas '100 Tgas' attached-deposit '0 NEAR' \
  sign-as vault.oxwrit.testnet network-config testnet sign-with-access-key-file $AGENT_KEY send

# Bypass attempt: direct transfer with the same key
near tokens vault.oxwrit.testnet send-near oxwrit.testnet '0.01 NEAR' \
  network-config testnet sign-with-access-key-file $AGENT_KEY send

Tracks

AI Security & Defense.

License

Apache-2.0, as OxDeAI.

Built at NEAR HACKATHON, November 2026.

Why not only NEAR's Agent API

NEAR's Agent API sets wallet-level spending policy (limits, budgets, allowlists). OxWrit is complementary, not a replacement: it verifies, inside the contract and per action, that this exact transfer (vault, receiver, amount, nonce) was authorized by a trusted policy decision point, before any effect. Wallet limits bound how much an agent can spend; an OxWrit proves that each specific payment was explicitly allowed, once, and binds the decision to the executed action on-chain. The two can be layered: Agent API budgets on the agent's wallet, OxWrit as the per-action enforcement point. Agent API integration was not built during this hackathon.

About

OxWrit is an on-chain Policy Enforcement Point (PEP) for NEAR: a vault contract that moves funds only when presented with a valid OxWrit, a policy-signed, intent-bound, single-use authorization.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages