v1.3.0

Release v1.3.0 changes

• Crates versions bumped to "v1.3.0", runtime spec version bumped to 1300 (#3869);
• Weights of extrinsic and WASM calls WERE updated (#3876), schedule version bumped to 1300 in order to re-instrument codes with CHEAPER costs;

Update requirements

Name	Character
JS clients	⚪ Insubstantial
Programs	🟡 Recommended
Node bin	🔴 Required

User-space

📚 gtest now uses real instruction costs for its executions, so charging has became more like on-chain (#3808);

---

📚 Fixed gtest bug caused panic in tests on zero balance call of gr_exit() (#3848);

---

📚 Fixed gear-wasm-builder bug caused compile problems when following gear-wiki steps (#3864);

---

📚 Added new function to gtest that allows to query already submitted within the system code by it's code id (#3878);

Tip

It's interface looks like following code snippet:

let mut sys = gtest::System::new();

// ...
// Uploading some code here, and storing code_id
// ... 

let _code: Vec<u8> = sys.submitted_code(code_id).unwrap();

---

📚 Error type of gstd containing reply error code was extended (#3808);

Note

Async futures of gstds "for_reply" sendings now in case of error return not only error reply code, but the payload as well, so even general case of unwrapping communication result become more informative.

Runtime

📚 Node client was highly optimised in terms of executing programs and initialising WASM modules on-chain (#3801);

Note

Now it uses in-memory LRU caching instead of legacy variant of always touching disk space. This significantly decreases execution costs, but increases load on hardware RAM, which is totally safe since it limited in a conservative way. Previous approach still valid and will be dynamically turned on in case of any problems with RAM caching.

---

📚 Instrumented on-chain codes now always contain stack end parameter that optimises its handling and increases pallets simplicity and safety (#3811);

Key-features of the release

📚 Gear repo migrated to a new fork (polkadot-sdk) and updated used substrate version to v1.1.0 (#3814);

Important

Please make sure everything you use as standard substrate interface is properly migrated in your JS applications.

🔥📖 First builtin actor implemented 🥳 (#3771);

Note

Basing on #3624 (look up release v1.2.0 for details), the first actor will be available on-chain by its unique account id that could be queried in a decentralised and trusted way by RPC call of pallet-gear-builtin. This actor implements logic of bls12-381 interfaces that are executed outside of WASM runtime, so they're cheap and fits in a block a lot of times, which wasn't previously possible. Any actor (especially programs) may send request for calculations to the actor and wait for reply with results if enough gas was applied, so be care there!

Tip

Having such basic and useful cryptography makes real a lot of scenarios of web2 to be implemented on-chain!

Important

Calculations of this builtin are implemented with runtime interface of the node, so upgrade of your node client is MUST TO UPDATE in order to be able import blocks or keep online. Nodes replacement must be preformed before upgrades of the network.

Full Changelog: v1.2.1...v1.3.0

v1.2.1

Release v1.2.1 changes

• Crates versions bumped to "v1.2.1", runtime spec version bumped to 1210;

Update requirements

Name	Character
JS clients	⚪ None
Programs	⚪ None
Node bin	⚪ None

Runtime

📚 Bug fixes and stability improvements

Full Changelog: v1.2.0...v1.2.1

v1.2.0

Release v1.2.0 changes

• Crates versions bumped to "v1.2.0", runtime spec version bumped to 1200 (#3806);
• Weights of extrinsic and WASM calls was NOT updated, schedule version bumped to 1200 to force new checks (#3806);
• ⚠️ Gas price multiplier dumped from 25 value per gas to 6 value per gas, so all transactions and execution become 4x+ times cheaper in terms of tokens (#3806).

Update requirements

Name	Character
JS clients	⚪ Insubstantial
Programs	⚪ Insubstantial
Node bin	🟡 Recommended

User-space

📚 All requirements for codes to be uploaded now checked at compile time using gear-wasm-builder (#3649);

---

📚 Errors related to incorrect codes uploaded now contain a full description and become more user friendly (#3695, #3757);

---

📚 Gas limit argument become optional if using gcli for submitting transactions (#3753);

Note

Previously, if passed --gas-limit=0 or skipped, than rpc call calculate_gas took place. Now this behaviour was changed: if explicitly set --gas-limit=0 than zero is used, while if skipped - it will be calculated.

Runtime

📚 Bug of returning Error::DuplicateWake between program executions was fixed (#3475);

Note

Previously, flow of program execution wake(x) -> wait/wake(self) -> wake(x) was returning error on the last wake, while now it properly wakes the message.

Important

Don't forget that waking the same message within one execution (wake(x) -> wake(x)) is still an error and will be like that according to protocol design.

---

📚 Bug of missing re-instrumentation in reading state RPC calls, resulting in inability to read state, was fixed (#3759);

---

📚 Bug of returning block gas limit from calculate gas RPC call in case of finite waits was fixed (#3780);

---

📚 Bug of expiring payload while gr_send_commit results in an error was fixed (#3785);

---

📚 The total amount of outgoing bytes was limited to prevent validators memory overflow (#3743);

Important

While amount of outgoing messages allowed within one message is kept the same - 1024 pcs, total amount of bytes kept in memory at the same time for sendings was limited by 64MB.

Warning

If your program was sending more than 64MB within one execution, it won't work on upgrade. Make sure to migrate it in time.

⚠️ New code restrictions

📚 Now it's unable to upload or use codes that declare export as imports (#3694);

---

📚 Now it's unable to upload or use codes that declare data section outside static memory: 0..WASM min memory pages, (#3733);

---

Warning

If your program doesn't fit in new restrictions, on upgrading runtime to this version, it will stop working.
Make sure to migrate it in time.

Key-features of the release

📚 New RPC call gear_calculateReplyForHandle was implemented (#3790);

Tip

This RPC call accepts arguments similar to Gear::send_message extrinsic and allows to run queue with the message to collect reply details: payload, value and reply code. Combination of this with gas calculation will serve a great UI/UX for your dApp!

Note

None of the changes will be applied to the blockchain database. It's usage only for informational/query purposes to "predict" reply for such sending.

Important

RPC call related to gas calculation kept the same, but now has aliases. These aliases soon will become defaults and legacy names will be deprecated, so it's recommended to change your client code for new approach. Checkout following snapshot:

- gear_calculateInitCreateGas
+ gear_calculateGasForCreate

- gear_calculateInitUploadGas
+ gear_calculateGasForUpload

- gear_calculateHandleGas
+ gear_calculateGasForHandle

- gear_calculateReplyGas
+ gear_calculateGasForReply

🔥📖 Rent distribution was redesigned (#3686);

Note

There are some rents presented in Gear protocol: rent for storing message in Waitlist, Mailbox and DispatchStash (delayed sending), rent for storing gas reservation for the program. They're reserving some gas for future payment on elements entry into that paid storage. Once removed from the storage, reserve was used to pay exact amount for blocks held in there: it has been sending to the current block producer, that's a little unfair, while still approximated on a long distance.

New behaviour implements special pool for such charges, which is now split between all validators at the end of each era, according to their era points!

🔥📖 Module for adding builtin actors was implemented (#3624);

Note

Now it's possible to derive some program ids to dedicated parts of the runtime that has access to any data and calls of the runtime. Furthermore, it will be visible for existing programs.

For example, this module will allow staking builtin actor to be implemented, so the programs will be able to stake their balance just as like as real users do!

Full Changelog: v1.1.1...v1.2.0

v1.1.1

Release v1.1.1 changes

• Crates versions bumped to "v1.1.1", runtime spec version bumped to 1110;
• Weights of extrinsic and WASM calls updated, schedule version bumped to 1110.

Update requirements

Name	Character
JS clients	⚪ Insubstantial
Programs	⚪ Insubstantial
Node bin	⚪ Insubstantial

User-space

📚 New testing function has been added to gtest that allows to assert that message panicked with specific string (#3670);

Tip

Check out following gtest API snapshot:

 let panic_msg = "panic!";
- assert_eq!(result.log().len(), 1);
-     assert!(matches!(
-         result.log()[0].reply_code(),
-         Some(ReplyCode::Error(ErrorReplyReason::Execution(
-             SimpleExecutionError::UserspacePanic
-        )))
-     ));
-     let payload = String::from_utf8(result.log()[0].payload().into())
-         .expect("Unable to decode panic message");
-     assert!(payload.contains(&format!("panicked with '{panic_msg}'")));
+ result.assert_panicked_with(panic_msg);

---

📖 New CLI util implementing keystore/keyring has been added: gring (#3619);

---

📚 Crates.io bug with gtest on v1.1.0 version fixed (#3704);

Runtime

📚 Programs code reinstrumentation failure no longer supposed to be unreachable so from now on handled as succeeded error case (#3690);

Note

This increases stability of the protocol and adds more recovery cases from some state invalidity.

---

📖 Added ability to decline a voucher issued for you, marking it expired (#3725);

Tip

This significantly increases UX of signless apps.

Full Changelog: v1.1.0...v1.1.1

v1.1.0

Release v1.1.0 changes

• Crates versions bumped to "v1.1.0", runtime spec version bumped to 1100 (#3679);
• Weights of extrinsic and WASM calls updated, schedule version bumped to 1100 (#3677).

Update requirements

Name	Character
JS clients	🔴 Required
Programs	🟡🔴 Recommended / Required
Node bin	⚪ Insubstantial

User-space libraries

📖 New syscall gr_env_vars() that allows to query some actual blockchain parameters added (#3403);

Tip

Check out following gstd API snapshot:

use gstd::exec;

let vars = exec::env_vars();

// Current multiplier percent recommended to use with explicit gas amounts.
let _ = vars.performance_multiplier;

// Current value of existential deposit (minimum balance).
let _ = vars.existential_deposit;

// Current value of mailbox threshold (minimum gas applied for message to user to be inserted into `Mailbox`).
let _ = vars.mailbox_threshold;

// Current value of gas multiplier (how much value, where value is 10^(-12) Token, is in a single gas).
let _ = vars.gas_multiplier;

---

📖 Crate level documentation added for gtest (#3419, #3511);

---

* Public gsdk API functions that returns WS subscriptions were renamed (#3456);

Tip

blocks and finalized_blocks changed to subscribe_blocks and subscribe_finalized_blocks accordingly:
Check out following gsdk API snapshot:

use gsdk::Api;

let api = Api::new(None).await?;
- let blocks = api.blocks().await?;
+ let blocks = api.subscribe_blocks().await?; 
     
while let Ok(block) = blocks.next().await {
     // .. // 
}

---

📖 All usages of Rust nightly's features moved under each own gstd feature, general feature "nightly" that enables all of the others added as well (#3470);

Warning

It may break compilation: please, doublecheck your features set of gstd import according to latest docs.
As well as It mayn't cause users due to changes about compiling below.

---

📚 Recommended nightly toolchain is downgraded to nightly-2023-09-05 (#3536);

Note

It won't cause users due to changes about compiling below.

---

📚 Added ability to pre-process out binary in gear-wasm-builder if not shortcuts used (#3538);

---

📚 New syscall free_range that allows to free multiple pages at once added (#3467);

Note

This syscall is now used in lates versions of default galloc allocator for gear programs, so its usage become cheaper (#3611).

---

📚 Added ability to derive custom CLI applications based on gcli commands (#3573);

---

📚 Logging for uploaded program id added in gcli (#3568);

---

📚 Added dbg! macro for gstd (#3610);

Note

Its usage is identical to Rust std one: link

---

📚 Time-limited wait of programs now will be handled and processed by gtest (#3605);

---

📚 Timestamp increase for each block for gtest set same as for real chain: 3 sec per block (#3516);

---

📖 gstd now has critical hooks: the code guaranteed to be executed even if panic occurs (#3503);

Tip

This API allows to revert state changes applied if something went wrong with business process.
Check out a small demo and dive into gstds module docs for more info:

use gstd::{critical, msg};

#[gstd::async_main]
async fn main() {
    let source = msg::source();

    critical::set_hook(move || {
        msg::send(source, "I failed :c", 0).expect("Failed to send emergency message");
    });

    let reply = msg::send_for_reply(source, "Say my name", 0, 0)
        .expect("Failed to send message")
        .await
        .expect("Received error reply");

    // here goes "reply" processing //

    // processing ends panicking,
    // but user guaranteed to receive emergency message.
}

🥳 Stable compiler

📖 Several panic handler verbose modes introduced through gstd features, allowing to optimally extract panic message even without nightly features, moreover panic handler no longer depend on compile mode or "debug" feature (#3527)

Tip

gstd panic format: panicked with '{message}'[ at '{location}']: location is optional. Note that resulting error reply with panic will have prefix Panic occurred: as well. This formatting is similar to Rust defaults.

gstd panic handler lvls:

• panic-handler: message <unknown> without location;
• panic-message: message from panic info without location; (!) [NEW gstd DEFAULT]
• panic-location: message and location from panic info.

Nightly features optimise panic message extracting, but are no longer required.

Important

This changes allow building gear programs with Rust stable toolchain!

---

📖 Usage of actual toolchain for building with gear-wasm-builder added (#3459).

Important

Previously compilation of program using gear-wasm-builder were forcing using nightly toolchain from your system. It caused a lot of limitations, problems and legacy code. Even if you were building your crate as cargo +nightly-z-y-x build it called just cargo +nightly build etc.
Now it will compile with toolchain that you specify in your cargo command. Furthermore, since gear programs are compiled with stable toolchain: this method is now strongly recommended! Don't forget to adjust your scripts and actions.

Note

gear_wasm_builder::build() uses your given toolchain: (!) [NEW gear_wasm_builder DEFAULT]
gear_wasm_builder::recommended_nightly() uses your given toolchain but checks if it matches recommended nightly: for cases if you use nightly features and want to keep toolchain on recommended by core.

🥳 Crates.io

📖 All of gear programs user-space libraries now published on crates.io (#3103, #3515, #3594, #3629).

Tip

Now it's possible to import these packages as any other Rust ones in your toml. Say no to GitHub refs!

[dependencies]
galloc = "1.1.0"
gcli = "1.1.0"
gclient = "1.1.0"
gcore = "1.1.0"
gear-wasm-builder = "1.1.0"
gmeta = "1.1.0"
gsdk = "1.1.0"
gstd = "1.1.0"
gtest = "1.1.0"

Important

An error occurred while publishing side-dependencies, so if you face some issues with version "1.1.0" use "1.1.1-rc.0" instead.

Runtime

📖 Program memory pages storage are now represented as triple map (#3166);

Warning

It causes ProgramStorage as well as MemoryPages storage: keeping relations changed from program id -> page number to program id -> session id -> page number
It may brake your JS code!

---

📚 Stack limitations are precised for more stable behaviour of the system (#3462);

---

📚 Added create Numerated as initial step of road to 4GB memory limitation for programs (#3471);

---

📚 Codes with non-empty WASM functions inputs and outputs of gear entry points are now rejected by the system on upload (#3559);

Note

Such WASMs may be produced by the aim only, common recommended flow is correct.

---

📚 Added StakingAdmin origin for pallet-staking to be used from governance (#3633);

---

📖 Current rent functionality is now removed (#3590);

Note

Keeping programs on-chain is now totally free in order to implement more optimal solution proposal.

---

📖 Added revokable functionality for vouchers (#3606);

Important

It may break your JS code!

• Previous flow was deprecated and APIs removed.
• Check out new extrinsics and their docs at pallet-gear-voucher.
• Previously issued voucher couldn't be revoked and is still supported: it's recommended to finish them until upcoming releases.
• Vouchers now can be used for Gear::upload_code as well (#3672).

---

📖 Removed support for syscall gr_pay_program_rent, since program rent is removed (#3664);

Important

It invalidates any uploaded program that uses this syscall - they won't be able to execute! Make sure to migrate them until runtime upgrade to current release.

🥳 Calculate gas RPC calls bug fixes

📚 Fixed bug of incorrect calculations for rare waiting cases (#3609);

---

📚 <wasm:stripped> is no longer returned: extrinsic errors are printed properly with dedicated format (#3655);

Tip

Check out details in pull request description.

---

📚 Gas calculation doesn't return error in any case for zero-balanced accounts (as well as for vouchers) (#3653);

Note

No new calls implemented. To calculate gas for voucher call use default gear api with your origin.

---

📚 Return error instead of invalid huge gas in case of failing init as well as for traps in handle (#3674).

Full Changelog: v1.0.5...v1.1.0

v1.0.5

Release v1.0.5 changes

• Crates and runtime version bumped to "1.0.5" (#3635).

Client updates required: NO
External node/runtime api changed: NO
Programs code refactoring level after update libs: NO

Runtime

• Runtime logic optimisations and stability improvements.

Full Changelog: v1.0.4...v1.0.5

v1.0.4

Release v1.0.4 changes

• Crates and runtime version bumped to "1.0.4" (#3630).

This release does not affect gear protocols execution layer or user space libraries, so there is no need to update programs.

Node binary updates: NOT NECESSARY
External node/runtime api changes level: PATCH

Node binary

• Execution strategies (as well as native execution) are deprecated (#3608).

The only option how to execute runtime now is wasm.

Runtime

• Cost of governance operations on Vara runtime reduced by 5 times (#3620).

• Fixed bug of incorrect post-calculation of Gear::runs extrinsic weight (#3535).

All of the explorers (e.g. polkadot.js.org/apps) now show block weight correctly.

• Substrate version bumped from v0.9.43 to v1.0.0 (#3608).

• pallet-im-online no longer keeps data of heartbeat in storage, migrations applied;
• Internal changes and improvement are present.

Full Changelog: v1.0.3...v1.0.4

v1.0.3

Release v1.0.3 changes

• Crates and runtime version bumped to "1.0.3" (#3522).

This release does not affect gear protocols execution layer or user space libraries, so there is no need to update programs.

Node binary updates required: RECOMMENDED.

External node/runtime api changed: MAYBE.

API was slightly changed according to substrate changes, may not require any updates at the moment.

Node binary

• Implemented new two-phase block proposing mechanism (#3558).

Patched substates default block proposer totally replaced with custom one. Gear block authorship now proposes block without Gear::run extrinsic (internal message queue processing with programs execution) in case of Gear::run took too long time to execute, instead of previous logic of dropping the whole block.

This unique mechanic makes Gear protocol implementors much more stable and fault-tolerant, even with weak hardware.

• Node code was adapted for new version of substrate (#3584).

Node binary argument --ws-port was renamed into --rpc-port, as well as --unsafe-ws-external into --unsafe-rpc-external.

Runtime

• Substrate version bumped from v0.9.41 to v0.9.42 (#3584).

Changed behaviour and named API of pallet-balances:

• Config, error names and constant changes;
• Change of fn set_balance() into fn force_set_balance() with different arguments (setting reserved balance now deprecated);
• For any pallet-balances interaction it's required to have balance greater or equal to existential deposit (10 Vara for Vara Network).

• Substrate version bumped from v0.9.42 to v0.9.43 (#3584).

Stakings "controller" instance was deprecated. Now "stash" and "controller" is the same.

Mentioned changes are not the only that were applied, but the most significant. It's strongly recommended to check compatibility of JS-related code

Full Changelog: v1.0.2...v1.0.3

v1.0.2

Release v1.0.2 changes

• Crates and runtime version bumped to "1.0.2" (#3436).

Client updates required: NO
External node/runtime api changed: NO
Programs code refactoring level after update libs: PATCH

Programs recommended compiler: nightly-2023-09-18

• Downgrade compiler version from nightly-2023-10-14 to nightly-2023-09-18 (#3451).

It's recommended to use toolchain files for such pins. For more details see: https://rust-lang.github.io/rustup/overrides.html

User-space libraries

• Fixed internal gtest bug that caused test panic in System::spend_blocks (#3481);
• Actualised gtests constants with real runtime (#3510).

Constants become public use gtest::constants and properly documented.
EXISTENTIAL_DEPOSIT bumped from 500 value to 10_000_000_000_000 value (10 tokens).

Runtime

• Fixed internal runtime bug that caused ignore keep_alive field of send_message extrinsic while destination is user (#3458);
• Runtime logic optimisations and stability improvements.

Full Changelog: v1.0.1...v1.0.2

v1.0.1

Most significant changes

Runtime & node client

• Benchmark tasks and reduce GasAllowance accordingly (#2797)
• Add RPC call to query inflation and ROI (#3290)
• Stabilise lazy-pages feature (#3123)
• Add nonce to ProgramId generation (#3010)
• Add gas_allowance_multiplier argument for RPC-node clients (#3226)
• Introduce Vara Testnet spec (#3326)
• Add proper benchmarks for signal-related syscalls (#3258)
• Tune benchmarking for non-return syscalls (#3319)
• Forbid non-wasm execution for validators (#3360)
• Set MaxUnbonding eq to Staking for Vara’s NominationPools (#3365)
• Unify client to be compatible with all chains (#3363)
• Introduce PerformanceMultiplier as Config constant (#3160)
• Add NominationPool and Staking runtime api (#3388)
• Maintain total supply consistency in off-chain election provider (#3389)
• Add TransactionPaymentCallApi (#3393)
• Add DustRemoval and OnSlash handlers (#3405)
• Separate prepaid transactions into specific pallet-gear-voucher call (#3401)
• Remove PoA runtime 🪦🕊️ (#3380)
• Add governance ability to align total supply (#3418)
• Add field keep_alive to Gear extrinsics defining existence requirement (#3425)
• Update weights (#3432)

Compiler update (recommended and stabilised version)

• Update compiler version to nightly-2023-10-14 (#3409)

User-space libraries

• Add payload argument into gtest state readers (#3254)
• Update dlmalloc (#3305)
• Introduce backtrace system in gsdk (#3170)
• Handle locks for default wait sendings (#3315)
• Add Mutex lock monitor (#3341)
• Upgrade subxt dependency in gsdk to v0.32.0 (#3392)
• Expose GearConfig and PairSigner in gsdk (#3423)
• Add From<T> and Default implementations for gstd sync primitives (#3429)

Full Changelog: v1.0.0...v1.0.1