Skip to content
NearGate

REFERENCE

Registry contract

neargate-registry is the on-chain layer of NearGate: a pay-through service registry with payment-backed attestations, written in Rust on near-sdk. This page is its ABI, from contracts/registry/src.

CLI v0.2.1SDK v0.1.0registry neargate-app-registry.testnetnear-testnet

Overview

Buyers pay through the registry. pay(service_id, nonce) forwards exactly the service price to the seller’s payment_target, keeps a small storage fee, refunds the rest and stores a payment record. record_attestation is accepted only for a payment this contract itself received, once, and never when the payer is the service owner or the payment target — so a score can only come from real transfers between distinct parties (see the trust model, including what it does not prove).

A buyer can also prepay: deposit_escrow puts NEAR into a per-account escrow, and pay_from_escrow(service_id, nonce) settles a payment out of it exactly like pay but attaches nothing, so a NEAR function-call access key restricted to that one method can sign it (see escrow and agent keys).

The contract has no owner and no admin. The only privileged roles are per service: its owner (the registering account: switches the service on and off, rotates the attestor) and its attestor (records outcomes; the owner may too). Every panic message starts with a stable ERR_* code, so clients map errors by that prefix. Source: contracts/registry/src/lib.rs and types.rs.

DEPLOYED

The default registry is neargate-app-registry.testnet. Point REGISTRY_CONTRACT_ID or --registry elsewhere to use another one.

All amounts are yoctoNEAR (1 NEAR = 1024 yocto): u128 in Rust, decimal strings in JSON. Service ids are 1-based.

Constants and limits

ConstantMeaning
MIN_PRICE_YOCTO10^18 yocto · 0.000001 NEARFloor for the "near" price option. Other assets are priced in their own base units: any amount above zero.
PAYMENT_STORAGE_FEE_YOCTO2 × 10^21 yocto · 0.002 NEARKept by the registry on every pay, to cover the payment record’s storage.
REGISTRATION_DEPOSIT_YOCTO1.2 × 10^23 yocto · 0.12 NEARKept on every register_service (anything above is refunded). It prepays the service record and the storage for a full attestation list.
ESCROW_STORAGE_FEE_YOCTO2 × 10^21 yocto · 0.002 NEARKept from an account’s first deposit_escrow, which creates its escrow entry (the fee prepays that entry’s storage, about 125 bytes at most). The first deposit must be more than this; later deposits are credited in full.
MAX_ATTESTATIONS100Attestations kept per service, newest first.
ACTIVITY_CAP200Events kept in the activity ring buffer.
NAME_MAX64 bytesService name. Also the limit of accepts[].asset and accepts[].symbol.
DESC_MAX280 bytesService description.
URL_MAX200 bytesgateway_base_url.
ACCEPTS_MAX4Price options per service.
TX_HASH_MAX64 bytespayment_tx_hash of an attestation.
NONCE_MAX20A nonce is 1 to 20 decimal digits.
LIST_LIMIT_MAX50list_services page size (larger limits are clamped).

Every length limit counts UTF-8 bytes, not characters: storage is paid per byte, and one character can take four.

Change methods

new()

One-time #[init] with no arguments, so there is nothing to front-run; it sets no admin. It pre-writes every activity slot with a one-byte placeholder, so a later pay replaces a record instead of creating one and its storage cost stays inside the fee.

register_service — payable

register_service(name: String, description: String, gateway_base_url: String,
                 accepts: Vec<PaymentOption>, payment_target: AccountId,
                 attestor: AccountId) -> u64

Registers a service owned by the caller and returns its id. The name is trimmed and must not be empty; the length limits apply; accepts holds 1 to 4 options, at most one with asset: "near" (the only one pay settles), whose amount is at least MIN_PRICE_YOCTO, every other amount above zero. Attach at least 0.12 NEAR; the registry keeps that and refunds the rest. The service starts active. The call panics ERR_STORAGE_EXCEEDED if the registration plus the attestation reserve would not fit in the deposit.

