[NEP-591]: Global Contracts #591

pugachAG · 2025-02-11T15:39:25Z

NEP Status (Updated by NEP Moderators)

Status: Review

SME reviews:

flmel · 2025-02-20T14:17:50Z

Hi @pugachAG – thank you for starting this proposal. As the moderator, I labeled this PR as "Needs author revision" because we assume you are still working on it since you submitted it in "Draft" mode.
Please ping the @near/nep-moderators once you are ready for us to review it.

walnut-the-cat · 2025-02-21T05:46:50Z

neps/nep-0591.md

+Global contract can be deployed in 2 ways: either by its hash or by owner account id.
+Contracts deployed by hash are effectively immutable and cannot be updated.
+When deployed by account id the owner can redeploy the contract updating it for all its users.


Can we talk about when to use each way? For instance, when should a user use hash instead of account id, and vice versa?

Sure, added in bfad2e3

Sorry to jump in, but I’m curious, will the deployed-by account ID receive a hash?

I don’t see a reason to allow someone to change my code and potentially take everything from my contract. But if a globally deployed account also gets a hash that I can lock onto (and update later if needed), that would be a nice DevX improvement.

I do see a downside, though that every update essentially creates a new copy of the code instead of replacing it. So I’m curious, how is this going to be addressed?

@akorchyn Nope, in this case we store account id, so the owner can update contract for all current users. There are underlying use cases for that, for example application developers onboarding users on NEAR.
Also it is possible to lock such contract if owner deletes all keys from the account, effectively making it impossible to make any changes.

neps/nep-0591.md

bowenwang1996 · 2025-02-28T16:42:32Z

As a working group member, I nominate @akhi3030 and @wacban as SME reviewers

akhi3030 · 2025-03-04T14:40:29Z

To help me schedule the work here, what is the deadline for this review?

pugachAG · 2025-03-06T11:56:50Z

@akhi3030 testnet release is scheduled for March 24th, so it would be nice to get this NEP reviewed by that that date.

neps/nep-0591.md

wacban

I had the first look, looks good so far, I'll come back to it some time this week.

wacban · 2025-03-10T11:56:20Z

neps/nep-0591.md

+}
+```
+
+Also new action is added for using previously deployed global contract:


Can you clarify that this action is the same / similar as deploying the contract directly to the account?

addressed in c528f22

wacban · 2025-03-10T11:56:53Z

neps/nep-0591.md

+```
+
+Also new action is added for using previously deployed global contract:
+


Is it possible to "unlink" the global contract from the account? Is it even possible for regular contracts? What about cleaning the state of the contract after it's removed?

As far as I know it is not possible to unlink the regular contract, so we don't have to solve that for the global contracts. The same applies for the state of the contracts.

wacban · 2025-03-10T12:09:44Z

neps/nep-0591.md

+`GlobalContractDistribution` receipt is generated as a result of processing `DeployGlobalContractAction`.
+Receipt distribution logic is updated to route such receipts to all shards.
+So effectively it is a part of `ShardProof` (incoming receipts) for each shard, but occurs only once in the outgoing receipts of that chunk.
+Applying `GlobalContractDistribution` receipt updates the corresponding `TrieKey::GlobalContractCode` in the trie.


It would be good to test that this logic works well in case of resharding. One particular corner case would be:

#10 - deploy smart contract in shard X

#11 - shard Y and shard Z are both missing chunk

#12 - new shard layout after resharding where Y was split into Y1 and Y2

For X = Y, X = Z, X != Y && X != Z

wacban · 2025-03-10T12:13:02Z

neps/nep-0591.md

+### Costs
+
+For global contracts deployment we burn tokens for storage instead of locking like what we do regular contracts today.
+The cost per byte of global contract code `global_contract_storage_amount_per_byte` is set as 10x the storage staking cost `storage_amount_per_byte`.


Is it set to 10x symbolically or do you just set its value to be 10x? I would suggest decoupling them so that they can be updated independently.

+1 to this comment.

global_contract_storage_amount_per_byte is a separate runtime parameter completely independent from storage_amount_per_byte, here I meant that initial values is set to be 10 * storage_amount_per_byte

neps/nep-0591.md

wacban · 2025-03-10T12:22:17Z

neps/nep-0591.md

+    /// Contract is deployed under the owner account id.
+    /// Users will be able reference it by that account id.
+    /// This allows the owner to update the contract for all its users.
+    AccountId,


Does deploying a global contract by account id deploy said contract to the owner account as well?

nope, it does not do that

wacban · 2025-03-10T12:25:50Z

neps/nep-0591.md

+Global contract has to be distributed to all shards after being deployed.
+This is implemented with a dedicated receipt type:


