Global Contracts

​

Key Features

• Global Addressing: Code is identified by its hash or publisher account ID. Accounts reference that identifier through UseGlobalContract, then receive calls at their own account IDs.
• Code Versioning: A reference by hash pins immutable code. A reference by publisher account ID follows updates published under that ID.
• Shared Infrastructure: Global contracts can act as canonical libraries, utility hubs, or standards for other contracts to rely on, simplifying development and reducing duplication.
• Independent Instances: Accounts reuse the same code while keeping separate storage, balances, and application state. Calls between instances follow the usual cross-contract execution model.

​

Use Cases

• Standard Libraries: Reusable components for math, string operations, or token interfaces.
• DeFi Protocols: Global contracts can anchor DEXs, lending markets, oracles—shared across all applications.
• DAO Frameworks: Shared governance modules that any DAO can plug into, ensuring consistency and reliability.
• Identity & Credentials: Accounts can reuse identity verification and access management code while keeping their own state.
• Multi-part dApps: Complex applications can split responsibilities across shards while accessing a common logic core.

​

Solution

• By Account: an upgradable contract is published globally under a specific account ID.
• By Hash: an immutable contract is deployed globally and identified by its code hash.

​

Reference by Account

​

Reference by Hash

​

When to use Global Contracts

• Are you working in a local environment? If you’re just testing or building a prototype, regular deployments are simpler and more flexible. There’s no need to burn tokens or register global references — just deploy and iterate.
• Is the contract supposed to be deployed on many accounts? If the same contract will be reused across many independent accounts — say, 10 or more — Global Contracts can significantly reduce overall cost and complexity. But if only a few accounts are involved, regular deployment remains the more economical choice.
• Are these accounts managed by your team? If all target accounts are under your infrastructure, you may prefer regular deployments for flexibility and cost recovery.
• Are there more than 10 accounts? Global Contracts become financially efficient when reused at scale. If you’re deploying the same contract to more than 10 accounts, it’s likely worth considering.
• Do you need to upgrade the contract across many accounts in one step, even if it requires burning tokens? If you want to be able to push updates to all deployed instances at once, then go with Global Contracts by Account ID, but keep in mind that the deployment cost is non-refundable.
• Does your use case require the contract to be permanently immutable? If the contract must never change, for example, due to security, compliance, or user trust, then using a Global Contract by Code Hash ensures immutability at the protocol level.

​

Deploying a Global Contract

near contract deploy-as-global use-file <path-to-wasm> as-global-account-id <account-id> network-config testnet sign-with-keychain send

near contract deploy-as-global use-file <path-to-wasm> as-global-hash <account-id> network-config testnet sign-with-keychain send

let global_account_id: AccountId = account_id_string.parse().unwrap();
let global_code = std::fs::read("../contracts/contract.wasm").unwrap();
let global_signer = Signer::from_secret_key(private_key).unwrap();

// Deploy the global contract code using the account ID `nft-contract.testnet`
// This will deploy the contract to the specified account ID
// and return the final execution outcome
let result = Contract::deploy_global_contract_code(global_code)
    .as_account_id(global_account_id.clone())
    .with_signer(global_signer.clone())
    .send_to_testnet()
    .await
    .unwrap();

let account_id: AccountId = account_id_string.parse().unwrap();
let code = std::fs::read("../contracts/contract.wasm").unwrap();
let signer = Signer::from_secret_key(private_key).unwrap();

// Deploy the global contract code using a hash
// This will deploy the contract to the global contract hash
// and return the final execution outcome
let result = Contract::deploy_global_contract_code(code.clone())
    .as_hash()
    .with_signer(account_id.clone(), signer.clone())
    .send_to_testnet()
    .await
    .unwrap();

​

Using a Global Contract

near contract deploy <account-id> use-global-account-id <global-contract-account-id> without-init-call network-config testnet

near contract deploy <account-id> use-global-hash <global-contract-hash> without-init-call network-config testnet

// Please note that you have to trust the account-id that you are providing. As the code is mutable, the owner of the referenced account can
// change the code at any time which might lead to unexpected behavior or malicious activity.
let my_signer = Signer::from_secret_key(private_key).unwrap();

let result = Contract::deploy(new_account_id)
    .use_global_account_id(global_account_id)
    .without_init_call()
    .with_signer(my_signer)
    .send_to_testnet()
    .await
    .unwrap();

let code = std::fs::read("../contracts/contract.wasm").unwrap();
let global_hash = near_api::CryptoHash::hash(&code);

// Prepare a transaction to deploy a contract to the provided account using an immutable hash reference to the code from the global contract code storage.
let my_signer = Signer::from_secret_key(private_key).unwrap();

let result = Contract::deploy(new_account_id)
    .use_global_hash(global_hash)
    .without_init_call()
    .with_signer(my_signer)
    .send_to_testnet()
    .await
    .unwrap();

​

Updating global contracts