Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Registry

The registry is a contract that maintains a list of contract versions, deploys new contracts, and maintains a list of those deployments. It is the only way a production market or proxy oracle is created: every one is a sub-account of the registry, deployed from a registered, audited version.

The account ID of the mainnet market registry is v1.tmplr.near. Read own_get_owner for its current owner rather than assuming the intended DAO handoff has occurred; what the owner can and cannot do is described in Protocol Governance.

Role-enabled V2 separates staged uploads from approved versions: Uploader pre-funds a NEP-145 storage balance and calls nonpayable upload_code (Borsh bytes), Owner approves an Uploaded or Global hash with JSON, and Deployer creates accounts from approved versions. Owner bypasses action role guards and alone sets roles, removes version code, upgrades the registry, or uses legacy add_version (including PublishGlobal). Query live owner/role/state-version views before assuming a registry has migrated; see the gated rollout.

Deployment names probe and deploy are reserved for implementation-owned scratch accounts used by Global probing and publication. All authorized callers, including Owner, receive Deployment name is reserved; Deployer authority cannot occupy either scratch account. Other deployment names retain the normal role checks.

deploy accepts full_access_keys: Deployer can install keys it controls and therefore control the child accounts, including replacing their code. Treat this role as account-creation authority, not merely permission to select approved code.

Only duplicate pending uploads are refused. The same bytes may be uploaded again after approval and registered under multiple version keys; there is no cross-history approved-hash ban or hash-index bootstrap. Successfully registered version keys remain occupied permanently, including after code removal. A failed Global probe preserves a matching upload and frees its version key for retry.

Storage balances and upload lifecycle

All storage methods are public and independent of roles. Query storage_balance_bounds ({}) for {"min":"<yoctoNEAR>","max":null} and storage_balance_of ({"account_id":"<payer>"}) for the payer's total and available balances. The minimum locks exactly the storage for a fixed-size account ledger record; do not hard-code it. Call payable storage_deposit first, optionally naming account_id and registration_only. New registration at the minimum has zero available balance, so uploading also requires a top-up for actual map/key/uploader/blob storage. Repeated registration_only:true on an already registered account refunds the entire attached deposit.

upload_code attaches zero NEAR and charges the predecessor's available balance. Uploaded approval moves the bytes into a version: the original payer remains charged for retained code until remove_version actually removes it. If the version key and version-storage entry exceed the freed upload metadata, approval charges the net growth to the original payer; top up that payer's available balance first or approval fails without changing approval state. Freed upload metadata and any matching pending storage removed by successful Global or legacy registration are credited to the original payer. A current Uploader can call remove_upload for its own pending upload; Owner can remove any. Removal attaches exactly one yocto and credits the original payer's available balance, not the remover, without immediately transferring funds. Losing Uploader prevents removal until re-granted (Owner can still act).

storage_withdraw requires one yocto and transfers available balance (omit amount to withdraw all available). storage_unregister also requires one yocto: non-force unregister succeeds only once no code/storage charge remains beyond the registration minimum, then releases that reserve. Forced unregister is rejected for registered accounts; an unregistered account returns false. There is no code-deleting force option, nonrefundable upload fee, Owner skim, or new administrative withdrawal method: storage liabilities are user funds.

Solvency checks reserve registry-funded final deployment metadata before dispatch, and retain that budget until its callback succeeds or fails. They also reserve the maximum unallocated Owner/proposed-owner slot growth, so standard ownership methods cannot consume backing for withdrawable balances. A V2 upgrade batches deploy, migration, and private upgrade_check_storage in one receipt, including same-version upgrades: insufficient backing reverts the code change as well. Target registry releases must retain that private post-upgrade check. Attach 300 Tgas to upgrade: 200 Tgas is reserved for migration and 10 Tgas for the check, leaving room for decoding and deploying local code.

Roles, ownership, and migration

set_role(account_id, role, set, allow_removing_last_member) is Owner-only and requires exactly one yocto. role is "Uploader" or "Deployer", set defaults to true, and allow_removing_last_member defaults to false, following the RedStone adapter convention. Removing the last explicit member requires allow_removing_last_member:true. has_role and list_role(role, offset, count) report explicit membership only, even for Owner; Owner's action-guard bypass is not an implicit membership. get_upload returns only {uploader, code_len}, never bytes; list_uploads lists hashes with optional offset/count pagination.

The standard Owner API, including own_renounce_owner, remains available. Owner plus RBAC preserves existing own_* clients, storage, and two-step DAO handoff; an RBAC Admin-only design is viable but would introduce an unnecessary ownership API/storage cutover. Renunciation is possible, not prevented by this design; it removes Owner-only administration unless another authorized recovery path exists. Ownership transfer preserves explicit grants and moves Owner's action-guard bypass to the new Owner.

