Audit near-workspaces-rs feature gap for deprecation

[r-near]

Context

As part of the Rust DevTools maintenance transition, near-workspaces-rs is being deprecated in favor of near-api-rs + near-sandbox-rs.

Action

Document what near-api-rs + near-sandbox-rs cannot do today that near-workspaces-rs can.

Key items to audit:

• compile_project() — builds cargo project and returns wasm bytes
• dev_deploy() — quick contract deployment for testing
• fast_forward() — time manipulation in sandbox
• State spooning from testnet/mainnet
• GasMeter — gas consumption tracking
• Parallel test execution patterns
• Automatic account provisioning

Outcome

A clear feature-parity checklist that informs migration guide and identifies gaps to fill in near-api-rs.

Reference

• Slack thread: https://nearone.slack.com/archives/C0A64SAMDNG/p1767726931086969
• PR: Add NEAR Rust DevTools 2025 status update docs#2929

Priority: High

[vsavchyn-dev]

Contract compilation via compile_project()

Status: feature missing, but there is workaround.

Current state:

near-api-rs + near-sandbox-rs does not support programatic contract compilation like near-workspaces. However, compile_project() is under unstable feature flag in near-worksapces.

Despite that, both defuse team and rainbow bridge use cargo-near-build directly in their tests:

• omni-bridge: building with cargo-near-build and cargo-build cli tool
• intents: building with cargo-near-build cli via makefile

Implementation ideas:

Adding compile_project to either near-sandbox or near-api wouldn't be the best idea.

While adopting compile_project() into near-sandbox might make sense, burden of maintenance that comes with cargo-near-build might be not that desirable. Introducing compile_project() to near-api-rs would be diverging from the main purpose of near-api-rs.

With that, it should be encouraged and documented how to use cargo-near:

1. Use cargo-near cli tool in test suite to build contracts before execution integration tests in CI.
2. Use cargo-near-build to build contracts programatically in unit and integration tests.

[vsavchyn-dev]

Developer Contract Deployment dev_deploy()

Status: feature is not supported

Current state:

Idea behind dev_deploy() in near-workspaces is that it generates account for contract automatically with default private key and deploys contract. near-api-rs + near-sandbox-rs don't have this one-liner. Sandbox has sandbox.create_account(account_id) only, without possibility to deploy contract.

near-api will require you to use Contract::deploy(account_id) builder, again requiring to specify account id and init function and etc.

It is possible to generate secret key using near_api::signer::generate_secret_key()? and account_id via near_sandbox

Implementation recommendation:

Add GeneratedDeployBuilder , to enable creating developer account as follows:

// Will create GeneratedDeployBuilder, that later will create account_id and secret key
let builder: GeneratedDeployBuilder = Contract::dev_deploy(tla, contract_bytes);

let contract_deploy_no_init: ExecuteSignedTransaction = builder.clone().without_init_call();

let contract_deploy_init: SetGeneratedDeployActionWithCallBuilder = builder.clone().with_init_call(args)?

contract_deploy_no_init.send_to(&network).await?; 
// as we generate signer, it might be better to allow for some intermediate step to translate to `ExecuteSignedTransaction`, and allow user to get signer and account_id
contract_deploy_init.execute().send_to(&network).await?;

or singular function that is more similar to near-workspaces - this approach will result in the least amount of code duplication imo

// will use contract_bytes and network to deploy contract to randomly created account under top level account, with generated PK
let (contract, signer) = Contract::dev_deploy(tla, contract_bytes, &network).await?;

[vsavchyn-dev]

Fast forwarding blocks via fast_forward()

Status: feature is supported in near-sandbox-rs only

Current state:

This feature is supported in near-sandbox-rs, however there is no easy way to perform it via near-api

Implementation recommendation:

Maybe it will worth looking into implementing way to patching state in near-api? Not sure if it worth it and it has any place to be in near-api.

[vsavchyn-dev]

State spooning (importing Testnet/Mainnet state import)

Status: feature is supported

Current state:

As of now, user is able to fetch store of account by using near-api-rs Contract(account_id).view_storage().fetch_from_mainnet/testnet(), however, you can't patch state using near-api-rs into sandbox.

near-sandbox-rs supports fetching full state for account for specified network config via sandbox.import_account(rpc_url, account_id).send().await?. PatchState builder (sandbox.patch_state(account_id)) provides more flexibility on what you want to patch.

Implementation recommendation:

Might worth adding a sandbox feature flag to near-api-rs, that enables sandbox state patching-related functions