pay — payable

pay(service_id: u64, nonce: String)

Pays for one call. The service must exist, be active and have a "near" option at price p. Attach at least p + 0.002 NEAR. The nonce must be 1 to 20 digits and never seen before (single-use across the whole registry). Transfers exactly p to the payment target, keeps the fee, refunds attached − p − fee to the payer, and stores the payment with self_paid = payer is the owner or the payment target. The measured storage cost must fit inside the fee.

pay_from_escrow — takes no deposit

pay_from_escrow(service_id: u64, nonce: String)

pay, funded by the caller’s escrow. It is marked payable in the ABI but rejects any attached deposit (ERR_DEPOSIT_NOT_ALLOWED, the first check). Then the checks of pay, in the same order, except that the escrow check replaces pay’s deposit check and comes before the nonce checks: the escrow must hold at least price + 0.002 NEAR. It debits exactly that from the escrow, sends the price to the payment target, keeps the fee and refunds nothing. The payment record, activity entry and payment event are the ones pay writes: the payer is the caller, so a score built on escrow payments is built on the same real transfers, and the same self-payment rule applies.

deposit_escrow — payable

deposit_escrow()

Credits the attached deposit to the caller’s escrow. The first deposit creates the entry: it must be more than 0.002 NEAR, the registry keeps that as ESCROW_STORAGE_FEE_YOCTO and credits the rest. Later deposits are credited in full and must attach something. Entries are never deleted, so an emptied escrow takes top-ups without a second fee.

withdraw_escrow — payable, exactly 1 yocto

withdraw_escrow(amount: U128)

Sends amount of the caller’s escrow back to the caller. It needs exactly 1 yocto attached, which a function-call key cannot attach, so only a full-access key can withdraw. The amount must be between 1 and the balance. The escrow is debited before the transfer; the private callback on_escrow_withdraw(account_id, amount) puts the amount back, once, if the transfer fails (a direct call to it from anyone else panics). The 1 yocto stays in the registry.

record_attestation

record_attestation(service_id: u64, nonce: String, payment_tx_hash: String, success: bool)

Records the outcome of the call that followed a payment. The caller must be the service’s attestor or owner and the service active. The payment must exist for that service, not yet be attested and not be self-paid. It marks the payment attested, bumps the score (total + 1, and success + 1 when success), prepends the attestation (the list is truncated at 100) and writes an activity entry. payment_tx_hash is informational, at most 64 bytes. Not payable: the score and the attestation list are prepaid by the registration deposit, while the activity entry overwrites a slot of the 200-slot ring and any growth of that slot is paid from the registry account’s own balance (at most about 0.5 NEAR in all; near:deploy wants 3 NEAR on the account for this).

set_active · set_attestor

set_active(service_id: u64, active: bool)
set_attestor(service_id: u64, attestor: AccountId)

Owner only. An inactive service accepts no new payments and no attestations. set_attestor replaces the account that may attest (the owner always may).

Views

ViewReturns
get_service(service_id)ServiceView or null.
list_services(from_index, limit)ServiceView[] with ids from_index.. ascending (1-based; 0 starts at 1); limit is clamped to 50.
services_count()The number of services, which is also the newest id.
get_score(service_id){ total_calls, success_calls }; zeros for an unknown id.
get_attestations(service_id)AttestationView[], newest first, at most 100; empty for an unknown id.
get_payment(nonce)PaymentView or null. This is what the gateway verifies a proof against.
get_recent_activity(limit)ActivityView[], newest first; limit is clamped to 200.
escrow_of(account_id)The account’s escrow as a U128 decimal string; "0" for an account that never deposited.

JSON shapes

Views are snake_case JSON; U128 amounts are decimal strings.