V1→V2 migration moves the historical version/registry map handles without rewriting entries or Owner slots and initializes empty uploads, version-payer records, and NEP-145 accounting. Historical code stays registry-funded. Typed Borsh storage keys preserve the legacy bytes Registry=0x72 (r) and Versions=0x76 (v), with Uploads=0x75 (u), UploadCode=0x63 (c) plus hash, StorageBounds=0x62 (b), StorageAccount=0x64 (d) plus account-ID hash, and VersionStorage=0x70 (p). The unreleased V2 layout does not imply either live registry has migrated. A same-V2 code-only upgrade uses empty migration args.

Interactions

The view examples below use near-cli-rs. The outputs are illustrative and abridged; the live call is authoritative.

List available versions

near contract call-function as-read-only \
    v1.tmplr.near list_versions \
    json-args '{"offset":0,"count":100}' \
    network-config mainnet \
    now

Illustrative output:

[
  "v20250811",
  "v1.1.0",
  "v1.2.1",
  "v1.3.0",
  "templar-proxy-oracle-near-contract@0.4.1#fb9b3b46bbedd16665dbc31f0efc605c8ef49acfa5ff17608fbc3b490b4a6cb3",
  "templar-proxy-oracle-near-governance-contract@0.3.1#40b1719a525dae7117a776ccefa281f97470e1213e83bbf054bd77eae5b0568a"
]

Most market versions are registered under vX.Y.Z keys; the legacy 1.0.0 build uses v20250811. Proxy oracle and governance builds use <package>@<version>#<sha256> keys. The mainnet deployment profile currently deploys new markets from v1.3.0 and pins the proxy oracle and governance builds shown above; other keys may exist. Released artifact hashes are recorded under contract/artifacts/releases/.

List deployments

near contract call-function as-read-only \
    v1.tmplr.near list_deployments \
    json-args '{"offset":0,"count":100}' \
    network-config mainnet \
    now

Illustrative output:

[
  "ibtc-iethusdc-1.v1.tmplr.near",
  "proxy-oracle-ibtc-iethusdc-1.v1.tmplr.near",
  "proxy-gov-ibtc-iethusdc-1.v1.tmplr.near",
  "ixlm-ixlmusdc-1.v1.tmplr.near",
  "proxy-oracle-ixlm-ixlmusdc-1.v1.tmplr.near",
  "proxy-gov-ixlm-ixlmusdc-1.v1.tmplr.near",
  "ixlmdejaaa-ixlmusdc-2.v1.tmplr.near",
  "..."
]

The list contains markets, proxy oracles, and proxy oracle governance contracts alike, since the registry deploys all three, and it includes deprecated markets that are still on chain. The call is paginated: count caps the page size, so if a page comes back full, request the next one with offset advanced by the page size and repeat until a page contains fewer than count entries. The markets currently offered in the app, and the deprecated ones, are listed on Smart Contract Addresses.

Read a deployment record

near contract call-function as-read-only \
    v1.tmplr.near get_deployment \
    json-args '{"account_id":"ixlmdejaaa-ixlmusdc-2.v1.tmplr.near"}' \
    network-config mainnet \
    now

Illustrative output:

{
  "version_key": "v1.3.0",
  "code_hash": "<base58 sha256 of the deployed WASM>",
  "block_height": "…"
}

version_key names the registered version the account was deployed from and code_hash is the hash of the bytes deployed. Compare the code hash with the released artifact manifests above, and use Contract Verification to verify the deployed bytes against their source. The record's types are documented in the API Reference.

Events

The registry logs NEP-297 events under the templar-registry standard. Events are version 1.0.0 except deployed, which is version 1.1.0. Each is logged by the receipt that makes its change, so an asynchronous step that later fails (a global contract that turns out not to exist, a deployment whose account creation fails) logs nothing. As with any NEAR event, count one only if its receipt succeeded: a receipt can still fail after logging, for example when the registry cannot stake the storage a new version needs, and NEAR keeps a failed receipt's logs.

EventFieldsLogged when
version_addedversion_key, code_hash, availability ({"Stored":{"code_len":…}} or "Global")Uploaded approval or legacy Stored registration stores code, or a callback confirms a global contract exists
version_removedversion_key, code_hashremove_version clears a version's stored code
deployedaccount_id, version_key, code_hash, block_height, deployer, full_access_keysthe deployed account is created and initialized and the name resolves to it
code_uploadedcode_hash, uploader, code_lencode and metadata are persisted and charged to the uploader's available storage balance
upload_removedcode_hash, uploadera pending upload is explicitly removed; approval/conversion emits no such event
role_setaccount_id, role ("Uploader" or "Deployer"), is_granted (boolean)every successful set_role, including idempotent calls

For deployed 1.1.0, new finalizers record the deploying predecessor and its supplied key list, including [] when no keys were supplied. Legacy in-flight finalizers did not carry that metadata, so both fields are null for them.

Owner changes are logged by near-sdk-contract-tools under its own standard.

The Rust variant is RegistryEvent::RoleSet { account_id, role, is_granted }; for example its NEP-297 data is {"account_id":"operator.near","role":"Uploader","is_granted":true}, under templar-registry, version 1.0.0.