RFC: C/C++ FFI from stratum crates

[plebhash]

there's an adopter (with around 5 to 10% of network hashrate) expressing interest in FFI for C++ integration

this discussion aims to discuss technical approaches, tradeoffs, align expectations and settle on a plan for next steps

[plebhash]

TLDR

TLDR of everything on this discussion is that we have 3 potential paths forward:

1.a. Raw FFIs from stratum repo crates (WITH lifetime cleanup)
1.b. Raw FFIs from stratum repo crates (WITHOUT lifetime cleanup)
2. UniFFI while relying on a third party project for C++ compatibility

assuming either approach becomes TOP-priority on SRI roadmap for the short term, IMO realistic timelines are:
1.a. ~2 months
1.b. ~1 month (or less?)
2. ~2 weeks

note: there's a dedicated section for the UniFFI approach (and its compromises) below in this discussion

[plebhash]

note: one (e.g.: @pavlenex or @Fi3 ) might point out sv2_ffi crate as a 4th path

this crate has not been actively maintained in a really long time, and was deprecated on release v0.1.5 of stratum repo

so not only it is VERY out-of-date with the current state of stratum crates, it also has scope issues in terms of:

• lacking API coverage
• exposing unnecessary APIs (e.g.: binary_sv2)

while we could take some loose inspiration from it for the Raw FFI approaches listed above, I don't think it makes sense to think/plan things in terms of "refactoring" this crate or bringing it back to life

[plebhash]

API boundaries

Both Raw FFI and UniFFI approaches should have clear and concise API boundaries. That means we should not expose every single crate from stratum repository.

IMHO we should resist the urge of trying to expose every "elegant" Rust construct that exists on the SRI stack. Our mission here is to enable straightforward implementations in C/C++, not force implementers into overengineered paths just for the sake of it.

In fact, this conservative FFI philosophy is already somewhat established on sv2-uniffi (although currently limited to Python bindings only, for reasons explained below).

---

What FFI API boundaries SHOULD cover:

• Owned objects for subprotocol messages:
  • common_messages_sv2
  • mining_sv2
  • job_declaration_sv2
  • template_distribution_sv2
• Transport primitives (from codec_sv2):
  • noise handshake/session state
  • encoder
  • decoder
• Reusable channel state machines (from channels_sv2):
  • standard/extended/group channels
  • share validation
  • unique extranonce_prefix generation
  • etc

---

What FFI API boundaries SHOULD NOT cover:

• Internal SRI "plumbing" crates:

  • binary_sv2

  • buffer_sv2

  • framing_sv2

  • handlers_sv2

• Raw Rust-specific types:
  • borrowed 'decoder messages
  • binary_sv2 specific types (Str0255, B032, U256, etc)
  • generic job store
  • trait-based handlers
  • async traits
  • buffer pools
  • etc
• App-layer concerns from stratum-apps crate:
  • networking runtime
  • config loading
  • monitoring
  • tracing setup
  • etc

These things should be either constrained into Rust-land (when absolutely necessary for building the FFI), or simply not included at all.

[plebhash]

maybe @GitGab19 or @Shourya742 might ask:

why not include handler traits from handlers_sv2?

I'd say this is a gray area and I'm not hardly opinionated about it

but I can list a few reasons why I think that would be a bad idea:

• those traits are tightly coupled with types from framing_sv2, so we'd be forced to also provide abstractions for those (which otherwise would only exist internally in Rust-land, keeping things simple and straightforward on the C/C++ side)
• there's no straightforward way to expose Rust traits via Raw FFI (emphasis on straightforward, I'm sure one can come up with crazy gymnastics but that's besides my point)
• while it is possible to map Rust traits into UniFFI interfaces, it's not straightforward to map them into different language constructs

ultimately, those traits are only thin guardrails that "nudge" implementers towards an architecture that separates concerns with regards to subprotocol message types.

so I don't really see the value in doing hardcore engineering gymnastics to bypass the challenges listed above

[GitGab19]

I agree on not including handlers_sv2, green light on my end about this.