ServiceView (get_service of service #1 on the deployed registry)

{
  "id": 1,
  "name": "USD exchange rates",
  "description": "Latest USD exchange rates from open.er-api.com, wrapped by the NearGate testnet seed script",
  "gateway_base_url": "https://neargate-gateway-production.up.railway.app",
  "accepts": [
    {
      "asset": "near",
      "amount": "10000000000000000000000",
      "decimals": 24,
      "symbol": "NEAR"
    }
  ],
  "payment_target": "neargate-app-seller.testnet",
  "owner": "neargate-app-seller.testnet",
  "attestor": "neargate-app-gateway.testnet",
  "active": true,
  "created_at_ms": 1794495083358
}
TypeFields
PaymentOption{ asset, amount, decimals, symbol }
ScoreView{ total_calls, success_calls }
AttestationView{ nonce, payment_tx_hash, success, timestamp_ms }
PaymentView{ nonce, service_id, payer, amount, timestamp_ms, block_height, self_paid, attested }
ActivityView{ kind, service_id, account, amount?, success?, nonce?, payment_tx_hash?, timestamp_ms, block_height }; kind is service_registered, payment or attestation, and account is the owner, the payer, or whoever recorded the attestation (the attestor or the owner) accordingly.

The public endpoint is never stored: the contract keeps only gateway_base_url, and every reader computes <gateway_base_url>/svc/<id>. An activity view cannot name its own transaction, which is why the dashboard’s live feed links to the event’s block and the gateway serves receipts.

Events

Change methods emit NEP-297 events with standard: "neargate" and version: "1.0.0":

EventData
service_registered{ service_id, owner, name, payment_target, attestor }
payment{ service_id, nonce, payer, amount, self_paid }
attestation{ service_id, nonce, payment_tx_hash, success, caller }
service_status{ service_id, active }
attestor_changed{ service_id, attestor }
escrow_deposit{ account_id, amount, balance }: amount is what was credited (net of the storage fee on a first deposit, or a failed withdrawal put back) and balance the escrow after it.
escrow_withdraw{ account_id, amount, balance }: the amount debited and the escrow after the debit.

The activity ring has no escrow entries: an escrow payment is a payment entry like any other, and deposits and withdrawals appear in the events only.

Escrow and agent keys

An AI agent should not hold a key that can empty its owner’s account. NEAR offers a function-call access key, restricted to one receiver and a list of methods, that can attach no deposit. The registry’s escrow is built around that:

CallAttachesWho can sign it
deposit_escrowthe amount to prepaya full-access key
withdraw_escrowexactly 1 yoctoa full-access key only
pay_from_escrownothinga full-access key, or a function-call key restricted to pay_from_escrow on the registry

THE SECURITY PROPERTY

An agent key restricted to pay_from_escrow on the registry can spend the escrow and nothing else. It cannot withdraw (that attaches 1 yocto), deposit, register or pause a service, or move any other balance, and NEAR rejects any other call from it. Withdrawing needs a full-access key. The escrow is the spending limit: a leaked agent key can spend all of it, on any active service, and no more NEAR than that. Its gas is paid by the account, not the escrow, so a leaked key can also burn gas from the account balance up to its allowance. Keep in the escrow only what the agent may spend, keep the allowance low, and top the escrow up from the full-access key.

Create such a key with neargate agent-key add and fund the escrow with neargate escrow deposit. The key’s allowance only pays its gas, and that gas comes from the account balance (not the escrow): it caps how much gas a leaked key can burn there.

Error codes

A panic message is ERR_CODE: text. The clients keep the code as the error’s code, in mock and live mode alike. Failures that are not contract rejections (transport, a sent transaction without an outcome, a missing key) have their own codes on the CLI page.

CodeWhen
ERR_EMPTY_NAMEregister_serviceThe trimmed name is empty.
ERR_FIELD_TOO_LONGregister_service, record_attestationA field is over its byte limit: name, description, gateway_base_url, accepts.asset, accepts.symbol, payment_tx_hash.
ERR_INVALID_PRICEregister_serviceaccepts has fewer than 1 or more than 4 options, a "near" amount is below 10^18 yocto, another amount is zero, or more than one option is "near".
ERR_DEPOSIT_TOO_LOWregister_service, pay, deposit_escrowAttached below 0.12 NEAR (registration) or below price + 0.002 NEAR (pay; the message states the required yocto). deposit_escrow: a first deposit that is not more than 0.002 NEAR, or a top-up that attaches nothing.
ERR_STORAGE_EXCEEDEDregister_service, pay, pay_from_escrow, deposit_escrowThe call’s measured storage cost is above its budget (the deposit, or the fee).
ERR_SERVICE_NOT_FOUNDpay, pay_from_escrow, record_attestation, set_active, set_attestorNo service with that id.
ERR_SERVICE_INACTIVEpay, pay_from_escrow, record_attestationThe owner switched the service off.
ERR_NO_NATIVE_PRICEpay, pay_from_escrowThe service has no "near" price option to settle.
ERR_INVALID_NONCEpay, pay_from_escrowThe nonce is not 1 to 20 decimal digits.
ERR_NONCE_USEDpay, pay_from_escrowThe nonce was already paid. Nonces are single-use across the registry.
ERR_NOT_AUTHORIZEDrecord_attestation, set_active, set_attestorThe caller is not the service owner (set_active, set_attestor) or the attestor or owner (record_attestation).
ERR_PAYMENT_NOT_FOUNDrecord_attestationThe registry holds no payment with that nonce.
ERR_PAYMENT_WRONG_SERVICErecord_attestationThe payment belongs to another service.
ERR_ALREADY_ATTESTEDrecord_attestationThat payment was already attested. The gateway treats this as done, not failed.
ERR_SELF_PAYMENTrecord_attestationThe owner or the payment target paid; it cannot be attested.
ERR_ESCROW_INSUFFICIENTpay_from_escrow, withdraw_escrowpay_from_escrow: the escrow holds less than price + 0.002 NEAR (an account that never deposited holds 0). withdraw_escrow: the amount is 0 or above the balance. The message states the balance.
ERR_ONE_YOCTO_REQUIREDwithdraw_escrowNot exactly 1 yocto attached. It is the first check, and the reason a function-call key cannot withdraw.
ERR_DEPOSIT_NOT_ALLOWEDpay_from_escrowAny deposit attached. pay_from_escrow spends the escrow and takes none; it is the first check.

One more code is NEAR’s, not the contract’s: ERR_INSUFFICIENT_BALANCE means the signer cannot fund the deposit plus gas, or would be left short of its storage stake after the transaction. pay_from_escrow checks, in this order: ERR_DEPOSIT_NOT_ALLOWED, ERR_SERVICE_NOT_FOUND, ERR_SERVICE_INACTIVE, ERR_NO_NATIVE_PRICE, ERR_ESCROW_INSUFFICIENT, ERR_INVALID_NONCE, ERR_NONCE_USED; withdraw_escrow: ERR_ONE_YOCTO_REQUIRED, then ERR_ESCROW_INSUFFICIENT.

Build, test and deploy

from the repository root

(cd contracts/registry && cargo near build non-reproducible-wasm --env 'RUSTFLAGS=-C link-arg=-s --remap-path-prefix=$HOME=/build')
# -> contracts/target/near/neargate_registry/neargate_registry.wasm
(cd contracts && cargo test)

The toolchain is pinned in contracts/rust-toolchain.toml; cargo-near is a separate install. npm run near:deploy builds and deploys the contract onto the registry account and reads services_count back; see the quickstart. The build above is the one it runs: the path remap keeps the builder’s home directory out of the wasm published on-chain, and near:deploy refuses a wasm that still holds a path under $HOME (including one passed in NEARGATE_REGISTRY_WASM). Reads need no key:

with the near CLI

near contract call-function as-read-only neargate-app-registry.testnet get_service json-args '{"service_id":1}' network-config testnet now