#[cfg(feature = "sandbox")]
impl Account {
    async fn patch_into_sandbox(&self, sandbox: &Sandbox) -> Result<()> {
        // Unified helper for sandbox_patch_state RPC
    }
}

[vsavchyn-dev]

Gas consumption tracking

Status: feature is not supported

Current state:

• near-workspaces-rs: Callback-based gas tracking on each transaction
• near-sandbox-rs: No equivalent
• near-api-rs: it's and rpc client to communicate w NEAR (it is not supposed to have gas metrics)

Challenges:

• Singleton pattern in near-sandbox-rs makes callback integration unclear
• Need design for how callbacks work with shared sandbox instance

Implementation recommendation:

This one requires design discussion. Possible approaches:

1. Per-test gas meter with explicit attachment to near-sandbox?
2. near-api function for ExecuteSignedTransaction to go through all receipts that transaction (and subsequent calls) will generate?
3. Explicit gas query API inside nearcore for sandbox feature instead of automatic tracking?

[vsavchyn-dev]

Parallel Test Execution Patterns

Status: full similarity to near-workspaces-rs

Current state:

There are mainly two patterns:

• Per-test sandbox: Each test spawns its own sandbox instance
• Singleton pattern: Shared sandbox across tests (more resource-efficient)

Both defuse team and rainbow bridge use singleton pattern:

• omni-bridge: building with cargo-near-build and cargo-build cli tool
• intents: building with cargo-near-build cli via makefile

Implementation recommendation:

Document both patterns with examples showing resource trade-offs:

• Singleton: Lower memory, shared state concerns
• Per-test: Isolated but higher overhead

[vsavchyn-dev]

Automatic Account Provisioning

Status: feature is not supported

Current state:

• near-workspaces-rs: dev_create_account() or dev_create_tla() for random accounts.
• near-sandbox-rs: Can generate Genesis accounts, account_id under sandbox, and secp keypair, but no dev account helper.
• near-api-rs: Has most of the dependencies ( under generate feature from near-sandbox) but no helper functions.

Implementation recommendation

Add dev account generation for near-sandbox-rs under generation feature (or remove generation feature), and near-api-rs under sandbox flag:

// near-sandbox-rs
#[cfg(feature = "generate")]
impl Sandbox {
    pub async fn create_dev_acc(&self) -> Result<(AccountId, String), SandboxRpcError> {
        let account_id = config::random_account_id();
        let (secret_key, public_key) = config::random_key_pair();

        AccountCreation::new(account_id.clone(), self)
            .public_key(public_key)
            .send()
            .await?;

        Ok((account_id, secret_key))
    }
}

[r-near]

1. compile_project - yeah I don't think it makes sense to include this, especially if cargo near can handle this. Let's just document this in near-api-rs and provide some examples on how to actually use it.

2. dev_deploy() - I think we should consider not hiding the implementation details from the user. I actually think the user should have to perform a create account and deploy contract action, just as they would in prod. So probably this feature isn't THAT necessary. I do think helpers to auto-generate random keys (and save them) would be useful. I never really liked dev_deploy - too much hidden behavior for me

3. fast-forward - IMO we shouldn't include this in near-sandbox-rs. This is an RPC method that should be called by near-api-rs. near-sandbox-rs should be a very scoped/focused package: it should download the sandbox binary, manage the singleton, and enable restarts. It shouldn't be concerned with how we talk to it (that's the RPC's job). Same with patch_state btw - this should be the job of the API crate, NOT the sandbox crate.

4. state spooning - Ok so we're just missing that RPC method? We should definitely add it. As for naming, let's just make it patch_state.

5. How does gas tracking work? I was under the impression it was part of the RPC responses? Couldn't that be done in near-api-rs?

6. Parallel test execution - perhaps we offer a singleton mode? I know Defuse in particular really wanted that

7. Account Provisioning - I'm actually not that keen on this, but open to partner feedback. IMO it hides implementation details that it shouldn't. What if we just offer a helper method to generate a random key and even a random account ID if they really want, but still force them to use the same create_account interface.

---

A theme I'm noticing is that there's some overlap in responsibilities between near-sandbox-rs and near-api-rs. I think we first need to delineate clear responsibilities, or we'll just end up turning near-sandbox-rs into near-workspaces. Speaking to the broader goal: near-api-rs is intended to be the canonical RPC client for Rust. Therefore, anything that interacts with the RPC should be the responsibility of near-api-rs. IMO near-sandbox-rs should be a very simple tool that just manages the neard binary for you: creates the tmp dir, launches localnet, etc. But to interact with the blockchain itself, you must use the RPC. And to use the RPC, you have near-api-rs (or near-cli, which would eventually use near-api-rs).

