Env usage localized in api.js

[volovyks]

• Env usage localized in api.js
• Stale and trivial low-level examples deleted
• Low-level nft and counter examples are rewritten (@ailisp do you think we should keep them? If so, I can write tests)
• Unit test scripts fixed (we should get updated SDK code on each run)

[volovyks]

@ailisp I'm not sure what should be done with this function call. The documentation says that it is used together with env.jsvm_call(...args), but we do not have it here.

Also, something I have noticed:

export function jsvmCall(contractName, method, args) {
    env.jsvm_call(contractName, method, JSON.stringify(args), 0)
    return JSON.parse(env.read_register(0) || 'null')
}

In this function we are using env.read_register(...args), not env.jsvm_value_return().

[ailisp]

@ailisp I'm not sure what should be done with this function call. The documentation says that it is used together with env.jsvm_call(...args), but we do not have it here.

My bad on describing the behavior. jsvm_value_return does: 1) store the return in a C static variable, so if this were called by another contract, that contract can retrieve this info. 2) plus the normal host function value_return.

This contract doesn't call other contract so there's no jsvm_call, but this contract could be called by another contract. Therefore, for any JS contract, jsvm_value_return should always be used instead of value_return.

In this function we are using env.read_register(...args), not env.jsvm_value_return().

env.jsvm_call saves the the return (if there were jsvm_value_return in the call) in both a C static variable and the given register:

// this is the env.jsvm_call
static JSValue near_jsvm_call(JSContext *ctx, JSValueConst this_val, int argc, JSValueConst *argv) {
  // ...
  jsvm_call(contract_name_len, (char *)contract_name_ptr, method_name_len, (char *)method_name_ptr, arguments_len, (char *)arguments_ptr, true); // inside jsvm_call, if there's a jsvm_value_return, it saves call return to a static variable and also call host's value_return
  jsvm_call_returns(&call_ret, &ret_len, GET); // get the return from that static variable
  write_register(register_id, ret_len, (uint64_t)call_ret); // save to given register
  // ...
}

If we just want to return the value to runtime, jsvm_value_return(value) would do that. If we want to further process this value, we need to read it from register (e.g. in jsvmCall)

[ailisp]

Great improvement to usability! We can be not care of low level APIs now and I'm going to replace them by near.* APIs in docs.

[ailisp]

Low-level nft and counter examples are rewritten (@ailisp do you think we should keep them? If so, I can write tests)

Rethink on this, now I prefer to drop them, or move them from examples to tests. Our low level rust contracts, are tests for the (nearcore) runtime, and not part of near-sdk-rs. If we have it here, we need some documentation describing env.* APIs and tech details on it. But we already decide to drop env.* from public APIs. They are more fit to near-sdk-js contributors than contract developers.

Whether we choose to drop or place some low level contracts as tests, nft and counter are not good test candidates that can be dropped now. What do you think?