Existing content, two related pages: the Move.toml manifest reference docs (https://docs.sui.io/references/package-managers/manifest-reference) and the transaction effects / object versioning docs. Filing together since both are documentation-clarity gaps rather than code bugs — happy to split into separate issues if preferred.
1. Pinning the Sui framework dependency to a moving branch instead of a release tag causes silent, hard-to-diagnose verifier failures
Our Move.toml originally pinned the Sui framework dependency to rev = "framework/mainnet" — a branch, not a fixed release tag. That branch advanced past what our then-pinned CLI's bytecode verifier understood (a newly added sui::rangeproofs module), and every test started failing with UNEXPECTED_VERIFIER_ERROR (error code 2017), with no signal anywhere that the actual cause was a branch/binary version mismatch rather than a bug in our code. The fix was pinning the dependency to the matching release tag instead of the branch, and keeping the two in lockstep going forward — but nothing in sui move build/sui move test warned us this was even a possible failure mode; we found it through process of elimination.
Suggested fix: a simple, purely static check — "this dependency's rev resolves to a branch ref rather than a tag; branches can move independently of your installed CLI and cause verifier mismatches, prefer pinning to a release tag" — would have saved meaningful debugging time and seems straightforward to implement, since the distinction between a branch ref and a tag ref is knowable at resolve time. Failing that, an explicit warning in the Move.toml manifest reference docs about the risk of branch-pinning the framework dependency would help.
2. Object versioning on immutable-reference-only inputs isn't obviously documented, and is easy to get wrong in verification logic
We initially designed backend verification logic that checked whether a given object appeared with a bumped version in effects.changedObjects as a proxy for "did this transaction touch object X." That check is silently wrong for any transaction that only borrows the object via &T (an immutable reference) without ever mutating, creating, or deleting it — Sui does not bump an object's version for read-only inputs, so changedObjects simply won't include it, even though the object was very much a real, meaningful input to the transaction. We caught this only through careful manual reasoning about Move's borrow semantics before ever running the code, not because any documentation we found called it out directly.
Given how natural it is to reach for changedObjects as a general "was this object involved" check, we'd guess this is a common trap. Suggested fix: an explicit, prominent callout in the transaction-effects / object-versioning documentation, ideally with the recommendation to check effects.dependencies/input objects instead of changedObjects when the goal is confirming an object was an input rather than confirming it was mutated.
Existing content, two related pages: the Move.toml manifest reference docs (https://docs.sui.io/references/package-managers/manifest-reference) and the transaction effects / object versioning docs. Filing together since both are documentation-clarity gaps rather than code bugs — happy to split into separate issues if preferred.
1. Pinning the Sui framework dependency to a moving branch instead of a release tag causes silent, hard-to-diagnose verifier failures
Our
Move.tomloriginally pinned the Sui framework dependency torev = "framework/mainnet"— a branch, not a fixed release tag. That branch advanced past what our then-pinned CLI's bytecode verifier understood (a newly addedsui::rangeproofsmodule), and every test started failing withUNEXPECTED_VERIFIER_ERROR(error code 2017), with no signal anywhere that the actual cause was a branch/binary version mismatch rather than a bug in our code. The fix was pinning the dependency to the matching release tag instead of the branch, and keeping the two in lockstep going forward — but nothing insui move build/sui move testwarned us this was even a possible failure mode; we found it through process of elimination.Suggested fix: a simple, purely static check — "this dependency's
revresolves to a branch ref rather than a tag; branches can move independently of your installed CLI and cause verifier mismatches, prefer pinning to a release tag" — would have saved meaningful debugging time and seems straightforward to implement, since the distinction between a branch ref and a tag ref is knowable at resolve time. Failing that, an explicit warning in the Move.toml manifest reference docs about the risk of branch-pinning the framework dependency would help.2. Object versioning on immutable-reference-only inputs isn't obviously documented, and is easy to get wrong in verification logic
We initially designed backend verification logic that checked whether a given object appeared with a bumped version in
effects.changedObjectsas a proxy for "did this transaction touch object X." That check is silently wrong for any transaction that only borrows the object via&T(an immutable reference) without ever mutating, creating, or deleting it — Sui does not bump an object's version for read-only inputs, sochangedObjectssimply won't include it, even though the object was very much a real, meaningful input to the transaction. We caught this only through careful manual reasoning about Move's borrow semantics before ever running the code, not because any documentation we found called it out directly.Given how natural it is to reach for
changedObjectsas a general "was this object involved" check, we'd guess this is a common trap. Suggested fix: an explicit, prominent callout in the transaction-effects / object-versioning documentation, ideally with the recommendation to checkeffects.dependencies/input objects instead ofchangedObjectswhen the goal is confirming an object was an input rather than confirming it was mutated.