The goal should be: no magic, explicit RPC calls, clear separation of concerns.

[vsavchyn-dev]

I will add partner feedback to #13 too, so we will be able to understand the best way to go for some of those issues.

@r-near 1. compile_project - yeah I don't think it makes sense to include this, especially if cargo near can handle this. Let's just document this in near-api-rs and provide some examples on how to actually use it.

I agree on that. +1 req to #13

@r-near 2. dev_deploy() - I think we should consider not hiding the implementation details from the user. I actually think the user should have to perform a create account and deploy contract action, just as they would in prod. So probably this feature isn't THAT necessary.

While I understand that it is nice to enable customization of account creation, but I believe the main problem with that is that always writing balance for account, custom key, and etc is annoying when you write tests. I think people mostly concern themselves with "does it work" questions when creating integration tests for contracts. Hence, the proposed GeneratedDeployBuilder sounds like the best balance between the customizability and easiness to use for devs IMO.

@r-near 3. fast-forward - IMO we shouldn't include this in near-sandbox-rs.

Yeah, maybe it would be better to put all sandbox-related methods under feature in near-api-rs. But what if we want to enable users to later manipulate sandbox with revert functionality for instance? It clearly shouldn't be a responsibility of near-api-rs

@r-near 4. state spooning - Ok so we're just missing that RPC method? We should definitely add it. As for naming, let's just make it patch_state.

same as above

@r-near 5. How does gas tracking work? I was under the impression it was part of the RPC responses? Couldn't that be done in near-api-rs?

It checks receipts after calls to contract and then displays total, so yeah, part of the RPC responses. But it would be better to address it somewhere in core level or add more sophisticated way of reporting/checking it with near-api-rs...

@r-near 6. Parallel test execution - perhaps we offer a singleton mode? I know Defuse in particular really wanted that

I am not sure if it makes sense to add this directly to near-sandbox or making new crate that exposes near-sandbox + near-api-rs and provides rstest fixtures... It would make sense to go with second approach, as it might be the best way to offer singleton and sandbox-per-test/factory flavour of tests, while keeping near-sandbox small and concentrated on 1 thing - running neard without a problems for developers.

At the same time, we can see omni-bridge not having a problems with running near-sandbox in parallel

@r-near 7. Account Provisioning - I'm actually not that keen on this, but open to partner feedback. IMO it hides implementation details that it shouldn't.

As we can see from Defuse team, they are creating random user for test purposes (I found like 98 references to this function). But as you said, the pattern is actually to generate account id and add desired balance for account to have. Signer/secret key is generated as well.

What if we just offer a helper method to generate a random key and even a random account ID if they really want, but still force them to use the same create_account interface.

We already have random_account_id and random_key_pair in near-sandbox and generate_secret_key in near-api-rs. SO I guess we can introduce generate_account_id for near-api-rs for that purpose.

[r-near]

I believe the main problem with that is that always writing balance for account, custom key, and etc is annoying when you write tests [...] Hence, the proposed GeneratedDeployBuilder sounds like the best balance between the customizability and easiness to use for devs IMO

Yes - you're right. I was being too much of a "purist". Those methods are genuinely helpful.

---

what if we want to enable users to later manipulate sandbox with revert functionality for instance

That depends how this feature gets implemented. Would revert be called via RPC? I think near-api-rs makes sense there. But what if we did it in userspace where we just snapshot the RocksDB database and copy it? Then yeah, definitely doesn't make sense to put that in near-api-rs.

---

It checks receipts after calls to contract and then displays total, so yeah, part of the RPC responses

I wonder...how useful of a feature is this? Didn't Defuse say they tried it but didn't find much value?

[r-near]

We already have random_account_id and random_key_pair in near-sandbox and generate_secret_key in near-api-rs. SO I guess we can introduce generate_account_id for near-api-rs for that purpose.

Too much sprawl - let's decide on one place to put it and consolidate everything.

[vsavchyn-dev]

I wonder...how useful of a feature is this? Didn't Defuse say they tried it but didn't find much value?

While it still looks like estimating how much gas it would take for a function call, it would be more useful rather than calculating it yourself. Regarding Defuse's team feedback, I believe that they said workspaces-rs version was not that useful as there were some features were missing. For instance - checking gas consumption per receipt or per action.