Skip to content

docs: refresh optimisation guide for v0.14 (#430) - #445

Open
mr-zwets wants to merge 1 commit into
nextfrom
docs/revisit-optimisation-guide
Open

mr-zwets wants to merge 1 commit into
nextfrom
docs/revisit-optimisation-guide

Conversation

@mr-zwets

Copy link
Copy Markdown
Member

The optimisation guide predated user-defined functions, global constants and imports, and framed optimisation as a bytesize-only concern.

  • Frame the guide around both budgets: bytesize and op-cost, and note that they pull in opposite directions for P2SH contracts.
  • Add a section on measuring op-cost with getVmResourceUsage(), which was documented on the TransactionBuilder but never linked from here.
  • Describe what the compiler already does: peephole optimisations and the inline-vs-OP_DEFINE decision for functions and constants.
  • Add a "Sharing code with functions and constants" section covering global constants, user-defined functions and imports.
  • Demote the "Combining Functions" workaround: extracting shared logic into user-defined functions is now the better first step.
  • Add a tip on returning multiple values from one function instead of recomputing shared work in two.

Also document the nested-function call stack in the debugging guide, which was user-visible since #429 but undocumented, and fix a link to the HashType anchor that broke when it was renamed to SighashType.

Correct the tuple destructuring guidance in contracts.md. It said that listing declarations before reassignments compiles smaller, but the opposite holds: visitTupleAssignment processes targets right-to-left and parks declarations on the altstack, so trailing declarations keep the stack shallower for the emitReplace calls, whose cost grows with depth. Measured at 58 / 55 / 52 bytes as the declaration moves rightwards.

Every byte count quoted in the guide was measured against the exact code shown.

The optimisation guide predated user-defined functions, global constants
and imports, and framed optimisation as a bytesize-only concern.

- Frame the guide around both budgets: bytesize and op-cost, and note
  that they pull in opposite directions for P2SH contracts.
- Add a section on measuring op-cost with getVmResourceUsage(), which
  was documented on the TransactionBuilder but never linked from here.
- Describe what the compiler already does: peephole optimisations and
  the inline-vs-OP_DEFINE decision for functions and constants.
- Add a "Sharing code with functions and constants" section covering
  global constants, user-defined functions and imports.
- Demote the "Combining Functions" workaround: extracting shared logic
  into user-defined functions is now the better first step.
- Add a tip on returning multiple values from one function instead of
  recomputing shared work in two.

Also document the nested-function call stack in the debugging guide,
which was user-visible since #429 but undocumented, and fix a link to
the HashType anchor that broke when it was renamed to SighashType.

Correct the tuple destructuring guidance in contracts.md. It said that
listing declarations before reassignments compiles smaller, but the
opposite holds: visitTupleAssignment processes targets right-to-left and
parks declarations on the altstack, so trailing declarations keep the
stack shallower for the emitReplace calls, whose cost grows with depth.
Measured at 58 / 55 / 52 bytes as the declaration moves rightwards.

Every byte count quoted in the guide was measured against the exact
code shown.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QbNNwhTXMdRuRBvwbjGSei
@vercel

vercel Bot commented Sep 14, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
cashscript Ready Ready Preview Sep 14, 2026 10:35am UTC

Request Review

@codecov

codecov Bot commented Sep 14, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (next@07a1667). Learn more about missing BASE report.

Additional details and impacted files
@@           Coverage Diff           @@
##             next     #445   +/-   ##
=======================================
  Coverage        ?   88.18%           
=======================================
  Files           ?       59           
  Lines           ?     4843           
  Branches        ?      906           
=======================================
  Hits            ?     4271           
  Misses          ?      443           
  Partials        ?      129           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant