uUR.c

#include "py/obj.h"
#include "py/objexcept.h"
#include "py/objstr.h"
#include "py/runtime.h"
#include "src/types/bip39.h"
#include "src/types/bytes_type.h"
#include "src/types/output.h"
#include "src/types/psbt.h"
#include "src/ur.h"
#include "src/ur_decoder.h"
#include "src/ur_encoder.h"
#include "src/utils.h" // is_ur_type()

// ---------------------------------------------------------------------------
// MicroPython version compatibility.
//
// MicroPython's C API changed across several releases: MP_REGISTER_MODULE
// lost its third (enable-flag) argument in v1.19, the "type slots" refactor
// (MP_DEFINE_CONST_OBJ_TYPE) landed in v1.20, and finaliser allocation moved
// to mp_obj_malloc_with_finaliser in v1.23 — so each change is probed
// independently rather than through one version gate. This binding supports
// BOTH the modern API (e.g. MicroPython 1.27) and the older MaixPy-era API
// (< 1.19, e.g. the build Krux runs on). The trivial differences are absorbed
// by the two shims below so the body of this file uses one (modern) spelling;
// the type definitions and module registration, which cannot be unified
// cleanly, use explicit #if/#else with the legacy branch kept verbatim.
// ---------------------------------------------------------------------------

// MP_ERROR_TEXT (compressed ROM error strings) arrived in v1.12; on older
// builds that lack it, fall back to the raw string.
#ifndef MP_ERROR_TEXT
#define MP_ERROR_TEXT(x) (x)
#endif

// mp_obj_malloc_with_finaliser(struct_type, obj_type) allocates a GC object
// with a finaliser and sets its type. On builds that predate it (< v1.23),
// express it in terms of the legacy m_new_obj_with_finaliser() + an explicit
// base.type set.
#ifndef mp_obj_malloc_with_finaliser
#define mp_obj_malloc_with_finaliser(struct_type, obj_type)                    \
  ({                                                                           \
    struct_type *_uur_o = m_new_obj_with_finaliser(struct_type);               \
    _uur_o->base.type = (obj_type);                                            \
    _uur_o;                                                                    \
  })
#endif

// URDecoder class structure
typedef struct {
  mp_obj_base_t base;
  ur_decoder_t *decoder;
} mp_obj_ur_decoder_t;

// UREncoder class structure
typedef struct {
  mp_obj_base_t base;
  ur_encoder_t *encoder;
  mp_obj_t fountain_encoder_cached; // Cached fountain_encoder wrapper to
                                    // prevent memory leaks
} mp_obj_ur_encoder_t;

// UR class structure for returning results (matches Python UR interface)
typedef struct {
  mp_obj_base_t base;
  ur_t *ur;
} mp_obj_ur_t;

// UR implementation (matches Python UR class)
static void ur_print(const mp_print_t *print, mp_obj_t self_in,
                     mp_print_kind_t kind) {
  (void)kind;
  mp_obj_ur_t *self = MP_OBJ_TO_PTR(self_in);
  if (self->ur) {
    mp_printf(print, "UR(type='%s')", ur_get_type(self->ur));
  } else {
    mp_printf(print, "UR(invalid)");
  }
}

static mp_obj_t ur_make_new(const mp_obj_type_t *type, size_t n_args,
                            size_t n_kw, const mp_obj_t *args) {
  mp_arg_check_num(n_args, n_kw, 2, 2, false);

  // Extract type and CBOR data from args
  const char *ur_type = mp_obj_str_get_str(args[0]);

  mp_buffer_info_t cbor_buf;
  mp_get_buffer_raise(args[1], &cbor_buf, MP_BUFFER_READ);

  // Distinguish bad arguments (ValueError) from allocation failure
  // (MemoryError): ur_new returns NULL for both. Matches the CPython binding.
  if (!is_ur_type(ur_type)) {
    mp_raise_msg(
        &mp_type_ValueError,
        MP_ERROR_TEXT(
            "invalid UR type (want [a-z0-9-], no leading/trailing '-')"));
  }
  if (cbor_buf.len == 0) {
    mp_raise_msg(&mp_type_ValueError, MP_ERROR_TEXT("cbor must not be empty"));
  }

  // Create internal UR object first so a failure doesn't leak the wrapper
  // through the exception long-jump in mp_raise_msg.
  ur_t *ur = ur_new(ur_type, cbor_buf.buf, cbor_buf.len);
  if (!ur) {
    mp_raise_msg(&mp_type_MemoryError,
                 MP_ERROR_TEXT("Failed to create UR object"));
  }

  // with_finaliser so __del__ (ur_del) runs on GC and frees ur_t.
  mp_obj_ur_t *self = mp_obj_malloc_with_finaliser(mp_obj_ur_t, type);
  self->ur = ur;

  return MP_OBJ_FROM_PTR(self);
}

static mp_obj_t ur_del(mp_obj_t self_in) {
  mp_obj_ur_t *self = MP_OBJ_TO_PTR(self_in);
  if (self->ur) {
    ur_free(self->ur);
    self->ur = NULL;
  }
  return mp_const_none;
}
static MP_DEFINE_CONST_FUN_OBJ_1(ur_del_obj, ur_del);

// UR attributes
static void ur_attr(mp_obj_t self_in, qstr attr, mp_obj_t *dest) {
  mp_obj_ur_t *self = MP_OBJ_TO_PTR(self_in);

  if (dest[0] == MP_OBJ_NULL) {
    // Load attribute
    if (attr == MP_QSTR_type) {
      if (self->ur) {
        dest[0] = mp_obj_new_str(ur_get_type(self->ur),
                                 strlen(ur_get_type(self->ur)));
      } else {
        dest[0] = mp_const_none;
      }
    } else if (attr == MP_QSTR_cbor) {
      if (self->ur) {
        // A snapshot copy of the payload, so hand it out as immutable bytes:
        // writing to a copy could never reach the UR. Same on the CPython side.
        dest[0] =
            mp_obj_new_bytes(ur_get_cbor(self->ur), ur_get_cbor_len(self->ur));
      } else {
        dest[0] = mp_const_none;
      }
    }
  }
}

