feat: add ergonomic API for global contracts #84
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Adds new ergonomic methods for global contract deployment: - Contract::publish_contract(code, account_id) - replaces 4 methods with cleaner 2-method API - DeployBuilder::deploy_from_published(reference) - unified method accepting hash or account ID Deprecated old methods (still functional): - Contract::deploy_global_contract_code() - DeployBuilder::use_global_hash() - DeployBuilder::use_global_account_id() Also fixes global contract tests by using neard 2.9.0 which includes NEP-591 support. Matches semantics from near-sdk-rs PR near/near-sdk-rs#1403
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
r-near
added a commit
to near/near-api-js
that referenced
this pull request
Nov 12, 2025
This PR adds a new ergonomic API for global contracts to match the near-sdk-rs API improvements from PR #1403. ## Changes ### New API Methods - `publishContract(code, accountId?)` - Publish contract code to global registry - Without accountId: Creates immutable contract (identified by code hash) - With accountId: Creates mutable contract (can be updated by owner) - `deployFromPublished(reference)` - Deploy from published code - Accepts Uint8Array (code hash), hex string (code hash), or account ID - Automatically detects reference type ### Deprecated Methods - `deployGlobalContract()` - Use `publishContract()` instead - `useGlobalContract()` - Use `deployFromPublished()` instead ### Other Changes - Added comprehensive tests for new API methods - Updated cookbook example to demonstrate new API - Old methods remain functional but marked as deprecated ## Migration Guide **Before:** // Deploy immutable contract await account.deployGlobalContract(code, "codeHash"); // Deploy mutable contract await account.deployGlobalContract(code, "accountId"); // Use by hash await account.useGlobalContract({ codeHash }); // Use by account ID await account.useGlobalContract({ accountId }); **After:** // Publish immutable contract await account.publishContract(code); // Publish mutable contract await account.publishContract(code, accountId); // Deploy from hash or account ID await account.deployFromPublished(codeHash); await account.deployFromPublished(accountId); Related PRs: - near-sdk-rs: near/near-sdk-rs#1403 - near-api-rs: near/near-api-rs#84
Addresses Codex feedback - split from_signer_account() into two methods: - from_any_account() for hash-based (None case) - from_account() for account-based (Some case) The from_account() method now properly binds the transaction to the account_id provided in publish_contract(), preventing mismatches where a different account could be passed to with_signer(). This matches the behavior of the old as_account_id() method.
Changed from confusing Option-based API to clear builder pattern: Before: - publish_contract(code, None).from_any_account() - publish_contract(code, Some(id)).from_account() After: - publish_contract(code).as_hash() - publish_contract(code).as_account(id) Benefits: - Single decision point (.as_hash vs .as_account) - Account specified where it matters - Impossible to misuse (no panics) - Clearer intent
Collaborator
|
I think we could also accept Vec, and it would be processed as LocalCode. So it would be I'm not convinced yet on the naming side, and I would wait until we have a consensus over it. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Adds ergonomic API for global contracts matching the semantics from near-sdk-rs PR #1403.
New API
Publishing contract code:
Deploying from published code:
Changes
Contract::publish_contract(code)with builder pattern.as_hash()for immutable deployment.as_account(account_id)for mutable deployment (transaction auto-bound to account)DeployBuilder::deploy_from_published(reference)- unified deployment methodIntoGlobalContractReftrait for type-safe referencesBenefits
.as_hash()or.as_account()at decision point.as_account()automatically binds transaction to accountMigration
Old methods are deprecated but still work:
deploy_global_contract_code().as_hash()→publish_contract(code).as_hash()deploy_global_contract_code().as_account_id(id)→publish_contract(code).as_account(id)use_global_hash(hash)→deploy_from_published(hash)use_global_account_id(id)→deploy_from_published(id)