[plebhash]

lifetime cleanup as a pre-requisite for Raw FFI

crates on stratum repo have technical debt around lifetime leakage.

@Shourya742 has done some extensive analysis on how the current buffer_sv2 + binary_sv2 impose lifetime limitations on the Rust APIs #2040

The next step is the lifetime cleanup described on this hackmd doc. So far we haven't decided when this cleanup will happen.

This lifetime cleanup matters for the Raw FFI approach because the C/C++ bindings needs owned, stable, language-neutral types.

---

We could theoretically write the Raw FFI code while trying to work around those limitations on the Rust side of the bindings.

More specifically, we could build a large adapter layer around borrowed Sv2 messages, into_static() conversions, and Rust-specific buffer semantics (only to throw much of it away after the lifetime cleanup).

---

So if we go in the Raw FFI direction, we should consider lifetime cleanup as a potential pre-requisite.

[plebhash]

Raw FFI as a standalone repo?

if we go with the Raw FFI approach, we could consider having a standalone repository, just like we have github.com/stratum-mining/sv2-uniffi

that would help separate concerns and keep a clear versioning/release schedule (downstream to stratum versioning/release schedule)

a few candidates that come to mind:

• github.com/stratum-mining/sv2-ffi: same naming pattern as sv2-uniffi
• github.com/stratum-mining/stratum-core-ffi: since this would be pretty much stratum-core but FFI
• github.com/stratum-mining/stratum-ffi: idk just another option that comes to mind

---

alternatively, it could live as a new stratum-core-ffi crate/directory on the stratum repo/workspace

the benefit of that would be that every stratum repo release cycle would force us to keep FFIs up-to-date

[plebhash]

uniffi-bindgen-cpp shortcut?

after reading everything above, someone (e.g.: @pavlenex) might say:

wait, but we already have sv2-uniffi?

why do all this work (e.g. lifetime cleanup, or writing Raw FFIs from scratch)?

unfortunately, C++ is not an officially supported language on UniFFI:

Supported languages

UniFFI comes with full support for Kotlin, Swift and Python; unless specified otherwise, you can expect all features in this manual will work for these languages.

we could theoretically bypass all the work above by leveraging github.com/NordSecurity/uniffi-bindgen-cpp and unblocking this adopter on the short term

however UniFFI mentions some trade-offs for third party projects:

There are also many 3rd party bindings - please see our README for references. These languages may require older versions of UniFFI and may have partial or non-existant support for some features; see the documentation for those bindings for details.

moreover, if for some reason @NordSecurity abandons the project, then SRI (and this specific Sv2 adopter) would be on our own to maintain it

[GitGab19]

Well, if that's the case, I would proceed with this option, hoping that everything we need is covered by their generator.

A comment about this:

moreover, if for some reason @NordSecurity abandons the project, then SRI (and this specific Sv2 adopter) would be on our own to maintain it

I'm not a bindings expert at all, but I guess that we're not gonna drastically change the crates we need to map in the future, so as long as we'll be able to create the c++ bindings now, they should work "forever" in the future?

[plebhash]

if we keep everything "frozen" in terms of which versions of uniffi and uniffi-bindgen-cpp are used on sv2-uniffi, then yes we're good "forever"

assuming uniffi-bindgen-cpp is abandoned, if we decide to update the version of uniffi that is used for sv2-uniffi, it would probably break compatibility with uniffi-bindgen-cpp

[GitGab19]

I see, thanks for detailing this.

According to their README their latest version is compatible with v0.29.4 of uniffi-rs.

[GitGab19]

And our current sv2-uniffi uses v0.29.3.

[plebhash]

And our current sv2-uniffi uses v0.29.3.

yeah yesterday I was making an analysis of what will need to be adapted on sv2-uniffi before we can plug in uniffi-bindgen-cpp

uniffi version is one of them, but not the only one

we will also need some minor adaptations on the rust source code... they're relatively small (almost cosmetic), but will probably result in a big diff

I'll write an issue after we get stratum-mining/sv2-uniffi#1 out of the way