// Value equality over (type, cbor) — consumers compare decoded URs against
// expected ones, and identity comparison would make every such check fail.
// A closed UR (payload freed by __del__) equals only another closed UR.
static mp_obj_t ur_binary_op(mp_binary_op_t op, mp_obj_t lhs_in,
                             mp_obj_t rhs_in) {
  // This slot is only reachable through mp_type_ur, so lhs is always a UR;
  // comparing against its own type avoids naming mp_type_ur before it is
  // defined (its storage class differs between the two API branches below).
  if (op != MP_BINARY_OP_EQUAL ||
      mp_obj_get_type(rhs_in) != mp_obj_get_type(lhs_in)) {
    return MP_OBJ_NULL; // op not supported
  }
  const ur_t *lhs = ((mp_obj_ur_t *)MP_OBJ_TO_PTR(lhs_in))->ur;
  const ur_t *rhs = ((mp_obj_ur_t *)MP_OBJ_TO_PTR(rhs_in))->ur;
  bool eq;
  if (!lhs || !rhs) {
    eq = (lhs == rhs);
  } else {
    size_t lhs_len = ur_get_cbor_len(lhs);
    eq = strcmp(ur_get_type(lhs), ur_get_type(rhs)) == 0 &&
         lhs_len == ur_get_cbor_len(rhs) &&
         memcmp(ur_get_cbor(lhs), ur_get_cbor(rhs), lhs_len) == 0;
  }
  return eq ? mp_const_true : mp_const_false;
}

// Hash over the same (type, cbor) the comparison uses, so equal URs hash
// equal — without this the default identity hash would break dict/set use.
static mp_obj_t ur_unary_op(mp_unary_op_t op, mp_obj_t self_in) {
  if (op != MP_UNARY_OP_HASH) {
    return MP_OBJ_NULL; // op not supported
  }
  mp_obj_ur_t *self = MP_OBJ_TO_PTR(self_in);
  if (!self->ur) {
    return MP_OBJ_NEW_SMALL_INT(0);
  }
  const char *type = ur_get_type(self->ur);
  mp_uint_t hash =
      qstr_compute_hash((const byte *)type, strlen(type)) ^
      qstr_compute_hash(ur_get_cbor(self->ur), ur_get_cbor_len(self->ur));
  return MP_OBJ_NEW_SMALL_INT(hash);
}

// UR locals dict
static const mp_rom_map_elem_t ur_locals_dict_table[] = {
    {MP_ROM_QSTR(MP_QSTR___del__), MP_ROM_PTR(&ur_del_obj)},
};
static MP_DEFINE_CONST_DICT(ur_locals_dict, ur_locals_dict_table);

#if defined(MP_DEFINE_CONST_OBJ_TYPE)
MP_DEFINE_CONST_OBJ_TYPE(mp_type_ur, MP_QSTR_UR, MP_TYPE_FLAG_NONE, make_new,
                         ur_make_new, print, ur_print, attr, ur_attr, unary_op,
                         ur_unary_op, binary_op, ur_binary_op, locals_dict,
                         &ur_locals_dict);
#else
static const mp_obj_type_t mp_type_ur = {
    {&mp_type_type},         .name = MP_QSTR_UR,
    .print = ur_print,       .make_new = ur_make_new,
    .unary_op = ur_unary_op, .binary_op = ur_binary_op,
    .attr = ur_attr,         .locals_dict = (mp_obj_dict_t *)&ur_locals_dict,
};
#endif

// URDecoder implementation
static void ur_decoder_print(const mp_print_t *print, mp_obj_t self_in,
                             mp_print_kind_t kind) {
  (void)kind;
  mp_obj_ur_decoder_t *self = MP_OBJ_TO_PTR(self_in);
  float progress = ur_decoder_estimated_percent_complete(self->decoder);
  mp_printf(print, "URDecoder(state=%d, progress=%.1f%%)",
            (int)ur_decoder_get_state(self->decoder), progress * 100.0f);
}

static mp_obj_t ur_decoder_make_new(const mp_obj_type_t *type, size_t n_args,
                                    size_t n_kw, const mp_obj_t *args) {
  mp_arg_check_num(n_args, n_kw, 0, 0, false);

  // Allocate the C decoder before the wrapper so a failure doesn't leak the
  // wrapper through mp_raise_msg's long-jump.
  ur_decoder_t *decoder = ur_decoder_new();
  if (!decoder) {
    mp_raise_msg(&mp_type_MemoryError,
                 MP_ERROR_TEXT("Failed to create URDecoder"));
  }

  // with_finaliser so __del__ (ur_decoder_del) runs on GC and frees decoder.
  mp_obj_ur_decoder_t *self =
      mp_obj_malloc_with_finaliser(mp_obj_ur_decoder_t, type);
  self->decoder = decoder;

  return MP_OBJ_FROM_PTR(self);
}

static mp_obj_t ur_decoder_del(mp_obj_t self_in) {
  mp_obj_ur_decoder_t *self = MP_OBJ_TO_PTR(self_in);
  if (self->decoder) {
    ur_decoder_free(self->decoder);
    self->decoder = NULL;
  }
  return mp_const_none;
}
static MP_DEFINE_CONST_FUN_OBJ_1(ur_decoder_del_obj, ur_decoder_del);

// receive_part method — returns the decoder state (one of the module's
// DECODER_* constants) after processing, mirroring the C API. Decode
// errors are returned, not raised: junk or misread frames are expected in
// a QR scan loop. NOTE: DECODER_OK == 0 is falsy in Python — compare the
// return against the DECODER_* constants, never use it as a boolean.
static mp_obj_t ur_decoder_receive_part_py(mp_obj_t self_in,
                                           mp_obj_t part_str) {
  mp_obj_ur_decoder_t *self = MP_OBJ_TO_PTR(self_in);

  if (!self->decoder) {
    mp_raise_msg(&mp_type_RuntimeError, MP_ERROR_TEXT("URDecoder is closed"));
  }

  const char *part_cstr = mp_obj_str_get_str(part_str);
  return mp_obj_new_int(
      (mp_int_t)ur_decoder_receive_part(self->decoder, part_cstr));
}
static MP_DEFINE_CONST_FUN_OBJ_2(ur_decoder_receive_part_obj,
                                 ur_decoder_receive_part_py);

