{"id":30732478,"url":"https://github.com/bitjson/bch-bitwise","last_synced_at":"2026-02-22T23:32:47.095Z","repository":{"id":296651997,"uuid":"993614521","full_name":"bitjson/bch-bitwise","owner":"bitjson","description":"Re-enables bitwise operations, enabling Bitcoin Cash contracts to more efficiently implement a variety of financial and cryptographic applications","archived":false,"fork":false,"pushed_at":"2025-10-14T18:11:38.000Z","size":76,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-29T03:59:00.647Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitjson.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-31T06:13:04.000Z","updated_at":"2025-10-14T18:11:41.000Z","dependencies_parsed_at":"2025-06-01T14:16:30.859Z","dependency_job_id":"f3a24fcb-a48c-488c-8b28-0ab711ca7505","html_url":"https://github.com/bitjson/bch-bitwise","commit_stats":null,"previous_names":["bitjson/bch-bitwise"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bitjson/bch-bitwise","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitjson%2Fbch-bitwise","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitjson%2Fbch-bitwise/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitjson%2Fbch-bitwise/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitjson%2Fbch-bitwise/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitjson","download_url":"https://codeload.github.com/bitjson/bch-bitwise/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitjson%2Fbch-bitwise/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29730728,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-22T20:09:16.275Z","status":"ssl_error","status_checked_at":"2026-02-22T20:09:13.750Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-03T17:07:43.169Z","updated_at":"2026-02-22T23:32:47.080Z","avatar_url":"https://github.com/bitjson.png","language":null,"readme":"# CHIP-2025-05 Bitwise: Re-Enable Bitwise Operations\n\n        Title: Re-Enable Bitwise Operations\n        Type: Standards\n        Layer: Consensus\n        Maintainer: Jason Dreyzehner\n        Initial Publication Date: 2025-05-31\n        Latest Revision Date: 2025-09-05\n        Version: 1.1.1 (a432a19b)\n        Status: Frozen for Lock-In\n\n## Summary\n\nThis proposal re-enables bitwise operations, enabling Bitcoin Cash contracts to more efficiently implement a variety of financial and cryptographic applications.\n\n## Deployment\n\nDeployment of this specification is proposed for the May 2026 upgrade.\n\n- Activation is proposed for `1763208000` MTP, (`2025-11-15T12:00:00.000Z`) on `chipnet`.\n- Activation is proposed for `1778846400` MTP, (`2026-05-15T12:00:00.000Z`) on the BCH network (`mainnet`), `testnet3`, `testnet4`, and `scalenet`.\n\n## Technical Specification\n\nThe virtual machine is modified to enable five bitwise opcodes: `OP_INVERT`, `OP_LSHIFTNUM`, `OP_RSHIFTNUM`, `OP_LSHIFTBIN`, and `OP_RSHIFTBIN`.\n\n### Bit Inversion\n\n#### `OP_INVERT`\n\n```CashAssembly\n\u003cbinary_data\u003e OP_INVERT\n```\n\nThe `OP_INVERT` opcode is defined at codepoint `0x83` (`131`) with the following behavior:\n\n1. Pop the top item from the stack.\u003csup\u003e1\u003c/sup\u003e\n2. Invert (bitwise \"NOT\") each byte of the item, then push the result to the stack.\u003csup\u003e2\u003c/sup\u003e\n\n\u003csmall\u003e\n\n#### OP_INVERT Clarifications\n\n1. If the stack is empty (no `binary_data`), error. Note that implementations may choose to operate on the top stack item in-place, but operation cost must be incremented as if the result were pushed again.\n2. The [Operation Cost](http://github.com/bitjson/bch-vm-limits#operation-cost-limit) of `OP_INVERT` is the [Base Instruction Cost](https://github.com/bitjson/bch-vm-limits?#base-instruction-cost) plus the length of the pushed result (see [Rationale: Calculation of Operation Costs](./rationale.md#calculation-of-operation-costs)). Note that the length of the result is always equal to the length of the input.\n\n\u003c/small\u003e\n\n### Arithmetic Shifts\n\n#### `OP_LSHIFTNUM`\n\n```CashAssembly\n\u003cvalid_number\u003e \u003cbit_count\u003e OP_LSHIFTNUM\n```\n\nThe `OP_LSHIFTNUM` opcode is defined at codepoint `0x8d` (`141`) with the following behavior:\n\n1. Pop the top item from the stack as a bit count (VM number).\u003csup\u003e1\u003c/sup\u003e\n2. Pop the next item from the stack as the value (VM number) to shift.\u003csup\u003e2\u003c/sup\u003e\n3. Perform an arithmetic left shift of the value by the bit count (`result = value * (2 ^ bit_count)`), then push the result to the stack.\u003csup\u003e3\u003c/sup\u003e\n\n\u003csmall\u003e\n\n#### OP_LSHIFTNUM Clarifications\n\n1. If the stack is empty (no `bit_count`), error. If the popped item is not a VM Number, error. If the bit count is negative, error. See [Rationale: Disallowance of Negative Shifts](./rationale.md#disallowance-of-negative-shifts) and [Rationale: Predictable Handling of Excessive Shift Operations](rationale.md#predictable-handling-of-excessive-shift-operations). Note that Maximum Stack Item Length may be increased by future upgrades. See [Notice of Possible Future Expansion](#notice-of-possible-future-expansion).\n2. If the stack is empty (no `valid_number`), error. If the popped item is not a valid VM Number, error.\n3. If the byte length of the result would exceed the [Maximum Stack Item Length](https://github.com/bitjson/bch-vm-limits#increased-stack-element-length-limit), error (implementations may optionally fast-fail such shifts). The [Operation Cost](http://github.com/bitjson/bch-vm-limits#operation-cost-limit) of `OP_LSHIFTNUM` is the [Base Instruction Cost](https://github.com/bitjson/bch-vm-limits?#base-instruction-cost) plus the length of the pushed result (see [Rationale: Calculation of Operation Costs](./rationale.md#calculation-of-operation-costs)). Note that the length of the output VM number may differ from the length of the input VM number.\n\n\u003c/small\u003e\n\n#### `OP_RSHIFTNUM`\n\n```CashAssembly\n\u003cvalid_number\u003e \u003cbit_count\u003e OP_RSHIFTNUM\n```\n\nThe `OP_RSHIFTNUM` opcode is defined at codepoint `0x8e` (`142`) with the following behavior:\n\n1. Pop the top item from the stack as a bit count (VM number).\u003csup\u003e1\u003c/sup\u003e\n2. Pop the next item from the stack as the value (VM number) to shift.\u003csup\u003e2\u003c/sup\u003e\n3. Perform an arithmetic right shift of the value by the bit count (`result = value / (2 ^ bit_count)`) rounding towards negative infinity\u003csup\u003e3\u003c/sup\u003e, then push the resulting VM number to the stack.\u003csup\u003e4\u003c/sup\u003e\n\n\u003csmall\u003e\n\n#### OP_RSHIFTNUM Clarifications\n\n1. If the stack is empty (no `bit_count`), error. If the popped item is not a VM Number, error. If the bit count is negative, error. See [Rationale: Disallowance of Negative Shifts](./rationale.md#disallowance-of-negative-shifts) and [Rationale: Predictable Handling of Excessive Shift Operations](rationale.md#predictable-handling-of-excessive-shift-operations). Note that Maximum Stack Item Length may be increased by future upgrades. See [Notice of Possible Future Expansion](#notice-of-possible-future-expansion).\n2. If the stack is empty (no `valid_number`), error. If the popped item is not a valid VM Number, error.\n3. The common behavior in Two's Complement right shifts (and the behavior standardized in C++20). See [Rationale: Behavior of Arithmetic Right Shifts on Negative Values](./rationale.md#behavior-of-arithmetic-right-shifts-on-negative-values). Implementations may optionally include a faster return path for excessive shifts (`0` for excessive shifts on positive values or `-1` for excessive shifts on negative values).\n4. The [Operation Cost](http://github.com/bitjson/bch-vm-limits#operation-cost-limit) of `OP_RSHIFTNUM` is the [Base Instruction Cost](https://github.com/bitjson/bch-vm-limits?#base-instruction-cost) plus the length of the pushed result (see [Rationale: Calculation of Operation Costs](./rationale.md#calculation-of-operation-costs)). Note that the length of the output VM number may differ from the length of the input VM number.\n\n\u003c/small\u003e\n\n### Binary (Logical) Shifts\n\n#### `OP_LSHIFTBIN`\n\n```CashAssembly\n\u003cbinary_data\u003e \u003cbit_count\u003e OP_LSHIFTBIN\n```\n\nThe `OP_LSHIFTBIN` opcode is defined at codepoint `0x98` (`152`) with the following behavior:\n\n1. Pop the top item from the stack as a bit count (VM number).\u003csup\u003e1\u003c/sup\u003e\n2. Pop the next item from the stack as the binary data to shift.\u003csup\u003e2\u003c/sup\u003e\n3. Perform a fixed-length, logical left shift of the data by the bit count, shifting-in `0` bits from the right and dropping shifted-out bits on the left\u003csup\u003e3\u003c/sup\u003e, then push the result to the stack.\u003csup\u003e4\u003c/sup\u003e\n\n\u003csmall\u003e\n\n#### OP_LSHIFTBIN Clarifications\n\n1. If the stack is empty (no `bit_count`), error. If the popped item is not a VM Number, error. If the bit count is negative, error. See [Rationale: Disallowance of Negative Shifts](./rationale.md#disallowance-of-negative-shifts) and [Rationale: Predictable Handling of Excessive Shift Operations](rationale.md#predictable-handling-of-excessive-shift-operations). Note that Maximum Stack Item Length may be increased by future upgrades. See [Notice of Possible Future Expansion](#notice-of-possible-future-expansion).\n2. If the stack is empty (no `binary_data`), error. Note that any stack item is a valid input; zero-byte inputs produce a zero-byte output.\n3. Implementations may optionally include a faster return path for excessive shifts (returning an appropriately-sized, zero-filled stack item).\n4. The [Operation Cost](http://github.com/bitjson/bch-vm-limits#operation-cost-limit) of `OP_LSHIFTBIN` is the [Base Instruction Cost](https://github.com/bitjson/bch-vm-limits?#base-instruction-cost) plus the length of the pushed result (see [Rationale: Calculation of Operation Costs](./rationale.md#calculation-of-operation-costs)). Note that the length of the result is always equal to the length of the input. See [Rationale: Fixed-Length Result of Binary Shifts](./rationale.md#fixed-length-result-of-binary-shifts).\n\n\u003c/small\u003e\n\n#### `OP_RSHIFTBIN`\n\n```CashAssembly\n\u003cbinary_data\u003e \u003cbit_count\u003e OP_RSHIFTBIN\n```\n\nThe `OP_RSHIFTBIN` opcode is defined at codepoint `0x99` (`153`) with the following behavior:\n\n1. Pop the top item from the stack as a bit count (VM number).\u003csup\u003e1\u003c/sup\u003e\n2. Pop the next item from the stack as the binary data to shift.\u003csup\u003e2\u003c/sup\u003e\n3. Perform a fixed-length, logical right shift of the data by the bit count, shifting-in `0` bits from the left and dropping shifted-out bits on the right\u003csup\u003e3\u003c/sup\u003e, then push the result to the stack.\u003csup\u003e4\u003c/sup\u003e\n\n\u003csmall\u003e\n\n#### OP_RSHIFTBIN Clarifications\n\n1. If the stack is empty (no `bit_count`), error. If the popped item is not a VM Number, error. If the bit count is negative, error. See [Rationale: Disallowance of Negative Shifts](./rationale.md#disallowance-of-negative-shifts) and [Rationale: Predictable Handling of Excessive Shift Operations](rationale.md#predictable-handling-of-excessive-shift-operations). Note that Maximum Stack Item Length may be increased by future upgrades. See [Notice of Possible Future Expansion](#notice-of-possible-future-expansion).\n2. If the stack is empty (no `binary_data`), error. Note that any stack item is a valid input; zero-byte inputs produce a zero-byte output.\n3. Implementations may optionally include a faster return path for excessive shifts (returning an appropriately-sized, zero-filled stack item).\n4. The [Operation Cost](http://github.com/bitjson/bch-vm-limits#operation-cost-limit) of `OP_RSHIFTBIN` is the [Base Instruction Cost](https://github.com/bitjson/bch-vm-limits?#base-instruction-cost) plus the length of the pushed result (see [Rationale: Calculation of Operation Costs](./rationale.md#calculation-of-operation-costs)). Note that the length of the result is always equal to the length of the input. See [Rationale: Fixed-Length Result of Binary Shifts](./rationale.md#fixed-length-result-of-binary-shifts).\n\n\u003c/small\u003e\n\n### Notice of Possible Future Expansion\n\nWhile unusual, it is possible to design pre-signed transactions, contract systems, and protocols which rely on the rejection of otherwise-valid transactions made invalid only by specifically exceeding one or more current VM limits. This proposal interprets such failure-reliant constructions as intentional – the constructions are designed to fail unless/until a possible future network upgrade in which such limits are increased, e.g. upgrade-activation futures contracts. Contract authors are advised that future upgrades may raise VM limits by increasing [Maximum Stack Item Length](https://github.com/bitjson/bch-vm-limits#increased-stack-element-length-limit) (A.K.A. `MAX_SCRIPT_ELEMENT_SIZE`), maximum bytecode length (A.K.A. `MAX_SCRIPT_SIZE`), or otherwise. See [Limits CHIP Rationale: Inclusion of \"Notice of Possible Future Expansion\"](https://github.com/bitjson/bch-vm-limits/blob/master/rationale.md#inclusion-of-notice-of-possible-future-expansion).\n\n## Rationale\n\n- [Appendix: Rationale \u0026rarr;](rationale.md#rationale)\n  - [Behavior of Arithmetic Right Shifts on Negative Values](rationale.md#behavior-of-arithmetic-right-shifts-on-negative-values)\n  - [Fixed-Length Result of Binary Shifts](rationale.md#fixed-length-result-of-binary-shifts)\n  - [Disallowance of Negative Shifts](rationale.md#disallowance-of-negative-shifts)\n  - [Predictable Handling of Excessive Shift Operations](rationale.md#predictable-handling-of-excessive-shift-operations)\n  - [Calculation of Operation Costs](rationale.md#calculation-of-operation-costs)\n\n## Evaluations of Alternatives\n\n- [Appendix: Evaluations of Alternatives \u0026rarr;](alternatives.md#evaluation-of-alternatives)\n  - [Arithmetic Shifts](./alternatives.md#arithmetic-shifts)\n    - [Alternative: Negative Rounding Toward Zero](./alternatives.md#alternative-negative-rounding-toward-zero)\n  - [Binary (Logical) Shifts](./alternatives.md#binary-logical-shifts)\n    - [Alternative: Variable-Length Results](./alternatives.md#alternative-variable-length-results)\n\n## Risk Assessment\n\n- [Appendix: Risk Assessment \u0026rarr;](risk-assessment.md#risk-assessment)\n\n## Test Vectors\n\nThis proposal includes [a suite of functional tests and benchmarks](./vmb_tests/) to verify the performance of all operations within virtual machine implementations.\n\n## Implementations\n\nPlease see the following implementations for examples and additional test vectors:\n\n- C++:\n  - [Bitcoin Cash Node (BCHN)](https://bitcoincashnode.org/) – A professional, miner-friendly node that solves practical problems for Bitcoin Cash. [Merge Request !1962](https://gitlab.com/bitcoin-cash-node/bitcoin-cash-node/-/merge_requests/1962/).\n- **JavaScript/TypeScript**:\n  - [Libauth](https://github.com/bitauth/libauth) – An ultra-lightweight, zero-dependency JavaScript library for Bitcoin Cash. [Branch `next`](https://github.com/bitauth/libauth/tree/next).\n  - [Bitauth IDE](https://github.com/bitauth/bitauth-ide) – An online IDE for bitcoin (cash) contracts. [Branch `next`](https://github.com/bitauth/bitauth-ide/tree/next).\n\n## Feedback \u0026 Reviews\n\n- [Bitwise CHIP Issues](https://github.com/bitjson/bch-bitwise/issues)\n- [`CHIP 2025-05 Bitwise: Re-Enable Bitwise Operations` - Bitcoin Cash Research](https://bitcoincashresearch.org/t/chip-2025-05-bitwise-re-enable-bitwise-operations/1580)\n\n## Acknowledgements\n\nThank you to the following contributors for reviewing and contributing improvements to this proposal, providing feedback, and promoting consensus among stakeholders:\n[Calin Culianu](https://github.com/cculianu)\n\n## Changelog\n\nThis section summarizes the evolution of this proposal.\n\n- **v1.1.1 – 2025-09-05** ([`a432a19b`](https://github.com/bitjson/bch-bitwise/commit/a432a19bcbc597391d0f0a29ae62a902b575d1dd) – [diff vs. `master`](https://github.com/bitjson/bch-bitwise/compare/a432a19bcbc597391d0f0a29ae62a902b575d1dd...master))\n  - Update VMB tests and benchmarks\n- **v1.1.0 – 2025-06-09** ([`1c954588`](https://github.com/bitjson/bch-bitwise/commit/1c954588ab971f5848844f44485fafe6d31bef56))\n  - More predictable handling of excessive shifts ([#2](https://github.com/bitjson/bch-bitwise/pull/2))\n- **v1.0.0 – 2025-05-31** ([`4fab9dfe`](https://github.com/bitjson/bch-bitwise/commit/4fab9dfe83f28b03211a38c850f2ca034eed700c))\n  - Initial publication\n\n## Copyright\n\nThis document is placed in the public domain.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitjson%2Fbch-bitwise","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitjson%2Fbch-bitwise","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitjson%2Fbch-bitwise/lists"}