Is this accounted for in the BandwidthScheduler?

implemented as part of near/nearcore#13147

akhi3030

generally looks good to me and I am happy for it to proceed with the current spec. I will do a detailed SME review soon.

akhi3030 · 2025-03-12T13:51:33Z

neps/nep-0591.md

+### Costs
+
+For global contracts deployment we burn tokens for storage instead of locking like what we do regular contracts today.
+The cost per byte of global contract code `global_contract_storage_amount_per_byte` is set as 10x the storage staking cost `storage_amount_per_byte`.


+1 to this comment.

Co-authored-by: Adam Chudaś <[email protected]>

wacban

As a subject matter expert I approve this NEP.

It adds an important feature, it is well designed, it strikes a great balance between added complexity and practical aspects and it well integrates with the rest of nearcore. Thank you @bowenwang1996, @pugachAG and @stedfn for this great proposal.

wacban · 2025-03-21T12:10:52Z

neps/nep-0591.md

+`GlobalContractDistribution` receipt is generated as a result of processing `DeployGlobalContractAction`.
+Such receipt contains destination shard `target_shard` as well as list of already visited shard ids `already_delivered_shards`.
+Applying `GlobalContractDistribution` receipt updates the corresponding `TrieKey::GlobalContractCode` in the trie for the current shard.
+It also generates distribution receipt for the next shard in the current shard layout. This process continues until `already_delivered_shards` contains all shards.


One consequence of this approach is that global contract deployment will take at least num_shards blocks to get onto all shards. In the future we may need some way of checking if the contract is fully deployed / updated. Nothing to worry about now, I'm sure the contract developers will ask about it once they need it.

Indeed with more shards in the future propagating global contract updates might take quite some time.
We can extend the functionality in the future by adding some deployment progress indicator as part of owners account id data if that would be required.

wacban · 2025-03-21T12:12:43Z

neps/nep-0591.md

+We change `Account` struct to make it possible to reference global contracts.
+`AccountV2` is introduced changing `code_hash: CryptoHash` field to more generic `contract: AccountContract`:
+
+```rust
+enum AccountContract {
+    None,
+    Local(CryptoHash),
+    Global(CryptoHash),
+    GlobalByAccount(AccountId),
+}
+```


Will it be possible to deploy / use global contracts from accounts created before AccountV2 is released? Is there any migration / lazy update necessary?

AccountV2 is released along with global contract.
User account is upgraded to V2 lazily when global contract is used, so no migration is required.

Related code in nearcore: https://github.com/near/nearcore/blob/a0d02a27cd68ed4e6ffda8b4a323d53f808d3c0e/core/primitives-core/src/account.rs#L272

render bot deployed to global-contracts - nomicon PR #591 February 11, 2025 15:39 View deployment

pugachAG mentioned this pull request Feb 11, 2025

[Tracking] Global contracts near/nearcore#12639

Closed

pugachAG force-pushed the global-contracts branch from aa2970e to 650b881 Compare February 11, 2025 16:08

render bot deployed to global-contracts - nomicon PR #591 February 11, 2025 16:08 View deployment

pugachAG force-pushed the global-contracts branch from 650b881 to 39b0c80 Compare February 12, 2025 19:01

render bot temporarily deployed to global-contracts - nomicon PR #591 February 12, 2025 19:01 Destroyed

pugachAG force-pushed the global-contracts branch from 39b0c80 to b4df91c Compare February 12, 2025 19:03

render bot temporarily deployed to global-contracts - nomicon PR #591 February 12, 2025 19:03 Destroyed

pugachAG force-pushed the global-contracts branch from b4df91c to 6abff6a Compare February 12, 2025 19:04

render bot temporarily deployed to global-contracts - nomicon PR #591 February 12, 2025 19:04 Destroyed

impl

424159e

pugachAG force-pushed the global-contracts branch from 6abff6a to 424159e Compare February 13, 2025 08:24

trechriron deployed to global-contracts - nomicon PR #591 February 13, 2025 08:24 — with Render View deployment

flmel added S-draft/needs-author-revision A NEP in the DRAFT stage that needs an author revision. A-NEP A NEAR Enhancement Proposal (NEP). labels Feb 20, 2025

flmel changed the title ~~[WIP]: Global Contracts~~ [NEP-591]: [WIP] Global Contracts Feb 20, 2025

walnut-the-cat reviewed Feb 21, 2025

View reviewed changes

neps/nep-0591.md Show resolved Hide resolved