// estimated_percent_complete(weight_mixed_frames=False) method.
// weight_mixed_frames is an opt-in flag: the default (False) returns the
// original reference estimate byte-for-byte, so existing callers are
// unaffected; True selects the weighted-mixed-frames method, which gives
// partial credit for fragments still only present inside mixed/XOR'd frames.
static mp_obj_t ur_decoder_estimated_percent_complete_py(
    size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
  static const mp_arg_t allowed_args[] = {
      {MP_QSTR_weight_mixed_frames, MP_ARG_BOOL, {.u_bool = false}},
  };
  mp_arg_val_t parsed[MP_ARRAY_SIZE(allowed_args)];
  mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args,
                   MP_ARRAY_SIZE(allowed_args), allowed_args, parsed);

  mp_obj_ur_decoder_t *self = MP_OBJ_TO_PTR(pos_args[0]);
  if (!self->decoder) {
    return mp_obj_new_float(0.0f);
  }

  float pct =
      parsed[0].u_bool
          ? ur_decoder_estimated_percent_complete_weighted(self->decoder)
          : ur_decoder_estimated_percent_complete(self->decoder);
  return mp_obj_new_float(pct);
}
static MP_DEFINE_CONST_FUN_OBJ_KW(ur_decoder_estimated_percent_complete_obj, 1,
                                  ur_decoder_estimated_percent_complete_py);

// URDecoder locals dict
static const mp_rom_map_elem_t ur_decoder_locals_dict_table[] = {
    {MP_ROM_QSTR(MP_QSTR___del__), MP_ROM_PTR(&ur_decoder_del_obj)},
    {MP_ROM_QSTR(MP_QSTR_receive_part),
     MP_ROM_PTR(&ur_decoder_receive_part_obj)},
    {MP_ROM_QSTR(MP_QSTR_estimated_percent_complete),
     MP_ROM_PTR(&ur_decoder_estimated_percent_complete_obj)},
};
static MP_DEFINE_CONST_DICT(ur_decoder_locals_dict,
                            ur_decoder_locals_dict_table);

// URDecoder attributes
static void ur_decoder_attr(mp_obj_t self_in, qstr attr, mp_obj_t *dest) {
  mp_obj_ur_decoder_t *self = MP_OBJ_TO_PTR(self_in);

  if (dest[0] == MP_OBJ_NULL) {
    // Load attribute
    if (attr == MP_QSTR_result) {
      if (!self->decoder) {
        dest[0] = mp_const_none;
        return;
      }

      ur_result_t *result = ur_decoder_get_result(self->decoder);
      if (!result) {
        dest[0] = mp_const_none;
        return;
      }

      // Create UR object
      mp_obj_t type_str = mp_obj_new_str(result->type, strlen(result->type));
      mp_obj_t cbor_bytes =
          mp_obj_new_bytes(result->cbor_data, result->cbor_len);

      mp_obj_t args[2] = {type_str, cbor_bytes};
      dest[0] = ur_make_new(&mp_type_ur, 2, 0, args);
    } else if (attr == MP_QSTR_state) {
      // Closed decoder -> NULL -> DECODER_ERR_NULL_POINTER, matching the C
      // API's get_state(NULL) behavior.
      dest[0] = mp_obj_new_int((mp_int_t)ur_decoder_get_state(self->decoder));
    } else if (attr == MP_QSTR_expected_part_count) {
      if (!self->decoder) {
        dest[0] = mp_obj_new_int(0);
      } else {
        dest[0] = mp_obj_new_int(ur_decoder_expected_part_count(self->decoder));
      }
    } else if (attr == MP_QSTR_processed_parts_count) {
      if (!self->decoder) {
        dest[0] = mp_obj_new_int(0);
      } else {
        dest[0] =
            mp_obj_new_int(ur_decoder_processed_parts_count(self->decoder));
      }
    } else {
      // Method lookup from locals_dict. Use the method-load protocol
      // (dest[0]=method, dest[1]=self) instead of allocating a bound
      // method — this path is hit by the GC finaliser looking up __del__,
      // and allocating during a sweep can trigger nlr_jump_fail.
      mp_obj_dict_t *locals_dict = (mp_obj_dict_t *)&ur_decoder_locals_dict;
      mp_map_elem_t *elem = mp_map_lookup(&locals_dict->map,
                                          MP_OBJ_NEW_QSTR(attr), MP_MAP_LOOKUP);
      if (elem != NULL) {
        dest[0] = elem->value;
        dest[1] = self_in;
      }
    }
  }
}

// URDecoder type definition
#if defined(MP_DEFINE_CONST_OBJ_TYPE)
MP_DEFINE_CONST_OBJ_TYPE(mp_type_ur_decoder, MP_QSTR_URDecoder,
                         MP_TYPE_FLAG_NONE, make_new, ur_decoder_make_new,
                         print, ur_decoder_print, attr, ur_decoder_attr,
                         locals_dict, &ur_decoder_locals_dict);
#else
static const mp_obj_type_t mp_type_ur_decoder = {
    {&mp_type_type},
    .name = MP_QSTR_URDecoder,
    .print = ur_decoder_print,
    .make_new = ur_decoder_make_new,
    .attr = ur_decoder_attr,
    .locals_dict = (mp_obj_dict_t *)&ur_decoder_locals_dict,
};
#endif

// UREncoder implementation
static void ur_encoder_print(const mp_print_t *print, mp_obj_t self_in,
                             mp_print_kind_t kind) {
  (void)kind;
  mp_obj_ur_encoder_t *self = MP_OBJ_TO_PTR(self_in);
  if (self->encoder) {
    mp_printf(print, "UREncoder(seq_len=%u, complete=%s)",
              ur_encoder_seq_len(self->encoder),
              ur_encoder_is_complete(self->encoder) ? "True" : "False");
  } else {
    mp_printf(print, "UREncoder(invalid)");
  }
}

