laantungir/amethyst
1
0
Fork 0
mirror of https://github.com/vitorpamplona/amethyst.git synced 2026-10-06 11:48:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3837 from vitorpamplona/claude/quartz-hex-encode-decode-xggbv2

Browse Source 
Add optimized decode64/decode128 and encode64/encode128 to Hex
This commit is contained in:
Vitor Pamplona
2026-07-31 22:51:50 -04:00
committed by GitHub
parent 77ff9e9699 729fb1bc17
commit d6333989a4
3 changed files with 263 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
benchmark/src/androidTest/java/com/vitorpamplona/quartz/benchmark/HexBenchmark.kt
+40
View File
@@ -39,9 +39,13 @@ class HexBenchmark {
@get:Rule val r = BenchmarkRule()
val hex = "48a72b485d38338627ec9d427583551f9af4f016c739b8ec0d6313540a8b12cf"
val hex128 = hex + "b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9"
val bytes =
fr.acinq.secp256k1.Hex
.decode(hex)
val bytes64 =
fr.acinq.secp256k1.Hex
.decode(hex128)
@Test
fun hexIsEqual() {
@@ -103,4 +107,40 @@ class HexBenchmark {
fun isHex64() {
r.measureRepeated { Hex.isHex64(hex) }
}
@Test
fun hexDecode64() {
r.measureRepeated { Hex.decode64(hex) }
}
@Test
fun hexDecode64OrNull() {
r.measureRepeated { Hex.decode64OrNull(hex) }
}
@Test
fun hexEncode64() {
r.measureRepeated { Hex.encode64(bytes) }
}
@Test
fun hexDecode128() {
r.measureRepeated { Hex.decode128(hex128) }
}
@Test
fun hexEncode128() {
r.measureRepeated { Hex.encode128(bytes64) }
}
/** The pre-existing two-pass way to safely decode an id, for comparison with [hexDecode64OrNull]. */
@Test
fun hexIsHex64ThenDecode() {
r.measureRepeated { if (Hex.isHex64(hex)) Hex.decode(hex) else null }
}
@Test
fun hexToLong256() {
r.measureRepeated { Hex.toLong256(hex) }
}
}
quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/utils/Hex.kt
+110 -21
View File
@@ -36,6 +36,8 @@ package com.vitorpamplona.quartz.utils
* val hex = Hex.encode(bytes) // ByteArray -> lower-case hex
* val bytes = Hex.decode(hex) // hex (any case) -> ByteArray
* if (Hex.isHex64(id)) { ... } // is this a valid 32-byte hex id?
* val id = Hex.decode64(idHex) // exactly 64 chars or it throws
* val sig = Hex.decode128OrNull(sigHex) // exactly 128 chars or null
* ```
*/
object Hex {
@@ -183,17 +185,100 @@ object Hex {
require(hex.length and 1 == 0) {
"Invalid hex $hex"
}
return ByteArray(hex.length / 2) {
(hexToByte[hex[2 * it].code] shl 4 or hexToByte[hex[2 * it + 1].code]).toByte()
// table hoisted into a local: the JVM/ART doesn't reliably prove the
// field load loop-invariant, and re-loading it per char costs ~25%
val table = hexToByte
val out = ByteArray(hex.length shr 1)
var c = 0
for (i in out.indices) {
out[i] = ((table[hex[c++].code] shl 4) or table[hex[c++].code]).toByte()
}
return out
}
/**
* Decodes a 32-byte pubkey/event id, accepting only exactly 64 hex chars
* (upper or lower case). Throws [IllegalArgumentException] on any other
* length or on non-hex characters — use [decode64OrNull] for untrusted
* input. Single pass: validation is folded into the decode, so this is
* faster than `isHex64` + [decode].
*/
fun decode64(hex: String): ByteArray = decode64OrNull(hex) ?: throw IllegalArgumentException("Invalid 64-char hex $hex")
/** Like [decode64] but returns null instead of throwing. */
fun decode64OrNull(hex: String): ByteArray? = if (hex.length == 64) decodeExactOrNull(hex, 32) else null
/**
* Decodes a 64-byte value (a Schnorr signature), accepting only exactly
* 128 hex chars (upper or lower case). Throws [IllegalArgumentException]
* on any other length or on non-hex characters — use [decode128OrNull]
* for untrusted input.
*/
fun decode128(hex: String): ByteArray = decode128OrNull(hex) ?: throw IllegalArgumentException("Invalid 128-char hex $hex")
/** Like [decode128] but returns null instead of throwing. */
fun decode128OrNull(hex: String): ByteArray? = if (hex.length == 128) decodeExactOrNull(hex, 64) else null
/**
* Decodes [hex] into [byteLen] bytes, or null if any char is not a hex
* digit. The caller has already checked `hex.length == 2 * byteLen`.
*
* Tuned at the bytecode level (see `HexBenchmark`): the table is hoisted
* into a local (the JVM/ART can't always prove the field load loop
* invariant), `inline` turns [byteLen] into a compile-time trip count at
* each call site, and validation is branchless — the table yields -1 for
* invalid chars and `255 - code` goes negative for chars above 0xFF (e.g.
* emoji, kept in bounds by the `and 0xFF` mask), so OR-ing everything into
* one accumulator and sign-checking it at the end rejects all bad input
* with no branches and no exception table. ~25% faster than the same loop
* with a per-iteration field load and a try/catch guard, and ~2x faster
* than `isHex64` + [decode].
*/
@Suppress("NOTHING_TO_INLINE")
private inline fun decodeExactOrNull(
hex: String,
byteLen: Int,
): ByteArray? {
val table = hexToByte
val out = ByteArray(byteLen)
var acc = 0
var c = 0
for (i in 0 until byteLen) {
val c0 = hex[c++].code
val c1 = hex[c++].code
val b = (table[c0 and 0xFF] shl 4) or table[c1 and 0xFF]
acc = acc or b or (255 - c0) or (255 - c1)
out[i] = b.toByte()
}
return if (acc < 0) null else out
}
/**
* Encodes a 32-byte pubkey/event id as a 64-char lower-case hex string.
* Throws [IllegalArgumentException] when [input] is not exactly 32 bytes.
*/
fun encode64(input: ByteArray): String {
require(input.size == 32) { "Expected 32 bytes, got ${input.size}" }
return encode(input)
}
/**
* Encodes a 64-byte value (a Schnorr signature) as a 128-char lower-case
* hex string. Throws [IllegalArgumentException] when [input] is not
* exactly 64 bytes.
*/
fun encode128(input: ByteArray): String {
require(input.size == 64) { "Expected 64 bytes, got ${input.size}" }
return encode(input)
}
/** Encodes [input] as a lower-case hex string (two chars per byte). */
fun encode(input: ByteArray): String {
val table = byteToHex
val out = CharArray(input.size * 2)
var outIdx = 0
for (i in 0 until input.size) {
val chars = byteToHex[input[i].toInt() and 0xFF]
val chars = table[input[i].toInt() and 0xFF]
out[outIdx++] = (chars shr 8).toChar()
out[outIdx++] = (chars and 0xFF).toChar()
}
@@ -212,23 +297,26 @@ object Hex {
fun readLong(
hex: String,
offset: Int,
): Long =
(hexToByte[hex[offset].code].toLong() shl 60) or
(hexToByte[hex[offset + 1].code].toLong() shl 56) or
(hexToByte[hex[offset + 2].code].toLong() shl 52) or
(hexToByte[hex[offset + 3].code].toLong() shl 48) or
(hexToByte[hex[offset + 4].code].toLong() shl 44) or
(hexToByte[hex[offset + 5].code].toLong() shl 40) or
(hexToByte[hex[offset + 6].code].toLong() shl 36) or
(hexToByte[hex[offset + 7].code].toLong() shl 32) or
(hexToByte[hex[offset + 8].code].toLong() shl 28) or
(hexToByte[hex[offset + 9].code].toLong() shl 24) or
(hexToByte[hex[offset + 10].code].toLong() shl 20) or
(hexToByte[hex[offset + 11].code].toLong() shl 16) or
(hexToByte[hex[offset + 12].code].toLong() shl 12) or
(hexToByte[hex[offset + 13].code].toLong() shl 8) or
(hexToByte[hex[offset + 14].code].toLong() shl 4) or
hexToByte[hex[offset + 15].code].toLong()
): Long {
// table hoisted into a local — one field load instead of sixteen
val t = hexToByte
return (t[hex[offset].code].toLong() shl 60) or
(t[hex[offset + 1].code].toLong() shl 56) or
(t[hex[offset + 2].code].toLong() shl 52) or
(t[hex[offset + 3].code].toLong() shl 48) or
(t[hex[offset + 4].code].toLong() shl 44) or
(t[hex[offset + 5].code].toLong() shl 40) or
(t[hex[offset + 6].code].toLong() shl 36) or
(t[hex[offset + 7].code].toLong() shl 32) or
(t[hex[offset + 8].code].toLong() shl 28) or
(t[hex[offset + 9].code].toLong() shl 24) or
(t[hex[offset + 10].code].toLong() shl 20) or
(t[hex[offset + 11].code].toLong() shl 16) or
(t[hex[offset + 12].code].toLong() shl 12) or
(t[hex[offset + 13].code].toLong() shl 8) or
(t[hex[offset + 14].code].toLong() shl 4) or
t[hex[offset + 15].code].toLong()
}
/**
* Reads the first 64 bits (16 hex chars) of [hex] as a single [Long].
@@ -272,9 +360,10 @@ object Hex {
id: String,
ourId: ByteArray,
): Boolean {
val table = byteToHex
var charIndex = 0
for (i in 0 until ourId.size) {
val chars = byteToHex[ourId[i].toInt() and 0xFF]
val chars = table[ourId[i].toInt() and 0xFF]
if (
id[charIndex++] != (chars shr 8).toChar() ||
id[charIndex++] != (chars and 0xFF).toChar()
quartz/src/commonTest/kotlin/com/vitorpamplona/quartz/utils/HexExactSizeTest.kt
+113
View File
@@ -0,0 +1,113 @@
/*
* Copyright (c) 2025 Vitor Pamplona
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of
* this software and associated documentation files (the "Software"), to deal in
* the Software without restriction, including without limitation the rights to use,
* copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
* Software, and to permit persons to whom the Software is furnished to do so,
* subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
* FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
* COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
* AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
* WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package com.vitorpamplona.quartz.utils
import kotlin.test.Test
import kotlin.test.assertContentEquals
import kotlin.test.assertEquals
import kotlin.test.assertFailsWith
import kotlin.test.assertNull
class HexExactSizeTest {
val id64 = "48a72b485d38338627ec9d427583551f9af4f016c739b8ec0d6313540a8b12cf"
val sig128 = id64 + "b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9"
@Test
fun decode64RoundTrip() {
assertEquals(id64, Hex.encode64(Hex.decode64(id64)))
assertContentEquals(Hex.decode(id64), Hex.decode64(id64))
assertContentEquals(Hex.decode(id64), Hex.decode64OrNull(id64))
}
@Test
fun decode64AcceptsUpperCase() {
assertContentEquals(Hex.decode(id64), Hex.decode64(id64.uppercase()))
}
@Test
fun decode64RejectsWrongLengths() {
assertFailsWith<IllegalArgumentException> { Hex.decode64("") }
assertFailsWith<IllegalArgumentException> { Hex.decode64(id64.drop(1)) }
assertFailsWith<IllegalArgumentException> { Hex.decode64(id64.drop(2)) }
assertFailsWith<IllegalArgumentException> { Hex.decode64(id64 + "ab") }
assertFailsWith<IllegalArgumentException> { Hex.decode64(sig128) }
assertNull(Hex.decode64OrNull(""))
assertNull(Hex.decode64OrNull(id64.drop(2)))
assertNull(Hex.decode64OrNull(id64 + "ab"))
assertNull(Hex.decode64OrNull(sig128))
}
@Test
fun decode64RejectsInvalidChars() {
// every position, both a plain non-hex char and an emoji (code > 0xFF)
for (i in 0 until 64) {
val withG = id64.substring(0, i) + "g" + id64.substring(i + 1)
assertNull(Hex.decode64OrNull(withG), withG)
assertFailsWith<IllegalArgumentException> { Hex.decode64(withG) }
}
val withEmoji = "🥰" + id64.drop(2)
assertNull(Hex.decode64OrNull(withEmoji))
assertFailsWith<IllegalArgumentException> { Hex.decode64(withEmoji) }
}
@Test
fun decode128RoundTrip() {
assertEquals(sig128, Hex.encode128(Hex.decode128(sig128)))
assertContentEquals(Hex.decode(sig128), Hex.decode128(sig128))
assertContentEquals(Hex.decode(sig128), Hex.decode128OrNull(sig128.uppercase()))
}
@Test
fun decode128RejectsWrongLengthsAndInvalidChars() {
assertFailsWith<IllegalArgumentException> { Hex.decode128("") }
assertFailsWith<IllegalArgumentException> { Hex.decode128(id64) }
assertFailsWith<IllegalArgumentException> { Hex.decode128(sig128.drop(2)) }
assertFailsWith<IllegalArgumentException> { Hex.decode128(sig128 + "ab") }
assertNull(Hex.decode128OrNull(id64))
assertNull(Hex.decode128OrNull(sig128.dropLast(1) + "x"))
assertNull(Hex.decode128OrNull("🥰" + sig128.drop(2)))
}
@Test
fun encodeRejectsWrongSizes() {
assertFailsWith<IllegalArgumentException> { Hex.encode64(ByteArray(31)) }
assertFailsWith<IllegalArgumentException> { Hex.encode64(ByteArray(33)) }
assertFailsWith<IllegalArgumentException> { Hex.encode64(ByteArray(64)) }
assertFailsWith<IllegalArgumentException> { Hex.encode128(ByteArray(32)) }
assertFailsWith<IllegalArgumentException> { Hex.encode128(ByteArray(63)) }
assertFailsWith<IllegalArgumentException> { Hex.encode128(ByteArray(65)) }
}
@Test
fun randomsMatchGenericDecode() {
for (i in 0..1000) {
val id = RandomInstance.bytes(32)
assertEquals(Hex.encode(id), Hex.encode64(id))
assertContentEquals(id, Hex.decode64(Hex.encode64(id)))
val sig = RandomInstance.bytes(64)
assertEquals(Hex.encode(sig), Hex.encode128(sig))
assertContentEquals(sig, Hex.decode128(Hex.encode128(sig)))
}
}
}