Convert a big-integer between bases (hex/dec/bin/oct).

Parses value as a from_base integer (a leading 0x/0b/0o and a - sign are accepted) and renders it in to_base, prefixed for non-decimal output. pad_bytes zero-fills the output to that byte width (a minimum, never truncating); it is bit-aligned, so it is rejected for decimal output. Arbitrary precision — a 32-byte RPC value converts losslessly. Returns {value, from_base, to_base, result}. Example: num_convert("255", "dec", "hex") -> result "0xff"

Convert a value between host and network byte order (htons/htonl/ntohs/ntohl).

data is decoded via input_format (hex default). from_order/to_order are little|big|network|host: network is big-endian, host resolves to the platform's sys.byteorder — so on a little-endian box from_order=host to_order=network is htonl/htons. width (bytes) sets a fixed field size: a shorter buffer is left zero-padded up to width, a longer one is split into width-byte groups each swapped independently (array semantics); omit it to swap the whole buffer as one field. Differing orders reverse each field; equal orders only apply the width normalization. Returns {result, from_order, to_order, width, output_format}; result is rendered via output_format. Example: byte_order("0x12345678", "little", "big") -> result "78563412"

Convert a timestamp between textual formats (ISO 8601/RFC 2822/HTTP/unix/strftime) and time zones.

Parses value per from_format (auto sniffs iso8601/rfc2822/http/unix), anchors a NAIVE result with from_zone (an input that already carries an offset ignores it), shifts the instant into to_zone, and renders it as to_format. Formats: iso8601 (RFC 3339), rfc2822, http (IMF-fixdate, always GMT), unix/unix_ms/unix_us/unix_ns epoch, and strftime (needs format_pattern on whichever side uses it). Zones are an IANA name (Europe/Budapest), UTC, or a ±HH:MM offset. Returns {result, from_format, to_format, zone, unix}; from_format echoes the detected format under auto, unix is the integer epoch-seconds anchor. Example: time_convert("1700000000", "iso8601") -> result "2023-11-14T22:13:20+00:00"

Compute a cryptographic, CRC, or fast non-crypto digest of bytes.

length (output bytes) is required for shake_*; key keys blake2b/blake2s (decoded with input_format); seed reseeds xxh*/fnv1a_*. Returns {algorithm, digest, output_format, bits}; CRC and fast hashes additionally report their integer value as int. Example: hash("abc", "sha256") -> digest "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"

Checksum a file on disk, optionally verifying it against an expected digest.

Crypto digests stream the file in 1 MiB chunks; CRC/xxh/fnv read it whole. When expected is supplied, verified reports whether it matches the digest (compared as bytes, so case/0x/whitespace differences are tolerated). Returns {algorithm, digest, path, size}, plus verified when expected is given. Example: hash_file("/etc/hostname", "sha256") -> {digest, path, size, ...}

Compute or verify an HMAC authentication tag over data with a secret key.

data and key are decoded with input_format / key_format. When expected is supplied, valid reports a constant-time comparison against the computed tag (tolerant of case/0x/whitespace in the expected value). Returns {algorithm, mac, output_format}, plus valid when expected is given. Example: hmac("msg", "key") -> mac "2d93cbc1be167bcb1637a4a23cbff01a..."

Encode bytes/text into a string form (base-N, URL, IDNA, bech32, hexdump, bytes32).

data is decoded to bytes via input_format (text|hex|base64). options is a per-scheme dict: padding (bool, default true — base32/base64 family), alphabet (custom symbol set — base58/base62), hrp (required for bech32/bech32m), width (bytes per line — hexdump, default 16). idna and bytes32 read data as a text string / short string respectively. bytes32 is a fixed-width 32-byte EVM word: inputs of <32 bytes are right-padded with 0x00; decode returns all 32 bytes (it does NOT strip trailing nulls, so the round-trip is lossless — rstrip them yourself for a short string). Returns {scheme, encoded}. Example: encode("hello", "base64") -> encoded "aGVsbG8="

Decode a base-N/URL/IDNA/bech32/hexdump string back to bytes or text.

The inverse of encode over the same scheme set. The recovered bytes are rendered per output_format (text=UTF-8 | hex=bare, no 0x | base64); pick hex/base64 for binary payloads that are not valid UTF-8. options carries alphabet for base58/base62. base58/base58check/base45/idna need the encoding extra. Returns {scheme, decoded, output_format}; bech32/bech32m additionally return their hrp. Example: decode("aGVsbG8=", "base64") -> decoded "hello"