static mp_obj_t ur_encoder_make_new(const mp_obj_type_t *type, size_t n_args,
                                    size_t n_kw, const mp_obj_t *args) {
  enum {
    ARG_ur,
    ARG_max_fragment_len,
    ARG_first_seq_num,
    ARG_min_fragment_len
  };
  static const mp_arg_t allowed_args[] = {
      {MP_QSTR_ur, MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL}},
      {MP_QSTR_max_fragment_len, MP_ARG_REQUIRED | MP_ARG_INT, {.u_int = 0}},
      {MP_QSTR_first_seq_num, MP_ARG_INT, {.u_int = 0}},
      {MP_QSTR_min_fragment_len, MP_ARG_INT, {.u_int = 10}},
  };

  mp_arg_val_t parsed_args[MP_ARRAY_SIZE(allowed_args)];
  mp_arg_parse_all_kw_array(n_args, n_kw, args, MP_ARRAY_SIZE(allowed_args),
                            allowed_args, parsed_args);

  // Type-check BEFORE MP_OBJ_TO_PTR — otherwise passing a non-UR object
  // dereferences garbage as ur_t*.
  if (!mp_obj_is_type(parsed_args[ARG_ur].u_obj, &mp_type_ur)) {
    mp_raise_TypeError(MP_ERROR_TEXT("First argument must be a UR object"));
  }
  mp_obj_ur_t *ur_obj = MP_OBJ_TO_PTR(parsed_args[ARG_ur].u_obj);

  if (!ur_obj->ur) {
    mp_raise_msg(&mp_type_ValueError, MP_ERROR_TEXT("Invalid UR object"));
  }

  // Clamp fragment-length params coming from Python. 10..2048 covers any
  // real QR payload; values outside drive unbounded fountain allocations.
  mp_int_t raw_max = parsed_args[ARG_max_fragment_len].u_int;
  mp_int_t raw_min = parsed_args[ARG_min_fragment_len].u_int;
  if (raw_max < 10 || raw_max > 2048 || raw_min < 1 || raw_min > raw_max) {
    mp_raise_msg(
        &mp_type_ValueError,
        MP_ERROR_TEXT("fragment_len out of range (min 1..max, max 10..2048)"));
  }
  size_t max_fragment_len = (size_t)raw_max;
  size_t min_fragment_len = (size_t)raw_min;

  // Range-check before the cast: a negative value would silently become a
  // huge sequence number and fail later, inside next_part().
  mp_int_t raw_seq = parsed_args[ARG_first_seq_num].u_int;
  if (raw_seq < 0 || (uintmax_t)raw_seq > (uintmax_t)UINT32_MAX) {
    mp_raise_msg(&mp_type_ValueError,
                 MP_ERROR_TEXT("first_seq_num out of range (0..4294967295)"));
  }
  uint32_t first_seq_num = (uint32_t)raw_seq;

  // Allocate the C encoder before the wrapper so a failure doesn't leak the
  // wrapper through mp_raise_msg's long-jump.
  const char *ur_type_str = ur_get_type(ur_obj->ur);
  const uint8_t *cbor_data = ur_get_cbor(ur_obj->ur);
  size_t cbor_len = ur_get_cbor_len(ur_obj->ur);

  // ur_encoder_new reports validation failures and OOM identically (NULL);
  // pre-check the one reachable validation case so it raises ValueError
  // rather than a misleading MemoryError.
  if (cbor_len < min_fragment_len) {
    mp_raise_msg(&mp_type_ValueError,
                 MP_ERROR_TEXT("UR payload is shorter than min_fragment_len"));
  }

  ur_encoder_t *encoder =
      ur_encoder_new(ur_type_str, cbor_data, cbor_len, max_fragment_len,
                     first_seq_num, min_fragment_len);
  if (!encoder) {
    mp_raise_msg(&mp_type_MemoryError,
                 MP_ERROR_TEXT("Failed to create UREncoder"));
  }

  // with_finaliser so __del__ (ur_encoder_del) runs on GC.
  mp_obj_ur_encoder_t *self =
      mp_obj_malloc_with_finaliser(mp_obj_ur_encoder_t, type);
  self->encoder = encoder;
  self->fountain_encoder_cached = MP_OBJ_NULL;

  return MP_OBJ_FROM_PTR(self);
}

static mp_obj_t ur_encoder_del(mp_obj_t self_in) {
  mp_obj_ur_encoder_t *self = MP_OBJ_TO_PTR(self_in);
  if (self->encoder) {
    ur_encoder_free(self->encoder);
    self->encoder = NULL;
  }
  return mp_const_none;
}
static MP_DEFINE_CONST_FUN_OBJ_1(ur_encoder_del_obj, ur_encoder_del);

// next_part method
static mp_obj_t ur_encoder_next_part_py(mp_obj_t self_in) {
  mp_obj_ur_encoder_t *self = MP_OBJ_TO_PTR(self_in);

  if (!self->encoder) {
    mp_raise_msg(&mp_type_RuntimeError, MP_ERROR_TEXT("UREncoder is closed"));
  }

  char *ur_part = NULL;
  bool result = ur_encoder_next_part(self->encoder, &ur_part);

  if (!result) {
    if (ur_part) {
      free(ur_part);
    }
    mp_raise_msg(&mp_type_RuntimeError,
                 MP_ERROR_TEXT("Failed to generate next part"));
  }

  if (!ur_part) {
    mp_raise_msg(&mp_type_RuntimeError, MP_ERROR_TEXT("Generated NULL part"));
  }

  // Copy the string into MicroPython's memory space
  size_t len = strlen(ur_part);
  mp_obj_t part_str =
      mp_obj_new_str_copy(&mp_type_str, (const byte *)ur_part, len);

  // Free the C-allocated string
  free(ur_part);

  return part_str;
}
static MP_DEFINE_CONST_FUN_OBJ_1(ur_encoder_next_part_obj,
                                 ur_encoder_next_part_py);

