tapehash 0.1.0__tar.gz

tapehash-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+*/__pycache__
+*.swp
+venv/
+temp/
+dist/

tapehash-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: tapehash
+Version: 0.1.0
+Summary: Simple proof-of-work system that uses many hash algorithms.
+Project-URL: Homepage, https://github.com/k98kurz/tapehash
+Project-URL: Repository, https://github.com/k98kurz/tapehash
+Project-URL: Bug Tracker, https://github.com/k98kurz/tapehash/issues
+Author-email: k98kurz <k98kurz@gmail.com>
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: ISC License (ISCL)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# tapehash
+
+Tapehash is a slapdash proof-of-work system that uses a lot of different hash
+algorithms and an opcode execution system for ASIC-resistance. This is meant to
+be a good-enough solution for proof-of-concept systems.
+
+## Installation
+
+```bash
+pip install tapehash
+```
+
+An overview follows, but full documentation can be found
+[here](https://github.com/k98kurz/tapehash/blob/master/dox.md), generated
+automatically by [autodox](https://pypi.org/project/autodox).
+
+## Functions
+
+This package contains three tuneable hashing functions:
+
+- `tapehash1(preimage: bytes, code_size: int = 20) -> bytes:`
+- `tapehash2(preimage: bytes, tape_size_multiplier: int = 2) -> bytes:`
+- `tapehash3(preimage: bytes, code_size: int = 64, tape_size_multiplier: int = 2) -> bytes:`
+
+All three have defaul parameters tuned to require about 0.25-0.3 ms per hash
+(roughly 250-300x as long as sha256 on the reference hardware).
+
+It also includes the following proof-of-work functions:
+
+- `work(state: HasNonceProtocol, serialize: Callable, difficulty: int, hash_algo: Callable) -> HasNonceProtocol:`
+- `calculate_difficulty(val: bytes) -> int:`
+- `calculate_target(difficulty: int) -> int:`
+- `check_difficulty(val: bytes, difficulty: int) -> bool:`
+
+Difficulty is calculated by dividing `2**256` by the big-endian int value of a
+hash, which produces the expected average number of tries to find that hash or
+better (smaller). It is a linear difficulty metric. A target for a given
+difficulty level can then be calculated by dividing `2**256` by the difficulty.
+The `work` function first calculates this target, then increments the `nonce`
+property of `state` until the `hash_algo(serialize(state))` is less than the
+calculated target (unsigned int comparison).
+
+## Use
+
+To use for proof-of-work/hashcash, create a class that follows the
+`HasNonceProtocol` contract (must have a settable `nonce` property) and a
+serialization function, then invoke `work` to find a nonce that meets the
+difficulty threshold. To check a received value, serialize it, hash it, and then
+call `check_difficulty`.
+
+For example, it could be used to filter out spam as in the original hashcash proposal:
+
+```python
+from dataclasses import dataclass, field
+from tapehash import tapehash3, work, check_difficulty, calculate_difficulty
+from packify import pack, unpack
+
+_default_diff_threshold = 128 # average number of attempts to find a nonce
+
+@dataclass
+class Message:
+    message: str = field()
+    nonce: int = field(default=0)
+    def pack(self) -> bytes:
+        return pack((self.message, self.nonce))
+    @classmethod
+    def unpack(cls, data: bytes) -> 'Message':
+        return cls(*unpack(data))
+    def find_nonce(self, difficulty: int = _default_diff_threshold):
+        work(self, lambda m: m.pack(), difficulty, tapehash3)
+    def hash(self) -> bytes:
+        return tapehash3(self.pack())
+    def check(self, difficulty: int = _default_diff_threshold) -> bool:
+        return check_difficulty(self.hash(), difficulty)
+    def difficulty(self) -> int:
+        return calculate_difficulty(self.hash())
+    @classmethod
+    def make(cls, msg: str, difficulty: int = _default_diff_threshold) -> 'Message':
+        m = cls(msg)
+        m.find_nonce(difficulty)
+        return m
+
+def filter(messages: list[Message], difficulty: int = _default_diff_threshold) -> list[Message]:
+    """Filter out spam messages that do not reach the difficulty threshold."""
+    return [m for m in messages if m.check(difficulty)]
+```
+
+Then, a message that has the required difficulty can be generated by calling
+`Message.make`, and a batch of received messages can be verified and filtered
+using the `filter` function.
+
+This example uses my serialization package [packify](https://pypi.org/project/packify)
+for convenience and brevity. Any serialization would do, and a real system would
+benefit from an optimized serialization function rather than a generalized one.
+
+## CLI
+
+Installing this package provides three CLI commands:
+
+- tapehash1
+- tapehash2
+- tapehash3
+
+These three commands function in the same way, with only the algorithm tuning
+parameters being somewhat different:
+
+- All 3 accept a `--help` or `-h` flag to print help text
+- All 3 accept a preimage from stdin, through a `--preimage {string}` parameter,
+  or through a `--file {path}` parameter
+    - NB: `cat file.txt | tapehashX` is equivalent to `tapehashX --file file.txt`
+- All 3 accept a `--from:hex` flag that will parse the preimage as hexadecimal
+- All 3 accept these optional output flags (only 1 at a time):
+    - `--to:raw` will output the digest as raw bytes
+    - `--difficulty` will output the calculated difficulty score of the hash digest
+    - `--check {int}` will output 1 if the digest meets the difficulty threshold
+      {int} or 0 (and an exit code of 2) if it did not
+    - Default behavior is to print the hexadecimal digest
+- tapehash1 and tapehash3 accept `--code_size {int}` or `-cs {int}` tuning
+  parameter (default=20 for tapehash1 and 64 for tapehash3)
+- tapehash2 and tapehash3 accept `--tape_size_multiplier {int}` or `-tsm {int}`
+  tuning parameter (default=2)
+
+An improper invocation will result in an exit value of 1. A proper invocation
+will result in an exit code of 0 in all cases except when `--check {int}` exits
+with 2.
+
+## Testing
+
+Testing has thus far been done manually. I may add a unit test suite at some
+point, but it seems unnecessary for now.
+
+## License
+
+ISC License
+
+Copyleft (c) 2025 Jonathan Voss (k98kurz)
+
+Permission to use, copy, modify, and/or distribute this software
+for any purpose with or without fee is hereby granted, provided
+that the above copyleft notice and this permission notice appear in
+all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
+AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
+CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+

tapehash-0.1.0/dox.md

@@ -0,0 +1,71 @@
+# tapehash
+
+## Classes
+
+### `HasNonceProtocol(Protocol)`
+
+The HasNonceProtocol requires that an implementation has a settable nonce
+property.
+
+#### Properties
+
+- nonce
+
+## Functions
+
+### `tapehash1(preimage: bytes, code_size: int = 20) -> bytes:`
+
+Runs the tapehash 1 algorithm on the preimage and returns a 32-byte hash.
+Computational complexity is tuneable via the `code_size` parameter.
+
+### `tapehash2(preimage: bytes, tape_size_multiplier: int = 2) -> bytes:`
+
+Runs the tapehash2 algorithm on the preimage and returns a 32-byte hash. Memory
+complexity can be tuned via the `tape_size_multiplier` parameter.
+
+### `tapehash3(preimage: bytes, code_size: int = 64, tape_size_multiplier: int = 2) -> bytes:`
+
+Runs the tapehash3 algorithm on the preimage and returns a 32-byte hash.
+Computational complexity is tuneable via the `code_size` parameter. Memory
+complexity is tuneable via the `tape_size_multiplier` parameter.
+
+### `license():`
+
+Copyright (c) 2025 Jonathan Voss (k98kurz) Permission to use, copy, modify,
+and/or distribute this software for any purpose with or without fee is hereby
+granted, provided that the above copyright notice and this permission notice
+appear in all copies. THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS
+ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
+RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE
+USE OR PERFORMANCE OF THIS SOFTWARE.
+
+### `work(state: HasNonceProtocol, serialize: Callable, difficulty: int, hash_algo: Callable) -> HasNonceProtocol:`
+
+Continually increments `state.nonce` until the difficulty score of
+`hash_algo(serialize(state))` >= target, then returns the updated state.
+
+### `calculate_difficulty(val: bytes) -> int:`
+
+Calculates the difficulty of a hash by dividing 2**256 (max int) by the supplied
+val interpreted as a big-endian unsigned int. This provides a linear metric that
+represents the expected amount of work (hashes) that have to be computed on
+average to reach the given hash val or better (lower).
+
+### `calculate_target(difficulty: int) -> int:`
+
+Calculates the target value that a hash must be below to meet the difficulty
+threshold.
+
+### `check_difficulty(val: bytes, difficulty: int) -> bool:`
+
+Returns True if the val has a difficulty score greater than or equal to the
+supplied difficulty, otherwise False.
+
+### `version() -> str:`
+
+Returns the current library version.
+
+

tapehash-0.1.0/license

@@ -0,0 +1,18 @@
+ISC License
+
+Copyleft (c) 2025 Jonathan Voss (k98kurz)
+
+Permission to use, copy, modify, and/or distribute this software
+for any purpose with or without fee is hereby granted, provided
+that the above copyleft notice and this permission notice appear in
+all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
+AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
+CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+

tapehash-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tapehash"
+version = "0.1.0"
+authors = [
+  { name="k98kurz", email="k98kurz@gmail.com" },
+]
+description = "Simple proof-of-work system that uses many hash algorithms."
+readme = "readme.md"
+requires-python = ">=3.10"
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: ISC License (ISCL)",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Developers",
+  "Topic :: Security :: Cryptography",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/k98kurz/tapehash"
+"Repository" = "https://github.com/k98kurz/tapehash"
+"Bug Tracker" = "https://github.com/k98kurz/tapehash/issues"
+
+[project.scripts]
+tapehash1 = "tapehash.cli:run_tapehash1"
+tapehash2 = "tapehash.cli:run_tapehash2"
+tapehash3 = "tapehash.cli:run_tapehash3"
+

tapehash-0.1.0/readme.md

@@ -0,0 +1,151 @@
+# tapehash
+
+Tapehash is a slapdash proof-of-work system that uses a lot of different hash
+algorithms and an opcode execution system for ASIC-resistance. This is meant to
+be a good-enough solution for proof-of-concept systems.
+
+## Installation
+
+```bash
+pip install tapehash
+```
+
+An overview follows, but full documentation can be found
+[here](https://github.com/k98kurz/tapehash/blob/master/dox.md), generated
+automatically by [autodox](https://pypi.org/project/autodox).
+
+## Functions
+
+This package contains three tuneable hashing functions:
+
+- `tapehash1(preimage: bytes, code_size: int = 20) -> bytes:`
+- `tapehash2(preimage: bytes, tape_size_multiplier: int = 2) -> bytes:`
+- `tapehash3(preimage: bytes, code_size: int = 64, tape_size_multiplier: int = 2) -> bytes:`
+
+All three have defaul parameters tuned to require about 0.25-0.3 ms per hash
+(roughly 250-300x as long as sha256 on the reference hardware).
+
+It also includes the following proof-of-work functions:
+
+- `work(state: HasNonceProtocol, serialize: Callable, difficulty: int, hash_algo: Callable) -> HasNonceProtocol:`
+- `calculate_difficulty(val: bytes) -> int:`
+- `calculate_target(difficulty: int) -> int:`
+- `check_difficulty(val: bytes, difficulty: int) -> bool:`
+
+Difficulty is calculated by dividing `2**256` by the big-endian int value of a
+hash, which produces the expected average number of tries to find that hash or
+better (smaller). It is a linear difficulty metric. A target for a given
+difficulty level can then be calculated by dividing `2**256` by the difficulty.
+The `work` function first calculates this target, then increments the `nonce`
+property of `state` until the `hash_algo(serialize(state))` is less than the
+calculated target (unsigned int comparison).
+
+## Use
+
+To use for proof-of-work/hashcash, create a class that follows the
+`HasNonceProtocol` contract (must have a settable `nonce` property) and a
+serialization function, then invoke `work` to find a nonce that meets the
+difficulty threshold. To check a received value, serialize it, hash it, and then
+call `check_difficulty`.
+
+For example, it could be used to filter out spam as in the original hashcash proposal:
+
+```python
+from dataclasses import dataclass, field
+from tapehash import tapehash3, work, check_difficulty, calculate_difficulty
+from packify import pack, unpack
+
+_default_diff_threshold = 128 # average number of attempts to find a nonce
+
+@dataclass
+class Message:
+    message: str = field()
+    nonce: int = field(default=0)
+    def pack(self) -> bytes:
+        return pack((self.message, self.nonce))
+    @classmethod
+    def unpack(cls, data: bytes) -> 'Message':
+        return cls(*unpack(data))
+    def find_nonce(self, difficulty: int = _default_diff_threshold):
+        work(self, lambda m: m.pack(), difficulty, tapehash3)
+    def hash(self) -> bytes:
+        return tapehash3(self.pack())
+    def check(self, difficulty: int = _default_diff_threshold) -> bool:
+        return check_difficulty(self.hash(), difficulty)
+    def difficulty(self) -> int:
+        return calculate_difficulty(self.hash())
+    @classmethod
+    def make(cls, msg: str, difficulty: int = _default_diff_threshold) -> 'Message':
+        m = cls(msg)
+        m.find_nonce(difficulty)
+        return m
+
+def filter(messages: list[Message], difficulty: int = _default_diff_threshold) -> list[Message]:
+    """Filter out spam messages that do not reach the difficulty threshold."""
+    return [m for m in messages if m.check(difficulty)]
+```
+
+Then, a message that has the required difficulty can be generated by calling
+`Message.make`, and a batch of received messages can be verified and filtered
+using the `filter` function.
+
+This example uses my serialization package [packify](https://pypi.org/project/packify)
+for convenience and brevity. Any serialization would do, and a real system would
+benefit from an optimized serialization function rather than a generalized one.
+
+## CLI
+
+Installing this package provides three CLI commands:
+
+- tapehash1
+- tapehash2
+- tapehash3
+
+These three commands function in the same way, with only the algorithm tuning
+parameters being somewhat different:
+
+- All 3 accept a `--help` or `-h` flag to print help text
+- All 3 accept a preimage from stdin, through a `--preimage {string}` parameter,
+  or through a `--file {path}` parameter
+    - NB: `cat file.txt | tapehashX` is equivalent to `tapehashX --file file.txt`
+- All 3 accept a `--from:hex` flag that will parse the preimage as hexadecimal
+- All 3 accept these optional output flags (only 1 at a time):
+    - `--to:raw` will output the digest as raw bytes
+    - `--difficulty` will output the calculated difficulty score of the hash digest
+    - `--check {int}` will output 1 if the digest meets the difficulty threshold
+      {int} or 0 (and an exit code of 2) if it did not
+    - Default behavior is to print the hexadecimal digest
+- tapehash1 and tapehash3 accept `--code_size {int}` or `-cs {int}` tuning
+  parameter (default=20 for tapehash1 and 64 for tapehash3)
+- tapehash2 and tapehash3 accept `--tape_size_multiplier {int}` or `-tsm {int}`
+  tuning parameter (default=2)
+
+An improper invocation will result in an exit value of 1. A proper invocation
+will result in an exit code of 0 in all cases except when `--check {int}` exits
+with 2.
+
+## Testing
+
+Testing has thus far been done manually. I may add a unit test suite at some
+point, but it seems unnecessary for now.
+
+## License
+
+ISC License
+
+Copyleft (c) 2025 Jonathan Voss (k98kurz)
+
+Permission to use, copy, modify, and/or distribute this software
+for any purpose with or without fee is hereby granted, provided
+that the above copyleft notice and this permission notice appear in
+all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
+AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
+CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+

tapehash-0.1.0/tapehash/__init__.py

@@ -0,0 +1,16 @@
+from .algos import tapehash1, tapehash2, tapehash3, license
+from .work import (
+    HasNonceProtocol,
+    calculate_difficulty,
+    calculate_target,
+    check_difficulty,
+    work
+)
+del algos
+
+__version__ = '0.1.0'
+
+def version() -> str:
+    """Returns the current library version."""
+    return __version__
+

tapehash-0.1.0/tapehash/algos.py

@@ -0,0 +1,184 @@
+from hashlib import (
+    sha256, md5,
+    shake_128, shake_256,
+    sha3_256, sha3_512,
+    blake2b, blake2s
+)
+
+
+"""New randomized proof-of-work hashing algorithms inspired roughly by
+    XMR's RandomX but much simpler and shoddier.
+    From https://pastebin.com/xY3B3K8S
+"""
+
+def tapehash1(preimage: bytes, code_size: int = 20) -> bytes:
+    """Runs the tapehash 1 algorithm on the preimage and returns a
+        32-byte hash. Computational complexity is tuneable via the
+        `code_size` parameter.
+    """
+    if type(preimage) is not bytes:
+        raise TypeError('preimage must be bytes')
+    if type(code_size) is not int:
+        raise TypeError('code_size must be an int between 1 and 65,536')
+    if code_size <= 0 or code_size > 65_536:
+        raise ValueError('code_size must be an int between 1 and 65,536')
+
+    # generate the code and the tape
+    code = shake_256(preimage).digest(code_size)
+    tape = bytearray(blake2b(preimage).digest())
+
+    # run the program
+    for i in range(0, len(code)):
+        opcode = code[i] >> 4
+        #pointer = ((code[i] << 4) % 256) >> 4
+        pointer = code[i] & 0b00001111
+        double_pointer = int.from_bytes(code[i:i+2], 'big') % 2
+
+        tape = execute_opcode(opcode, pointer, tape)
+        tape = execute_opcode(opcode, pointer + 16, tape)
+        tape = execute_opcode(opcode, pointer + 32, tape)
+        tape = execute_opcode(opcode, pointer + 48, tape)
+
+    return sha256(tape).digest()
+
+
+def tapehash2(preimage: bytes, tape_size_multiplier: int = 2) -> bytes:
+    """Runs the tapehash2 algorithm on the preimage and returns a
+        32-byte hash. Memory complexity can be tuned via the
+        `tape_size_multiplier` parameter.
+    """
+    if type(preimage) is not bytes:
+        raise TypeError('preimage must be bytes')
+    if type(tape_size_multiplier) is not int:
+        raise TypeError('tape_size_multiplier must be an int between 1 and 65,536')
+    if tape_size_multiplier <= 0 or tape_size_multiplier > 65_536:
+        raise ValueError('tape_size_multiplier must be an int between 1 and 65,536')
+
+    # generate the code and the tape
+    code = blake2b(preimage).digest()
+    tape = bytearray(shake_256(preimage).digest(tape_size_multiplier * 32))
+
+    # run the program
+    for i in range(0, len(code), 2):
+        opcode = code[i] >> 4
+        #pointer = ((code[i] << 4) % 256) >> 4
+        pointer = code[i] & 0b00001111
+        double_pointer = int.from_bytes(code[i:i+2], 'big') % tape_size_multiplier
+
+        tape = execute_opcode(opcode, pointer + double_pointer * 32, tape)
+        tape = execute_opcode(opcode, pointer + 16 + double_pointer * 32, tape)
+
+    return sha256(tape).digest()
+
+
+def tapehash3(
+    preimage: bytes, code_size: int = 64, tape_size_multiplier: int = 2
+) -> bytes:
+    """Runs the tapehash3 algorithm on the preimage and returns a
+        32-byte hash. Computational complexity is tuneable via the
+        `code_size` parameter. Memory complexity is tuneable via the
+        `tape_size_multiplier` parameter.
+    """
+    if type(preimage) is not bytes:
+        raise TypeError('preimage must be bytes')
+    if type(code_size) is not int:
+        raise TypeError('code_size must be an int between 1 and 65,536')
+    if code_size <= 0 or code_size > 65_536:
+        raise ValueError('code_size must be an int between 1 and 65,536')
+    if type(tape_size_multiplier) is not int:
+        raise TypeError('tape_size_multiplier must be an int between 1 and 65,536')
+    if tape_size_multiplier <= 0 or tape_size_multiplier > 65_536:
+        raise ValueError('tape_size_multiplier must be an int between 1 and 65,536')
+
+    # generate the code and the tape
+    code = shake_256(preimage).digest(code_size)
+    tape = bytearray(shake_256(preimage).digest(tape_size_multiplier * 32))
+
+    # run the program
+    for i in range(0, len(code), 2):
+        opcode = code[i] >> 4
+        #pointer = ((code[i] << 4) % 256) >> 4
+        pointer = code[i] & 0b00001111
+        double_pointer = int.from_bytes(code[i:i+2], 'big') % tape_size_multiplier
+
+        tape = execute_opcode(opcode, pointer + double_pointer * 32, tape)
+        tape = execute_opcode(opcode, pointer + 16 + double_pointer * 32, tape)
+
+    return sha256(tape).digest()
+
+
+
+def rotate_tape(tape: bytearray, pointer: int) -> bytes:
+    """Rotates the tape so that the pointer-indexed byte is first."""
+    if not isinstance(tape, bytearray):
+        raise TypeError('tape must be bytearray')
+    if not isinstance(pointer, int):
+        raise TypeError('pointer must be int')
+    if len(tape) < 1:
+        raise ValueError('tape must not be empty')
+    if pointer < 0 or pointer >= len(tape):
+        raise ValueError('pointer must be a valid index of tape')
+
+    new_tape = tape[pointer:]
+    new_tape.extend(tape[:pointer])
+    return bytes(new_tape)
+
+
+def execute_opcode(opcode: int, pointer: int, tape: bytearray) -> bytearray:
+    """Execute a single opcode."""
+    if type(opcode) is not int:
+        raise TypeError('opcode must be an int')
+    if type(pointer) is not int:
+        raise TypeError('pointer must be an int')
+    if type(tape) is not bytearray:
+        raise TypeError('tape must be bytearray')
+    if opcode < 0 or opcode > 15:
+        raise ValueError('opcode must be between 0 and 15')
+    if pointer < 0 or pointer >= len(tape):
+        raise ValueError('pointer must be a valid index of tape')
+
+    operations = {
+        0: lambda data: data, # no op
+        1: lambda data: (data + 1) % 256,
+        2: lambda data: data - 1 if data > 0 else 255,
+        3: lambda data: data >> 1,
+        4: lambda data: (data << 1) % 256,
+        5: lambda data: data ^ 255,
+        6: lambda data: (data * 2) % 256,
+        7: lambda data: (data ** 2) % 256,
+        8: lambda data: (data // 2) % 256,
+        9: lambda data: ((data << 4) % 256) | (data >> 4),
+        10: lambda data: sha256(data).digest()[data[0] % 32],
+        11: lambda data: md5(data).digest()[data[0] % 16],
+        12: lambda data: shake_128(data).digest(data[0] + 1)[data[0]],
+        13: lambda data: sha3_256(data).digest()[data[0] % 32],
+        14: lambda data: sha3_512(data).digest()[data[0] % 64],
+        15: lambda data: blake2s(data).digest()[data[0] % 32]
+    }
+
+    if opcode < 10:
+        tape[pointer] = operations[opcode](tape[pointer])
+    else:
+        tape[pointer] = operations[opcode](rotate_tape(tape, pointer))
+    return tape
+
+
+def license():
+    """Copyright (c) 2025 Jonathan Voss (k98kurz)
+
+        Permission to use, copy, modify, and/or distribute this software
+        for any purpose with or without fee is hereby granted, provided
+        that the above copyright notice and this permission notice appear in
+        all copies.
+
+        THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+        WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
+        WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
+        AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
+        CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+        OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+        NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+        CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+    """
+    return license.__doc__
+

tapehash-0.1.0/tapehash/cli.py

@@ -0,0 +1,270 @@
+from sys import argv, stdin, stdout
+from .algos import tapehash1, tapehash2, tapehash3
+from .work import work, check_difficulty, calculate_difficulty
+
+
+def help_tapehash1():
+    print('Use: command | tapehash1 OR tapehash1 --preimage {str} OR tapehash1 --file path/to/file')
+    print('\t--from:hex - parse preimage as hexadecimal')
+    print('\t--code_size {int} - set the code_size parameter (default=1024)')
+    print('\t-cs {int} - set the code_size parameter (default=1024)')
+    print('\t--to:raw - write the raw hash digest bytes to stdout')
+    print('\t--difficulty - output the difficulty of the hash digest')
+    print('\t--check {int} - outputs 1 if the hash digest meets the ' +
+        'difficulty threshold; outputs 0 and exits with error code 2 '+
+        'if it does not'
+    )
+    print('\nOnly 1 of --to:raw --difficulty --check can be used at a time')
+
+def run_tapehash1() -> None:
+    preimage = b''
+    code_size = 20
+
+    if not stdin.isatty():
+        preimage = stdin.buffer.read()
+
+    if len(argv) > 1:
+        if '--help' in argv or '-h' in argv:
+            return help_tapehash1()
+
+        if '--preimage' in argv:
+            idx = argv.index('--preimage')
+            if len(argv) < idx + 2:
+                print("must supply data after --preimage")
+                exit(1)
+            preimage = argv[idx+1].encode('utf-8')
+
+        if '--file' in argv:
+            idx = argv.index('--file')
+            if len(argv) < idx + 2:
+                print("must supply path after --file")
+                exit(1)
+            with open(argv[idx+1], 'rb') as f:
+                preimage = f.read()
+
+        if '--from:hex' in argv:
+            preimage = bytes.fromhex(preimage.decode('utf-8'))
+
+        if '--code_size' in argv:
+            idx = argv.index('--code_size')
+            if len(argv) < idx + 2:
+                print("must supply integer after --code_size")
+                exit(1)
+            code_size = int(argv[idx+1])
+
+        if '-cs' in argv:
+            idx = argv.index('-cs')
+            if len(argv) < idx + 2:
+                print("must supply integer after -cs")
+                exit(1)
+            code_size = int(argv[idx+1])
+
+        if '--to:raw' in argv:
+            stdout.buffer.write(tapehash1(preimage, code_size))
+            return
+
+        if '--difficulty' in argv:
+            diff = calculate_difficulty(tapehash1(preimage, code_size))
+            print(diff)
+            return
+
+        if '--check' in argv:
+            idx = argv.index('--check')
+            if len(argv) < idx + 2:
+                print("must supply integer after --check")
+                exit(1)
+            target = int(argv[idx+1])
+            digest = tapehash1(preimage, code_size)
+            if check_difficulty(digest, target):
+                print(1)
+                return
+            else:
+                print(0)
+                exit(2)
+
+    print(tapehash1(preimage, code_size).hex())
+
+def help_tapehash2():
+    print('Use: command | tapehash1 OR tapehash1 --preimage {str} OR tapehash2 --file path/to/file')
+    print('\t--from:hex - parse preimage as hexadecimal')
+    print('\t--tape_size_multiplier {int} - set the tape_size_multiplier' +
+        ' parameter (default=1024)'
+    )
+    print('\t-tsm {int} - set the tape_size_multiplier parameter (default=1024)')
+    print('\t--to:raw - write the raw hash digest bytes to stdout')
+    print('\t--difficulty - output the difficulty of the hash digest')
+    print('\t--check {int} - outputs 1 if the hash digest meets the ' +
+        'difficulty threshold; outputs 0 and exits with error code 2 '+
+        'if it does not'
+    )
+    print('\nOnly 1 of --to:raw --difficulty --check can be used at a time')
+
+def run_tapehash2() -> None:
+    preimage = b''
+    tape_size_multiplier = 2
+
+    if not stdin.isatty():
+        preimage = stdin.buffer.read()
+
+    if len(argv) > 1:
+        if '--help' in argv or '-h' in argv:
+            return help_tapehash2()
+
+        if '--preimage' in argv:
+            idx = argv.index('--preimage')
+            if len(argv) < idx + 2:
+                print("must supply data after --preimage")
+                exit(1)
+            preimage = argv[idx+1].encode('utf-8')
+
+        if '--file' in argv:
+            idx = argv.index('--file')
+            if len(argv) < idx + 2:
+                print("must supply path after --file")
+                exit(1)
+            with open(argv[idx+1], 'rb') as f:
+                preimage = f.read()
+
+        if '--from:hex' in argv:
+            preimage = bytes.fromhex(preimage.decode('utf-8'))
+
+        if '--tape_size_multiplier' in argv:
+            idx = argv.index('--tape_size_multiplier')
+            if len(argv) < idx + 2:
+                print("must supply integer after --tape_size_multiplier")
+                exit(1)
+            tape_size_multiplier = int(argv[idx+1])
+
+        if '-tsm' in argv:
+            idx = argv.index('-tsm')
+            if len(argv) < idx + 2:
+                print("must supply integer after -tsm")
+                exit(1)
+            tape_size_multiplier = int(argv[idx+1])
+
+        if '--to:raw' in argv:
+            stdout.buffer.write(tapehash2(preimage, tape_size_multiplier))
+            return
+
+        if '--difficulty' in argv:
+            diff = calculate_difficulty(tapehash2(preimage, tape_size_multiplier))
+            print(diff)
+            return
+
+        if '--check' in argv:
+            idx = argv.index('--check')
+            if len(argv) < idx + 2:
+                print("must supply integer after --check")
+                exit(1)
+            target = int(argv[idx+1])
+            digest = tapehash2(preimage, tape_size_multiplier)
+            if check_difficulty(digest, target):
+                print(1)
+                return
+            else:
+                print(0)
+                exit(2)
+
+    print(tapehash2(preimage, tape_size_multiplier).hex())
+
+def help_tapehash3():
+    print('Use: command | tapehash1 OR tapehash1 --preimage {str} OR tapehash3 --file path/to/file')
+    print('\t--from:hex - parse preimage as hexadecimal')
+    print('\t--code_size {int} - set the code_size parameter (default=1024)')
+    print('\t-cs {int} - set the code_size parameter (default=1024)')
+    print('\t--tape_size_multiplier {int} - set the tape_size_multiplier' +
+        ' parameter (default=1024)'
+    )
+    print('\t-tsm {int} - set the tape_size_multiplier parameter (default=1024)')
+    print('\t--to:raw - write the raw hash digest bytes to stdout')
+    print('\t--difficulty - output the difficulty of the hash digest')
+    print('\t--check {int} - outputs 1 if the hash digest meets the ' +
+        'difficulty threshold; outputs 0 and exits with error code 2 '+
+        'if it does not'
+    )
+    print('\nOnly 1 of --to:raw --difficulty --check can be used at a time')
+
+
+def run_tapehash3() -> None:
+    preimage = b''
+    code_size = 64
+    tape_size_multiplier = 2
+
+    if not stdin.isatty():
+        preimage = stdin.buffer.read()
+
+    if len(argv) > 1:
+        if '--help' in argv or '-h' in argv:
+            return help_tapehash2()
+
+        if '--preimage' in argv:
+            idx = argv.index('--preimage')
+            if len(argv) < idx + 2:
+                print("must supply data after --preimage")
+                exit(1)
+            preimage = argv[idx+1].encode('utf-8')
+
+        if '--file' in argv:
+            idx = argv.index('--file')
+            if len(argv) < idx + 2:
+                print("must supply path after --file")
+                exit(1)
+            with open(argv[idx+1], 'rb') as f:
+                preimage = f.read()
+
+        if '--from:hex' in argv:
+            preimage = bytes.fromhex(preimage.decode('utf-8'))
+
+        if '--code_size' in argv:
+            idx = argv.index('--code_size')
+            if len(argv) < idx + 2:
+                print("must supply integer after --code_size")
+                exit(1)
+            code_size = int(argv[idx+1])
+
+        if '-cs' in argv:
+            idx = argv.index('-cs')
+            if len(argv) < idx + 2:
+                print("must supply integer after -cs")
+                exit(1)
+            code_size = int(argv[idx+1])
+
+        if '--tape_size_multiplier' in argv:
+            idx = argv.index('--tape_size_multiplier')
+            if len(argv) < idx + 2:
+                print("must supply integer after --tape_size_multiplier")
+                exit(1)
+            tape_size_multiplier = int(argv[idx+1])
+
+        if '-tsm' in argv:
+            idx = argv.index('-tsm')
+            if len(argv) < idx + 2:
+                print("must supply integer after -tsm")
+                exit(1)
+            tape_size_multiplier = int(argv[idx+1])
+
+        if '--to:raw' in argv:
+            stdout.buffer.write(tapehash3(preimage, code_size, tape_size_multiplier))
+            return
+
+        if '--difficulty' in argv:
+            diff = calculate_difficulty(tapehash3(preimage, code_size, tape_size_multiplier))
+            print(diff)
+            return
+
+        if '--check' in argv:
+            idx = argv.index('--check')
+            if len(argv) < idx + 2:
+                print("must supply integer after --check")
+                exit(1)
+            target = int(argv[idx+1])
+            digest = tapehash1(preimage, code_size, tape_size_multiplier)
+            if check_difficulty(digest, target):
+                print(1)
+                return
+            else:
+                print(0)
+                exit(2)
+
+    print(tapehash3(preimage, code_size, tape_size_multiplier).hex())
+

tapehash-0.1.0/tapehash/work.py

@@ -0,0 +1,52 @@
+from typing import Protocol, Callable
+import math
+
+
+class HasNonceProtocol(Protocol):
+    """The HasNonceProtocol requires that an implementation has a settable
+        nonce property.
+    """
+    @property
+    def nonce(self) -> int:
+        ...
+    @nonce.setter
+    def nonce(self, val: int):
+        ...
+
+def calculate_difficulty(val: bytes) -> int:
+    """Calculates the difficulty of a hash by dividing 2**256 (max int)
+        by the supplied val interpreted as a big-endian unsigned int.
+        This provides a linear metric that represents the expected
+        amount of work (hashes) that have to be computed on average to
+        reach the given hash val or better (lower).
+    """
+    val = int.from_bytes(val, 'big')
+    if not val:
+        return 2**256
+    return 2**256 // val
+
+def calculate_target(difficulty: int) -> int:
+    """Calculates the target value that a hash must be below to meet
+        the difficulty threshold.
+    """
+    return 2**256 if not difficulty else 2**256 // difficulty
+
+def check_difficulty(val: bytes, difficulty: int) -> bool:
+    """Returns True if the val has a difficulty score greater than or
+        equal to the supplied difficulty, otherwise False.
+    """
+    return calculate_difficulty(val) >= difficulty
+
+def work(
+    state: HasNonceProtocol, serialize: Callable[[HasNonceProtocol], bytes],
+    difficulty: int, hash_algo: Callable[[bytes], bytes]
+) -> HasNonceProtocol:
+    """Continually increments `state.nonce` until the difficulty score of
+        `hash_algo(serialize(state))` >= target, then returns the updated
+        state.
+    """
+    target = calculate_target(difficulty)
+    while int.from_bytes(hash_algo(serialize(state)), 'big') > target:
+        state.nonce += 1
+    return state
+