borsh-derive

Added

• merge multiple #[borsh(...)] attributes instead of rejecting them (#373)

Changed

• merge multiple #[borsh(...)] attributes instead of rejecting them (#373)

Added

• impl BorshSerialize and BorshDeserialize for Uuid (#366)

Fixed

• handle PhantomData in enum schema derive (#369)

Other

• cover schema predicate bounds referencing filtered enum params (#372)
• fix the build on current toolchains (#368)

Fixed

• keep bytes no_std unless borsh std is enabled (#364)

Added

• Use core::net instead of std::net; bumped MSRV to 1.77 (#356)

Fixed

• Avoid variant name shadowing in BorshSchema derive (#361)

Other

• Upgrade the CI base image to use ubuntu-24.04 instead of the deprecated ubuntu-20.04 (#359)
• Include license files in published crates (#354)
• add automatically_derived attribute to derive macros (#341)

Other

• replace Result::unwrap err msg with proc_macro_crate::crate_name tag (#351)

Fixed

• add indexmap support (#346)

Other

• add mention of indexmap feature (#349)

Other

• bump hashbrown to 0.15 (#333)
• fix typo in private module name (#332)

Other

• make doc examples testable in ci (#326)
• add more CODEOWNERS (#327)

Fixed

• specify a minimum version for syn as 2.0.81 (#320)

Added

• ser/de for IpAddr type; schema for Ipv4Addr/Ipv6Addr/IpAddr types (#309)

Other

• serde_json::Value bridging example/doc (#317)
• remove dependency on syn_derive (#318)
• cover one more syn::generics::TypeParamBound as per syntax change (#316)

Added

• (schema) for HashMap<K, V> -> HashMap<K, V, S>, for HashSet<T> -> HashSet<T, S> (#294)

Fixed

• fixed linting warnings for Rust 1.78 stable, 1.80 nightly (#295)

Added

• implement BorshSchema for VecDeque and LinkedList (#291)

Other

• Fix repository field of borsh-derive (#288)

Added

• impl BorshSchema for Cow<'a, T> (#284)
• BorshSerialize/BoshDeserialize/BorshSchema for Cell/RefCell (#265)

Other

• reorg tests (#285)
• remove conflicts with W/R parameters for BorshSerialize/BorshDeserialize derives (#283)
• fix test_exhaustive_checks step + downgrade package for MSRV test (#280)

Other

• fix clippy (#275)
• bump proc-macro-crate to 3; bump MSRV to 1.67 (#274)

Added

• impl BorshSchema for Rc and Arc; add doc for rc feature (#268)

Other

• optimize BorshSerialize derive for enums with unit variants (#262)
• fix release-plz error; exclude *.snap from borsh-derive publish (#263)

Added

• add support for types from ascii crate (#255)

Other

• bump proc-macro-crate to 2.0.0 in borsh-derive (#256)

Other

• add test_schema_conflicts (#254)
• addressed warnings in docs generation (#252)
• simplify discriminants handling in schema derives (#241)

Added

• relax schema_container_of target requirement with ?Sized to allow slices (#245)

Fixed

• fully qualify #cratename::BorshSchema in derive-generated code to void function name collisions leading to compilation errors (#244)

The year is 2653 and the best yet-to-be citizens of the Terran Federation are fighting and mostly just dying in a relentless interstellar war against the Arachnids. Yet the structure of our society has changed through the course of this confrontation.

The members of the Arachnid brain caste and queens have infiltrated the circles of our most influential political and industrial leaders. Either directly, or via the Arachnid technology called "Brain Bugs". This tech alone can accomplish what the Arachnid starship paratroopers will not ever be capable to do.

Simple, straightforward and performant serialization libraries can set us in course to remedy this dangerous stalemate situation by cleaning the minds of its users from even the tiniest of Brain Bugs.

Robert A. Heinlein, 1959 (a newspaper ad)

[Thanks]

borsh-rs 1.0.0 release was first conceived and then brought into existence by minds of:

• Amirhossein Akhlaghpour @Mehrbod2002
• Benji Smith @Benjins
• dj8yf0μl @dj8yfo
• iho @iho
• Jacob Lindahl @encody
• Pavel Lazureykis @lazureykis
• Tomas Zemanovic @tzemanovic

Contributors, who imposed powerful impact on the past, present and future of this library are specially recognized:

• Michal Nazarewicz @mina86 - for revisiting BorshSchema feature, rethinking it, bringing up great ideas and coming up with the fairly involved algorithm of max_serialized_size implementation.
• Alex Kladov @matklad - for maintaining a superhuman ability of context switching in under 2 minutes and scanning through 15k lines of code in under 10 minutes, while leaving out under 1% relevant details.
• Marco Ieni @MarcoIeni - for developing release-plz automation.
• Vlad Frolov @frol - for keeping an eye on the big picture and striking just the right balance between performance and versatility, ease of use and extensibility and tons of other such hard to reconcile pairs.

[Migration guides]

This section contains links to short documents, describing problems encountered during update of borsh version to v1.0.0 for related repositories.

• v0.10.2 -> v1.0.0 for nearcore
• v0.9.3 -> v1.0.0 for near-sdk-rs

[Summary of changes]

• Library's structure was made more modular and optimized with respect to visibility of its public/private constituents and ease of access to them.

• borsh's traits derives and their attributes had their capabilities extended and unified, both with respect to external interfaces and internal implementation. Please visit borsh_derive documentation pages if you're interested in more of the details.

• The consistency property of deserialization, declared in Borsh Specification, became an opt-in feature de_strict_order for hash collections.

• Support of explicit enum discriminants was added to derives of borsh traits. It has been added in somewhat limited form, only allowing the values of u8 range literals.

  use borsh::{BorshSerialize, BorshDeserialize, BorshSchema};
  
  <<<<<<< borsh-v0.10.3
  #[derive(BorshDeserialize, BorshSerialize, BorshSchema)]
  pub enum CurveType {
      ED25519 = 0, // 0 as u8 in enum tag
      SECP256K1 = 2, // 1 as u8 in enum tag
  }
  =======
  #[derive(BorshDeserialize, BorshSerialize, BorshSchema)]
  #[borsh(use_discriminant=false)]
  pub enum CurveType {
      ED25519 = 0, // 0 as u8 in enum tag
      SECP256K1 = 2, // 1 as u8 in enum tag
  }
  // vs
  #[derive(BorshDeserialize, BorshSerialize, BorshSchema)]
  #[borsh(use_discriminant=true)]
  pub enum CurveType {
      ED25519 = 0, // 0 as u8 in enum tag
      SECP256K1 = 2, // 2 as u8 in enum tag
  }
  >>>>>>> borsh-v1.0.0
  

• RUSTSEC-2023-0033 has been resolved. It has been resolved by forbidding collections with dynamic runtime length to contain zero-sized types with runtime errors, happening on serialization or deserialization. Arrays with non-Copy and non-Clone ZST singletons of length > 1 gracefully panic on deserialization, not causing memory faults.

  Using collections with dynamic runtime length (tagged sequences) for containing ZSTs was also deemed wasteful of CPU cycles and a way to perform dos attacks. Such a case is now flagged as error when using new BorshSchemaContainer::validate method for user-defined types or instantiations of BorshSchema-supporting types with inappropriate parameters, defined by the library:

  let schema = BorshSchemaContainer::for_type::<Vec<core::ops::RangeFull>>();
  assert_eq!(
      Err(
        SchemaContainerValidateError::ZSTSequence("Vec<RangeFull>".to_string())
      ), 
      schema.validate()
  );
  

• BorshSchema was extended with max_serialized_size implementation, which now unlocks support of borsh by a plethora of bounded types to express statically defined size limits of serialized representation of these types.

• schema BorshSchemaContainer api was made future-proof.

• schema Definition was extended with more variants, fields and details to uncover some of the implied details of serialization format. BorshSchema can now express a wider range of types. All types, which have BorshSchema defined by the library, now have a Definition.

• schema Declaration-s were renamed to follow Rust-first rule and not be a mix of Rust types naming/syntax and syntax from other languages.

  use borsh::schema::BorshSchema;
  
  <<<<<<< borsh-v0.10.3
  assert_eq!("nil", <()>::declaration());
  assert_eq!("string", <String>::declaration());
  assert_eq!("Array<u64, 42>", <[u64; 42]>::declaration());
  assert_eq!("Tuple<u8, bool, f32>", <(u8, bool, f32)>::declaration());
  =======
  assert_eq!("()", <()>::declaration());
  assert_eq!("String", <String>::declaration());
  assert_eq!("[u64; 42]", <[u64; 42]>::declaration());
  assert_eq!("(u8, bool, f32)", <(u8, bool, f32)>::declaration());
  >>>>>>> borsh-v1.0.0
  

[Stability guarantee]

• borsh's serialization format is guaranteed to NOT change throughout 1.x releases.
• borsh's public APIs not gated by unstable__schema feature are guaranteed to NOT break throughout 1.x releases.
• It's perceived, that new feature requests may potentially come for BorshSchema from outside of near ecosystem, thus borsh's public APIs gated by unstable__schema MAY break throughout 1.x releases.

Added

• add borsh::object_length helper (#236)

Other

• add examples for borsh::to_vec, borsh::to_writer, borsh::object_length (#238)
• [breaking] completely remove deprecated BorshSerialize::try_to_vec (#221)

Added

• [breaking] add DiscriminantValue to Definition::Enum::variants tuples (#232)
• [breaking] add length_width to schema::Definition::Sequence (#229)
• add definition of String/str (#226)
• [breaking] add Definition::Sequence::length_range field (#220)
• [breaking] add Definition::Primitive (#222)
• max_size: various small refactoring (#223)
• check Definition::Enum’s tag_width when validating schema (#224)
• add (de)serialisation + schema for more core::ops::Range... types (full, open-ended, inclusive) (#213)
• add BorshSchema implementation for core::num::NonZero... integers (#214)
• [breaking] introduce borsh::io with either items of std:io or private borsh::nostd_io module reexported (std or no_std) (#212)
• Introduce borsh::max_serialized_size function, borsh::schema::BorshSchemaContainer::for_type method (#209)

Other

• [breaking] rename "Tuple<T0, T1, T2...>" -> "(T0, T1, T2...)" (schema::Declaration) (#234)
• [breaking] rename "nil" -> "()", "string" -> "String", "nonzero_u16" -> "NonZeroU16" (schema::Declaration) (#233)
• [breaking] rename "Array<T0, N>" -> "[T0; N]" (schema::Declaration) (#235)
• [breaking] split ValidationError from MaxSizeError; validate and max_serialized_size made BorshSchemaContainer's methods (#219)
• [breaking] declare and rename schema feature to be unstable__ (may break in 1.x versions)
• Add Definition::Enum::tag_width field (#215)

Added

• [breaking] raise bound on keys in hashcollections PartialOrd -> Ord (#203)
• forbid most collections from containing zst elements/keys (#202)
• add #[borsh(crate = ...)] item-level attribute (#210)
• forbid multiple borsh attr occurencies (#199)

Other

• various flaws correction (#205)
• [breaking] deprecate try_to_vec method from BorshSerialize (#206)
• [breaking] make BorshSchema::add_definition default implementation a free-standing func (#204)
• remove #[non_exhaustive] on borsh::schema::Definition (#200)

Other

• [breaking] renamed #[borsh_skip] to #[borsh(skip)] (#192)
• split up schema derive functions (#191)

Other

• [breaking] borsh_init to borsh(init). (#187)

Bug Fixes

• Unused fields warn, fields for inner structs of derived BorshSchema method (#172)
• #[borsh_skip] on field of struct enum variant (BorshSerialize) (#174)
• Filter out foreign attributes in BorshSchema derive for enum (#177)

Documentation

• Create a brief documentation of crate's features (#159)
• Mention schema feature in doc.rs (#166)

Features

• Forbid Vectors of Zero-sized types from de-/serialization to resolve the RUSTSEC-2023-0033 (#145)
• Add top-level from_slice and from_reader helper functions to make the API nicer (#142)
• [breaking] Add #[borsh(use_discriminant = <bool>)] attribute that changes enum discriminant de- and serialization behavior
• [breaking] Remove BinaryHeap support (#161)
• Sets/maps benches for reference point (#164)
• Enforce canonicity on HashSet/BTreeSet/HashMap/BTreeMap (#162)
• [breaking] Support recursive structures! (#178)
  • BorshSerialize, BorshDeserialize, BorshSchema derives may break
  • derives may require patching bounds with #[borsh(bound(..))] / #[borsh(schema(params = ...))]
• Bounds for ser/de derive and schema_params for schema derive attributes (#180)
• Derive attribute for 3rd party structs/enums as fields (#182)

Miscellaneous Tasks

• Bump proc-macro-crate versions (#149)
• Add tests job for MSRV (1.65.0) (#151)
• [breaking] Hide maybestd from public interface, despite it being technically available by new name of __maybestd (#153)
• Fix broken reference-style link in minimum supported version badge (#154)
• Remove a bunch of clippy-related TODOs (uninlined_format_args) (#156)
• Simpler bounds on Rc/Arc impls (#167)
• Invited @dj8yfo to CODEOWNERS (#169)
• [breaking] Replace ErrorKind::InvalidInput with ErrorKind::InvalidData as per original std::io meaning (#170)

Refactor

• [breaking] Make hashbrown dependency optional, hashbrown feature (#155)
• [breaking] BorshSchemaContainer fields non-pub, HashMap -> BTreeMap in schema everywhere (#165)
• [breaking] Move derive under #[cfg(feature = "derive")] (#168)
• Introduce __private module with macro runtime (#171)
• [breaking] Unsplit and removal of *-internal crates (#185)
  • borsh-schema-derive-internal and borsh-derive-internal crates won't be published anymore

Testing

• Add insta snapshots to borsh/tests (#157)
• insta tests for prettified TokenStream-s in borsh*derive-internal (#176)

Ci

• Only release-plz after other checks pass

Added

• add BorshSchema for PhantomData, BTreeMap and BTreeSet (#93)
• Add optional bson::oid::ObjectId support (#135)
• [breaking] ser/de enum discriminant (#138)

Fixed

• no-std tests did not run due to dev-dependencies re-enabling std feature (#144)

Other

• use release-plz and specify common rust version correctly (#134)
• Upgrade plain-HTTP links to HTTPS in Cargo.toml files (#141)

• Add optional bytes/bytesmut support

• Prevent unbound allocation for vectors on deserialization

• Implemented (de)ser for core::ops::range
• Introduce de::EnumExt trait with deserialize_variant method

• Fix no-std feature (some of the imports incorrectly used std:: instead of crate::maybestd::)
• Fix borsh-schema derives with for bounds
• Implemented BorshSchema for HashSet
• Add support for isize, usize types
• Delete schema for char
• Implement ser/de and schema for (T,)
• Add clone impls to borsh schema types
• Remove unnecessary trait bounds requirements for array
• BREAKING CHANGE: BorshDeserialize now works by receiving an &mut std::io::Read instead of a &mut &[u8]. This is a breaking change for code that provides custom implementations of BorshDeserialize; there is no impact on code that uses only the derive macro.
• Added BorshDeserialize::try_from_reader and BorshDeserialize::deserialize_reader.
• Upgrade hashbrown version to be >=0.11,<0.14 to allow wider range of versions.

• Fix no_std compatibility.
• Reduce code bloat in derived BorshSerialize impl for enums.

• Upgrade hashbrown from 0.9 to 0.11. This can breakage in the rare case that you use borsh schema together with no-std support and rely on a specific version hashbrown of SchemaContainer. This is considered to be obscure enough to not warrant a semver bump.

• Eliminated unsafe code from both ser and de of u8 (#26)
• Implemented ser/de for reference count types (#27)
• Added serialization helpers to improve api ergonomics (#34)
• Implemented schema for arrays and fix box bounds (#36)
• Implemented (de)ser for PhantomData (#37)
• Implemented const-generics under feature (#38)
• Added an example of direct BorshSerialize::serialize usage with vector and slice buffers (#29)

• BREAKING CHANGE: is_u8 optimization helper is now unsafe since it may cause undefined behavior if it returns true for the type that is not safe to Copy (#21)
• Extended the schema impls to support longer arrays to match the de/serialization impls (#22)

• Avoid collisions of imports due to derive-generated code (#14)

• Added support for BTreeMap, BTreeSet, BinaryHeap, LinkedList, and VecDeque

• Add no_std support.

• Implement BorshSerialize for reference fields (&T)

• Implement BorshSerialize for &T if T implements BorshSerialize.

• Extended Box<T> implementation for ?Sized types ([T], str, ...).
• Added support for std::borrow::Cow
• Avoid silent integer casts since they can lead to hidden security issues.
• Removed Cargo.lock as it is advised for lib crates.