// is_complete method
static mp_obj_t ur_encoder_is_complete_py(mp_obj_t self_in) {
  mp_obj_ur_encoder_t *self = MP_OBJ_TO_PTR(self_in);
  if (!self->encoder) {
    return mp_const_false;
  }
  return mp_obj_new_bool(ur_encoder_is_complete(self->encoder));
}
static MP_DEFINE_CONST_FUN_OBJ_1(ur_encoder_is_complete_obj,
                                 ur_encoder_is_complete_py);

// is_single_part method
static mp_obj_t ur_encoder_is_single_part_py(mp_obj_t self_in) {
  mp_obj_ur_encoder_t *self = MP_OBJ_TO_PTR(self_in);
  if (!self->encoder) {
    return mp_const_false;
  }
  return mp_obj_new_bool(ur_encoder_is_single_part(self->encoder));
}
static MP_DEFINE_CONST_FUN_OBJ_1(ur_encoder_is_single_part_obj,
                                 ur_encoder_is_single_part_py);

// UREncoder locals dict
static const mp_rom_map_elem_t ur_encoder_locals_dict_table[] = {
    {MP_ROM_QSTR(MP_QSTR___del__), MP_ROM_PTR(&ur_encoder_del_obj)},
    {MP_ROM_QSTR(MP_QSTR_next_part), MP_ROM_PTR(&ur_encoder_next_part_obj)},
    {MP_ROM_QSTR(MP_QSTR_is_complete), MP_ROM_PTR(&ur_encoder_is_complete_obj)},
    {MP_ROM_QSTR(MP_QSTR_is_single_part),
     MP_ROM_PTR(&ur_encoder_is_single_part_obj)},
};
static MP_DEFINE_CONST_DICT(ur_encoder_locals_dict,
                            ur_encoder_locals_dict_table);

// FountainEncoder wrapper type for accessing seq_len(). Holds a strong
// reference to the parent UREncoder Python object so GC cannot finalise
// the parent (and free ->encoder) while this wrapper is still reachable.
// The encoder pointer is always re-read from parent->encoder at call time
// so that an explicit parent.__del__() cleanly turns all wrapper reads
// into no-ops instead of dangling dereferences.
typedef struct {
  mp_obj_base_t base;
  mp_obj_t parent; // UREncoder Python object; MP_OBJ_NULL if detached
} mp_obj_fountain_encoder_wrapper_t;

// Reach through the parent back-ref to the live ur_encoder_t, or NULL if
// the parent was explicitly closed (ur_encoder_del set parent->encoder to
// NULL) or never attached.
static ur_encoder_t *
fountain_encoder_wrapper_encoder(mp_obj_fountain_encoder_wrapper_t *self) {
  if (self->parent == MP_OBJ_NULL)
    return NULL;
  mp_obj_ur_encoder_t *parent = MP_OBJ_TO_PTR(self->parent);
  return parent->encoder;
}

static void fountain_encoder_wrapper_print(const mp_print_t *print,
                                           mp_obj_t self_in,
                                           mp_print_kind_t kind) {
  (void)kind;
  mp_obj_fountain_encoder_wrapper_t *self = MP_OBJ_TO_PTR(self_in);
  ur_encoder_t *enc = fountain_encoder_wrapper_encoder(self);
  if (enc && enc->fountain_encoder) {
    mp_printf(print, "FountainEncoder(seq_len=%u)", ur_encoder_seq_len(enc));
  } else {
    mp_printf(print, "FountainEncoder(invalid)");
  }
}

static mp_obj_t fountain_encoder_seq_len_py(mp_obj_t self_in) {
  mp_obj_fountain_encoder_wrapper_t *self = MP_OBJ_TO_PTR(self_in);
  ur_encoder_t *enc = fountain_encoder_wrapper_encoder(self);
  if (!enc || !enc->fountain_encoder) {
    return mp_obj_new_int(0);
  }
  return mp_obj_new_int(ur_encoder_seq_len(enc));
}
static MP_DEFINE_CONST_FUN_OBJ_1(fountain_encoder_seq_len_obj,
                                 fountain_encoder_seq_len_py);

static const mp_rom_map_elem_t fountain_encoder_wrapper_locals_dict_table[] = {
    {MP_ROM_QSTR(MP_QSTR_seq_len), MP_ROM_PTR(&fountain_encoder_seq_len_obj)},
};
static MP_DEFINE_CONST_DICT(fountain_encoder_wrapper_locals_dict,
                            fountain_encoder_wrapper_locals_dict_table);

#if defined(MP_DEFINE_CONST_OBJ_TYPE)
MP_DEFINE_CONST_OBJ_TYPE(mp_type_fountain_encoder_wrapper,
                         MP_QSTR_FountainEncoder, MP_TYPE_FLAG_NONE, print,
                         fountain_encoder_wrapper_print, locals_dict,
                         &fountain_encoder_wrapper_locals_dict);
#else
static const mp_obj_type_t mp_type_fountain_encoder_wrapper = {
    {&mp_type_type},
    .name = MP_QSTR_FountainEncoder,
    .print = fountain_encoder_wrapper_print,
    .locals_dict = (mp_obj_dict_t *)&fountain_encoder_wrapper_locals_dict,
};
#endif

// UREncoder attributes
static void ur_encoder_attr(mp_obj_t self_in, qstr attr, mp_obj_t *dest) {
  mp_obj_ur_encoder_t *self = MP_OBJ_TO_PTR(self_in);

  if (dest[0] == MP_OBJ_NULL) {
    // Load attribute
    if (attr == MP_QSTR_fountain_encoder) {
      // Return cached fountain encoder wrapper to prevent memory leaks
      if (!self->encoder || !self->encoder->fountain_encoder) {
        dest[0] = mp_const_none;
        return;
      }

      // If not cached yet, create and cache the wrapper. The wrapper keeps
      // a strong ref to self so GC can't free self->encoder out from under it,
      // and reads encoder through self->parent->encoder each call so explicit
      // __del__ on the parent neuters the wrapper instead of dangling.
      if (self->fountain_encoder_cached == MP_OBJ_NULL) {
        mp_obj_fountain_encoder_wrapper_t *fe_wrapper =
            m_new_obj(mp_obj_fountain_encoder_wrapper_t);
        fe_wrapper->base.type = &mp_type_fountain_encoder_wrapper;
        fe_wrapper->parent = self_in;
        self->fountain_encoder_cached = MP_OBJ_FROM_PTR(fe_wrapper);
      }

      dest[0] = self->fountain_encoder_cached;
    } else {
      // Method lookup from locals_dict. Use the method-load protocol
      // (dest[0]=method, dest[1]=self) instead of allocating a bound
      // method — this path is hit by the GC finaliser looking up __del__,
      // and allocating during a sweep can trigger nlr_jump_fail.
      mp_obj_dict_t *locals_dict = (mp_obj_dict_t *)&ur_encoder_locals_dict;
      mp_map_elem_t *elem = mp_map_lookup(&locals_dict->map,
                                          MP_OBJ_NEW_QSTR(attr), MP_MAP_LOOKUP);
      if (elem != NULL) {
        dest[0] = elem->value;
        dest[1] = self_in;
      }
    }
  }
}