Build a data: URI from a payload, or parse one into its parts (RFC 2397).

action=build (needs data, read via input_format): wraps it as data:[media_type][;base64],<payload>; base64=true base64-encodes the payload, else it is percent-encoded. action=parse (needs uri): returns media_type (defaulting to text/plain when absent), the ;k=v parameters, is_base64, and the decoded data rendered via output_format. Example: data_uri("build", media_type="text/plain", data="hi") -> uri "data:text/plain;base64,aGk="

Edit a hex byte-buffer: pad/trim to width, slice, concat, size, or 0x-prefix.

data is hex (a leading 0x is optional). Actions:

• pad: widen to length bytes with the fill byte on side (left=prepend, right=append); never truncates if already wider.

• trim: strip the fill byte (default 00) from side (left=leading, right=trailing) — the inverse of pad.

• slice: take data[start:end] (Python indexing; negatives allowed).

• concat: append each hex buffer in parts to data.

• size: report the byte length, buffer unchanged.

• prefix: side=left adds a 0x prefix, side=right strips it.

Returns {action, result, size}: result is the 0x-prefixed hex buffer (bare hex when prefix-stripping), size its byte length. Example: a 20-byte address -> 32-byte log topic: bytes_edit("pad", "0x1234", length=4, side="left") -> result "0x00001234"

Normalize text to a Unicode normalization form (NFC/NFD/NFKC/NFKD).

NFC/NFD are canonical compose/decompose; NFKC/NFKD also fold compatibility characters (ligatures, full-width, circled digits) to their plain forms. changed is true when result differs from the input — i.e. the text was not already in form. Returns {form, result, changed}. Example: unicode_normalize("fi", "NFKC") -> result "fi" (fi ligature, ① -> 1)

Convert text between character encodings (e.g. latin-1/cp1252 <-> utf-8).

The input is encoded under from_charset to recover its raw bytes, which are then decoded under to_charset. If the bytes aren't valid to_charset text they're returned as bare hex with output_format='hex' (otherwise 'text'). errors selects the codec error handler (strict|replace|ignore|…). Returns {from_charset, to_charset, result, output_format}. Example: charset_transcode("café", "cp1252", "utf-8") -> result "café"

Escape text for a source-code or markup context (JSON/JS/C/shell/HTML/...).

style picks the convention: json|js|python|c|backslash (backslash escapes), html|xml (entities), unicode_escape (\uXXXX/\xNN), quoted_printable, or mime_word (=?UTF-8?B?...?=). shell yields a paste-safe single-quoted token. For URL %-escaping use encode(scheme='url') instead. An unknown style raises ValueError. Returns {style, result}. Inverse: string_unescape. Example: string_escape('a"b', "json") -> result 'a"b'

Reverse a source-code or markup escaping back to the original text.

Style-for-style inverse of string_escape (json|js|python|c|backslash escape sequences, html|xml entities, unicode_escape, quoted_printable, mime_word, and shell). Malformed escape sequences (and an unknown style) raise ValueError. Returns {style, result}. Example: string_unescape('a\nb', "json") -> result "ab"

Break text into its code points with names and UTF-8/16/32 byte views.

Returns one entry per Unicode scalar (astral characters stay whole): the char, its codepoint as 'U+XXXX', the Unicode name (or a placeholder for unnamed control/format/private-use scalars), and big-endian utf8/utf16/utf32 byte views as hex. count is the code-point length, which differs from len() only for surrogate-pair-bearing input. Example: codepoints("é") -> count 1, char "é" at codepoint "U+00E9"

Generate cryptographically secure random bytes, a token, or a passphrase.

All randomness is drawn from the OS CSPRNG (secrets). kind selects the shape and which sizing arg applies: bytes|hex|urlsafe draw nbytes (default 32) random bytes — bytes renders them via output_format (hex/base64), hex is the same bytes as hex, urlsafe is RFC 4648 url-safe base64; token is a length-character (default 32) alphanumeric [A-Za-z0-9] string; passphrase joins words (default 6) words with separator (default '-'), drawn from wordlist or the bundled EFF large diceware list. Returns {kind, value, entropy_bits}; the value is the only secret and is never logged elsewhere. Example: random("hex", nbytes=4) -> value "6a08ed95" (8 hex chars, 32 bits)

Compute an Ethereum hash: raw keccak-256, EIP-191, or EIP-712 typed-data.