[NEP-591]: global contract usage cost description (#595)

4c3a980

trechriron deployed to global-contracts - nomicon PR #591 February 21, 2025 13:35 — with Render View deployment

update usage costs section

610dbc4

trechriron deployed to global-contracts - nomicon PR #591 February 21, 2025 13:41 — with Render View deployment

more details for contract types

bfad2e3

trechriron deployed to global-contracts - nomicon PR #591 February 21, 2025 13:49 — with Render View deployment

Add Future possibilities

053cb24

trechriron deployed to global-contracts - nomicon PR #591 February 21, 2025 14:05 — with Render View deployment

pugachAG changed the title ~~[NEP-591]: [WIP] Global Contracts~~ [NEP-591]: Global Contracts Feb 24, 2025

wacban reviewed Mar 10, 2025

View reviewed changes

neps/nep-0591.md Outdated Show resolved Hide resolved

wacban reviewed Mar 10, 2025

View reviewed changes

akorchyn mentioned this pull request Mar 11, 2025

Add support for DeployGlobalContract and UseGlobalContract actions near/near-cli-rs#458

Open

akhi3030 approved these changes Mar 12, 2025

View reviewed changes

nep-491 description

850dcf4

Co-authored-by: Adam Chudaś <[email protected]>

trechriron deployed to global-contracts - nomicon PR #591 March 17, 2025 20:08 — with Render View deployment

address comment

c528f22

trechriron deployed to global-contracts - nomicon PR #591 March 17, 2025 20:14 — with Render View deployment

typo

f373635

trechriron deployed to global-contracts - nomicon PR #591 March 17, 2025 20:20 — with Render View deployment

update distribution

431520e

trechriron deployed to global-contracts - nomicon PR #591 March 17, 2025 20:33 — with Render View deployment

Merge branch 'master' into global-contracts

ad67f3c

trechriron had a problem deploying to global-contracts - nomicon PR #591 March 20, 2025 12:36 — with Render Failure

Merge branch 'master' into global-contracts

4ff27a8

trechriron had a problem deploying to global-contracts - nomicon PR #591 March 20, 2025 18:26 — with Render Failure

update LastUpdated

865c66a

trechriron had a problem deploying to global-contracts - nomicon PR #591 March 20, 2025 19:08 — with Render Failure

Update status

f9ed471

trechriron had a problem deploying to global-contracts - nomicon PR #591 March 20, 2025 19:11 — with Render Failure

wacban approved these changes Mar 21, 2025

View reviewed changes

Merge branch 'master' into global-contracts

bb1c050

trechriron had a problem deploying to global-contracts - nomicon PR #591 March 21, 2025 18:03 — with Render Failure

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[NEP-591]: Global Contracts #591

[NEP-591]: Global Contracts #591

pugachAG commented Feb 11, 2025 •

edited by wacban

Loading

flmel commented Feb 20, 2025

walnut-the-cat Feb 21, 2025

pugachAG Feb 21, 2025

akorchyn Mar 5, 2025

pugachAG Mar 17, 2025 •

edited

Loading

bowenwang1996 commented Feb 28, 2025

akhi3030 commented Mar 4, 2025

pugachAG commented Mar 6, 2025 •

edited

Loading

wacban left a comment

wacban Mar 10, 2025

pugachAG Mar 17, 2025

wacban Mar 10, 2025

pugachAG Mar 10, 2025

wacban Mar 10, 2025

wacban Mar 10, 2025

akhi3030 Mar 12, 2025

pugachAG Mar 17, 2025

wacban Mar 10, 2025

pugachAG Mar 17, 2025

wacban Mar 10, 2025

pugachAG Mar 17, 2025

akhi3030 left a comment

akhi3030 Mar 12, 2025

wacban left a comment

wacban Mar 21, 2025

pugachAG Mar 21, 2025

wacban Mar 21, 2025

pugachAG Mar 21, 2025

pugachAG Mar 21, 2025

		```

		Also new action is added for using previously deployed global contract:

		Global contract has to be distributed to all shards after being deployed.
		This is implemented with a dedicated receipt type:

[NEP-591]: Global Contracts #591

Are you sure you want to change the base?

[NEP-591]: Global Contracts #591

Conversation

pugachAG commented Feb 11, 2025 • edited by wacban Loading

NEP Status (Updated by NEP Moderators)

flmel commented Feb 20, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pugachAG Mar 17, 2025 • edited Loading

Choose a reason for hiding this comment

bowenwang1996 commented Feb 28, 2025

akhi3030 commented Mar 4, 2025

pugachAG commented Mar 6, 2025 • edited Loading

wacban left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

akhi3030 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wacban left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pugachAG commented Feb 11, 2025 •

edited by wacban

Loading

pugachAG Mar 17, 2025 •

edited

Loading

pugachAG commented Mar 6, 2025 •

edited

Loading