// UREncoder type definition
#if defined(MP_DEFINE_CONST_OBJ_TYPE)
MP_DEFINE_CONST_OBJ_TYPE(mp_type_ur_encoder, MP_QSTR_UREncoder,
                         MP_TYPE_FLAG_NONE, make_new, ur_encoder_make_new,
                         print, ur_encoder_print, attr, ur_encoder_attr,
                         locals_dict, &ur_encoder_locals_dict);
#else
static const mp_obj_type_t mp_type_ur_encoder = {
    {&mp_type_type},
    .name = MP_QSTR_UREncoder,
    .print = ur_encoder_print,
    .make_new = ur_encoder_make_new,
    .attr = ur_encoder_attr,
    .locals_dict = (mp_obj_dict_t *)&ur_encoder_locals_dict,
};
#endif

// ============================================================================
// Types Module (for URTypes functionality)
// ============================================================================

// bytes_from_cbor(cbor_data) - module function
static mp_obj_t bytes_from_cbor_py(mp_obj_t cbor_data_in) {
  mp_buffer_info_t bufinfo;
  mp_get_buffer_raise(cbor_data_in, &bufinfo, MP_BUFFER_READ);

  // Decode CBOR to Bytes
  bytes_data_t *bytes =
      bytes_from_cbor((const uint8_t *)bufinfo.buf, bufinfo.len);
  if (!bytes) {
    mp_raise_msg(&mp_type_ValueError,
                 MP_ERROR_TEXT("Failed to decode Bytes from CBOR"));
  }

  // Get raw bytes data
  size_t len;
  const uint8_t *data = bytes_get_data(bytes, &len);

  // Create Python bytes object
  mp_obj_t result = mp_obj_new_bytes(data, len);

  // Cleanup
  bytes_free(bytes);

  return result;
}
static MP_DEFINE_CONST_FUN_OBJ_1(bytes_from_cbor_obj, bytes_from_cbor_py);

// bytes_to_cbor(bytes_data) - module function
static mp_obj_t bytes_to_cbor_py(mp_obj_t bytes_data_in) {
  mp_buffer_info_t bufinfo;
  mp_get_buffer_raise(bytes_data_in, &bufinfo, MP_BUFFER_READ);

  // Create Bytes from raw bytes
  bytes_data_t *bytes = bytes_new((const uint8_t *)bufinfo.buf, bufinfo.len);
  if (!bytes) {
    mp_raise_msg(&mp_type_MemoryError, MP_ERROR_TEXT("Failed to create Bytes"));
  }

  // Encode to CBOR
  size_t cbor_len;
  uint8_t *cbor_data = bytes_to_cbor(bytes, &cbor_len);
  if (!cbor_data) {
    bytes_free(bytes);
    mp_raise_msg(&mp_type_RuntimeError,
                 MP_ERROR_TEXT("Failed to encode Bytes to CBOR"));
  }

  // Create Python bytes object
  mp_obj_t result = mp_obj_new_bytes(cbor_data, cbor_len);

  // Cleanup
  free(cbor_data);
  bytes_free(bytes);

  return result;
}
static MP_DEFINE_CONST_FUN_OBJ_1(bytes_to_cbor_obj, bytes_to_cbor_py);

// ============================================================================
// PSBT Functions
// ============================================================================

// psbt_from_cbor(cbor_data) - module function
static mp_obj_t psbt_from_cbor_py(mp_obj_t cbor_data_in) {
  mp_buffer_info_t bufinfo;
  mp_get_buffer_raise(cbor_data_in, &bufinfo, MP_BUFFER_READ);

  // Decode CBOR to PSBT
  psbt_data_t *psbt = psbt_from_cbor((const uint8_t *)bufinfo.buf, bufinfo.len);
  if (!psbt) {
    mp_raise_msg(&mp_type_ValueError,
                 MP_ERROR_TEXT("Failed to decode PSBT from CBOR"));
  }

  // Get raw PSBT data
  size_t len;
  const uint8_t *data = psbt_get_data(psbt, &len);

  // Create Python bytes object
  mp_obj_t result = mp_obj_new_bytes(data, len);

  // Cleanup
  psbt_free(psbt);

  return result;
}
static MP_DEFINE_CONST_FUN_OBJ_1(psbt_from_cbor_obj, psbt_from_cbor_py);

// psbt_to_cbor(psbt_data) - module function
static mp_obj_t psbt_to_cbor_py(mp_obj_t psbt_data_in) {
  mp_buffer_info_t bufinfo;
  mp_get_buffer_raise(psbt_data_in, &bufinfo, MP_BUFFER_READ);

  // Create PSBT from raw bytes
  psbt_data_t *psbt = psbt_new((const uint8_t *)bufinfo.buf, bufinfo.len);
  if (!psbt) {
    mp_raise_msg(&mp_type_MemoryError, MP_ERROR_TEXT("Failed to create PSBT"));
  }

  // Encode to CBOR
  size_t cbor_len;
  uint8_t *cbor_data = psbt_to_cbor(psbt, &cbor_len);
  if (!cbor_data) {
    psbt_free(psbt);
    mp_raise_msg(&mp_type_RuntimeError,
                 MP_ERROR_TEXT("Failed to encode PSBT to CBOR"));
  }

  // Create Python bytes object
  mp_obj_t result = mp_obj_new_bytes(cbor_data, cbor_len);

  // Cleanup
  free(cbor_data);
  psbt_free(psbt);

  return result;
}
static MP_DEFINE_CONST_FUN_OBJ_1(psbt_to_cbor_obj, psbt_to_cbor_py);