Returns {kind, hash}. For kind=eip712 the result also carries {domain_separator, struct_hash}, the two EIP-712 component hashes. Note keccak-256 is the pre-NIST Ethereum variant, not hashlib's SHA3-256.

Example: eth_hash("keccak256", "hello", "text") -> hash="0x1c8aff950685c2ed4bc3174f3472287b56d9517b9c948127319a09a7a36deac8".

Derive the 4-byte function selector or 32-byte event topic from a signature.

Returns {kind, signature (canonicalized), selector} for functions, or {kind, signature, topic0} for events.

Example: eth_selector("transfer(address,uint256)") -> selector="0xa9059cbb".

RLP-encode structured data, or RLP-decode a hex string.

Encode data is a recursive structure: a leaf (hex string, or a non-negative integer stored minimal big-endian) or a JSON array of items (nested allowed); a JSON-array string is parsed too. action=encode -> {encoded:'0x...'}. Decode data is a 0x-hex string; action=decode -> {decoded} with leaves as 0x-hex and lists as arrays.

Example: rlp_codec("encode", ["0x636174"]) -> encoded="0xc483636174".

ABI-encode values or ABI-decode call/return/log data.

types is a list of ABI type strings (e.g. ["uint256", "address", "(uint8,bytes)[]"]); aliases like uint/int/byte are normalized. action=encode (needs values) -> {encoded, mode}. mode=packed is abi.encodePacked (tight, no padding) and is encode-only. action=decode (needs data, standard only) -> {values}; ints are returned as decimal strings and addresses EIP-55 checksummed.

Example: abi_codec("encode", ["uint256"], [69]) -> encoded="0x00..0045" (the 32-byte word 0x...0045).

Compute the storage slot for a mapping/array entry given a layout.

layout: {"kind": "mapping"|"dynamic_array", "slot": , ...} mapping -> needs key; "key_type" (default uint256). For nested mappings pass key (and optionally "key_type") as lists. dynamic_array -> needs index; optional "element_size" in slots (default 1). Returns {slot, slot_hex}: the slot as a decimal string and a 0x 32-byte word.

Example: eth_storage_slot({"kind":"mapping","slot":1}, "0x0000000000000000000000000000000000000000") -> slot_hex="0xa6eef7e35abe7026729641147f7915573c7e97b47efa546f5f6e3230263bcb49".

Serialize signed tx fields into a raw transaction, or decode a raw tx.

action=encode (needs fields) serializes the supplied, already-signed fields (it does not sign) -> {type, raw:'0x...', hash}. fields is an object; the type is taken from a type key or inferred from which fields are present (maxFeePerGas -> 1559, blobVersionedHashes -> 4844, accessList -> 2930, else legacy). Numbers accept int / decimal / 0x-hex; to/data are 0x-hex. action=decode (needs data, a 0x-hex raw tx) -> {type, fields, hash, from}, recovering from from the signature; numeric fields come back as decimal strings, addresses EIP-55 checksummed.

Example: eth_tx_codec("encode", fields={"nonce":0,"gasPrice":"0x09184e72a000", "gasLimit":"0x2710","to":"0x00..00","value":0,"data":"0x"}) -> type=0, raw="0xe5808609184e72a00082271094...808080".

Apply or verify an EIP-55 mixed-case address checksum.

action=encode -> {action, address} with the checksummed (mixed-case) address. action=verify -> {action, address (checksummed), valid}, plus a reason when the supplied casing does not match the EIP-55 checksum.

Example: eth_address_case("encode", "0x52908400098527886e0f7030069857d2e4169ee7") -> address="0x52908400098527886E0F7030069857D2E4169EE7".

Compute the EIP-137 namehash (and labelhash) of an ENS name.

The name is hashed exactly as given; EIP-137 expects it already UTS-46 normalized (use unicode_normalize first if needed), and empty labels from a stray dot are rejected. Returns {name, namehash, labelhash}, where labelhash is the keccak of the leftmost label — for a single label that is the .eth registrar token id for that name.

Example: ens_namehash("vitalik.eth") -> namehash="0xee6c4522aab0003e8d14cd40a6af439055fd2577951148c14b6cea9a53475835".

Discovery / health-check entrypoint: report availability and enabled toolsets.

Returns six keys: status ("available"), name, version (package version), python (runtime version), mcp_sdk (MCP SDK version, or "unknown"), and toolsets (sorted list of live optional toolsets). Example: {"status":"available","name":"mcp-bytesmith","version":"0.1.0", "python":"3.12.3","mcp_sdk":"1.2.0","toolsets":["ethereum","serialize"]}