// ============================================================================
// BIP39 Functions
// ============================================================================

// BIP39.words_from_cbor(cbor_data) - static function
static mp_obj_t bip39_words_from_cbor_py(mp_obj_t cbor_data_in) {
  mp_buffer_info_t bufinfo;
  mp_get_buffer_raise(cbor_data_in, &bufinfo, MP_BUFFER_READ);

  // Decode CBOR to BIP39
  bip39_data_t *bip39 =
      bip39_from_cbor((const uint8_t *)bufinfo.buf, bufinfo.len);
  if (!bip39) {
    mp_raise_msg(&mp_type_ValueError,
                 MP_ERROR_TEXT("Failed to decode BIP39 from CBOR"));
  }

  // Get words
  size_t word_count;
  char **words = bip39_get_words(bip39, &word_count);

  // Create Python list
  mp_obj_t list = mp_obj_new_list(0, NULL);
  for (size_t i = 0; i < word_count; i++) {
    mp_obj_list_append(list, mp_obj_new_str(words[i], strlen(words[i])));
  }

  // Cleanup
  bip39_free(bip39);

  return list;
}
static MP_DEFINE_CONST_FUN_OBJ_1(bip39_words_from_cbor_obj,
                                 bip39_words_from_cbor_py);

// ============================================================================
// Output Descriptor Functions
// ============================================================================

// output_from_cbor(cbor_data) - module function
static mp_obj_t output_from_cbor_py(mp_obj_t cbor_data_in) {
  mp_buffer_info_t bufinfo;
  mp_get_buffer_raise(cbor_data_in, &bufinfo, MP_BUFFER_READ);

  // Decode CBOR to Output
  output_data_t *output =
      output_from_cbor((const uint8_t *)bufinfo.buf, bufinfo.len);
  if (!output) {
    mp_raise_msg(&mp_type_ValueError,
                 MP_ERROR_TEXT("Failed to decode Output from CBOR"));
  }

  // Generate descriptor string with checksum
  char *descriptor = output_descriptor(output, true);
  if (!descriptor) {
    output_free(output);
    mp_raise_msg(&mp_type_RuntimeError,
                 MP_ERROR_TEXT("Failed to generate output descriptor"));
  }

  // Create Python string from descriptor
  mp_obj_t result = mp_obj_new_str(descriptor, strlen(descriptor));

  // Cleanup
  free(descriptor);
  output_free(output);

  return result;
}
static MP_DEFINE_CONST_FUN_OBJ_1(output_from_cbor_obj, output_from_cbor_py);

// output_from_cbor_account(cbor_data) - module function
static mp_obj_t output_from_cbor_account_py(mp_obj_t cbor_data_in) {
  mp_buffer_info_t bufinfo;
  mp_get_buffer_raise(cbor_data_in, &bufinfo, MP_BUFFER_READ);

  // Extract first output descriptor from Account CBOR
  char *descriptor = output_descriptor_from_cbor_account(
      (const uint8_t *)bufinfo.buf, bufinfo.len);
  if (!descriptor) {
    mp_raise_msg(
        &mp_type_ValueError,
        MP_ERROR_TEXT("Failed to extract output descriptor from Account CBOR"));
  }

  // Create Python string from descriptor
  mp_obj_t result = mp_obj_new_str(descriptor, strlen(descriptor));

  // Cleanup
  free(descriptor);

  return result;
}
static MP_DEFINE_CONST_FUN_OBJ_1(output_from_cbor_account_obj,
                                 output_from_cbor_account_py);

// ============================================================================
// Type String Constants (for UR type names with hyphens)
// ============================================================================

// Static string constants for UR type names (with hyphens)
static const mp_obj_str_t crypto_psbt_type_str = {
    {&mp_type_str}, 0, 11, (const byte *)"crypto-psbt"};
static const mp_obj_str_t crypto_bip39_type_str = {
    {&mp_type_str}, 0, 12, (const byte *)"crypto-bip39"};
static const mp_obj_str_t crypto_output_type_str = {
    {&mp_type_str}, 0, 13, (const byte *)"crypto-output"};
static const mp_obj_str_t crypto_account_type_str = {
    {&mp_type_str}, 0, 14, (const byte *)"crypto-account"};

// Types namespace globals
static const mp_rom_map_elem_t types_globals_table[] = {
    {MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_Types)},
    // Functions
    {MP_ROM_QSTR(MP_QSTR_bytes_from_cbor), MP_ROM_PTR(&bytes_from_cbor_obj)},
    {MP_ROM_QSTR(MP_QSTR_bytes_to_cbor), MP_ROM_PTR(&bytes_to_cbor_obj)},
    {MP_ROM_QSTR(MP_QSTR_psbt_from_cbor), MP_ROM_PTR(&psbt_from_cbor_obj)},
    {MP_ROM_QSTR(MP_QSTR_psbt_to_cbor), MP_ROM_PTR(&psbt_to_cbor_obj)},
    {MP_ROM_QSTR(MP_QSTR_bip39_words_from_cbor),
     MP_ROM_PTR(&bip39_words_from_cbor_obj)},
    {MP_ROM_QSTR(MP_QSTR_output_from_cbor), MP_ROM_PTR(&output_from_cbor_obj)},
    {MP_ROM_QSTR(MP_QSTR_output_from_cbor_account),
     MP_ROM_PTR(&output_from_cbor_account_obj)},
    // Tag constants (integers)
    {MP_ROM_QSTR(MP_QSTR_CRYPTO_PSBT_TAG), MP_ROM_INT(CRYPTO_PSBT_TAG)},
    {MP_ROM_QSTR(MP_QSTR_CRYPTO_BIP39_TAG), MP_ROM_INT(CRYPTO_BIP39_TAG)},
    {MP_ROM_QSTR(MP_QSTR_CRYPTO_ACCOUNT_TAG), MP_ROM_INT(CRYPTO_ACCOUNT_TAG)},
    {MP_ROM_QSTR(MP_QSTR_CRYPTO_OUTPUT_TAG), MP_ROM_INT(CRYPTO_OUTPUT_TAG)},
    // Type name constants (strings with hyphens for UR type field)
    {MP_ROM_QSTR(MP_QSTR_CRYPTO_PSBT_TYPE), MP_ROM_PTR(&crypto_psbt_type_str)},
    {MP_ROM_QSTR(MP_QSTR_CRYPTO_BIP39_TYPE),
     MP_ROM_PTR(&crypto_bip39_type_str)},
    {MP_ROM_QSTR(MP_QSTR_CRYPTO_OUTPUT_TYPE),
     MP_ROM_PTR(&crypto_output_type_str)},
    {MP_ROM_QSTR(MP_QSTR_CRYPTO_ACCOUNT_TYPE),
     MP_ROM_PTR(&crypto_account_type_str)},
};
static MP_DEFINE_CONST_DICT(types_globals, types_globals_table);

static const mp_obj_module_t types_module = {
    .base = {&mp_type_module},
    .globals = (mp_obj_dict_t *)&types_globals,
};

// ============================================================================
// Main uUR Module
// ============================================================================

// Module globals table
static const mp_rom_map_elem_t bc_ur_globals_table[] = {
    {MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_bc_ur)},
    {MP_ROM_QSTR(MP_QSTR_URDecoder), MP_ROM_PTR(&mp_type_ur_decoder)},
    {MP_ROM_QSTR(MP_QSTR_UREncoder), MP_ROM_PTR(&mp_type_ur_encoder)},
    {MP_ROM_QSTR(MP_QSTR_UR), MP_ROM_PTR(&mp_type_ur)},
    {MP_ROM_QSTR(MP_QSTR_Types), MP_ROM_PTR(&types_module)},
    // Decoder state constants (mirror ur_decoder_state_t). Compare
    // URDecoder.receive_part() / URDecoder.state against these; never use
    // the value as a boolean — DECODER_OK is 0 and therefore falsy.
    {MP_ROM_QSTR(MP_QSTR_DECODER_OK), MP_ROM_INT(UR_DECODER_OK)},
    {MP_ROM_QSTR(MP_QSTR_DECODER_PROCESSING),
     MP_ROM_INT(UR_DECODER_PROCESSING)},
    {MP_ROM_QSTR(MP_QSTR_DECODER_NO_RESULT), MP_ROM_INT(UR_DECODER_NO_RESULT)},
    {MP_ROM_QSTR(MP_QSTR_DECODER_ERR_INVALID_SCHEME),
     MP_ROM_INT(UR_DECODER_ERROR_INVALID_SCHEME)},
    {MP_ROM_QSTR(MP_QSTR_DECODER_ERR_INVALID_TYPE),
     MP_ROM_INT(UR_DECODER_ERROR_INVALID_TYPE)},
    {MP_ROM_QSTR(MP_QSTR_DECODER_ERR_INVALID_PATH_LENGTH),
     MP_ROM_INT(UR_DECODER_ERROR_INVALID_PATH_LENGTH)},
    {MP_ROM_QSTR(MP_QSTR_DECODER_ERR_INVALID_SEQUENCE_COMPONENT),
     MP_ROM_INT(UR_DECODER_ERROR_INVALID_SEQUENCE_COMPONENT)},
    {MP_ROM_QSTR(MP_QSTR_DECODER_ERR_INVALID_FRAGMENT),
     MP_ROM_INT(UR_DECODER_ERROR_INVALID_FRAGMENT)},
    {MP_ROM_QSTR(MP_QSTR_DECODER_ERR_INVALID_PART),
     MP_ROM_INT(UR_DECODER_ERROR_INVALID_PART)},
    {MP_ROM_QSTR(MP_QSTR_DECODER_ERR_INVALID_CHECKSUM),
     MP_ROM_INT(UR_DECODER_ERROR_INVALID_CHECKSUM)},
    {MP_ROM_QSTR(MP_QSTR_DECODER_ERR_MEMORY),
     MP_ROM_INT(UR_DECODER_ERROR_MEMORY)},
    {MP_ROM_QSTR(MP_QSTR_DECODER_ERR_NULL_POINTER),
     MP_ROM_INT(UR_DECODER_ERROR_NULL_POINTER)},
};
static MP_DEFINE_CONST_DICT(bc_ur_globals, bc_ur_globals_table);

// Module definition
const mp_obj_module_t bc_ur_module = {
    .base = {&mp_type_module},
    .globals = (mp_obj_dict_t *)&bc_ur_globals,
};

// MP_REGISTER_MODULE lost its third (enable-flag) argument in v1.19 — one
// release BEFORE the v1.20 type-slots refactor — so it needs its own version
// probe: gating on MP_DEFINE_CONST_OBJ_TYPE would feed v1.19.x the 3-arg
// legacy form and fail to compile. MICROPY_VERSION is
// (major << 16 | minor << 8 | micro); on builds too old to define it, the
// expression evaluates to 0 and correctly selects the legacy 3-arg form.
//
// The modern branch registers through the UR_REGISTER_MODULE alias, not the
// macro's own name: the legacy MaixPy (K210) build generates
// genhdr/moduledefs.h by regex-scanning the RAW source for the macro name,
// ignoring preprocessor conditionals, and with two visible registrations the
// scan mangles the generated header ("#else after #else"). The alias keeps
// the modern line invisible to that scanner; modern builds collect
// registrations from PREPROCESSED source, where the alias has already
// expanded to the real macro.
#if MICROPY_VERSION >= ((1 << 16) | (19 << 8)) // >= v1.19
#define UR_REGISTER_MODULE MP_REGISTER_MODULE
UR_REGISTER_MODULE(MP_QSTR_uUR, bc_ur_module);
#else
MP_REGISTER_MODULE(MP_QSTR_uUR, bc_ur_module, MODULE_BC_UR_ENABLED);
#endif