Exposing Rust-only RGB PSBT primitives through UniFFI

[Arshia-r-m]

Hi

We are considering exposing a small safe wrapper around the current Rust-only RGB PSBT primitives through UniFFI, using only binding-friendly types: PSBT strings, asset ID strings, simple DTOs, and consignment file paths.

The wrapper would avoid exposing raw internals like Fascia, RgbTransfer, BuilderSeal, raw color_psbt, or raw consume_fascia.

We’d appreciate your feedback on the system design:

1. Should these primitives be exposed through UniFFI at all, or kept Rust-only?
2. Is a higher-level safe wrapper the right approach, instead of exposing raw RGB types?
3. Should consignments remain file-path based at the binding boundary?
4. Should static blinding be required explicitly in the binding API?
5. What invariants should the binding layer validate before calling the Rust primitives?
6. Is there a better API shape you would recommend for non-Rust consumers?

The final goal for this is to have an onchain rgb swap with PSBT approach, looking forward to your response.

[zoedberg]

Hi, thanks for the proposal.

In general, I agree with the direction of exposing this only through a higher-level safe API, not by binding the low-level RGB/PSBT internals directly.

rgb-lib tries to keep all API logic in Rust, while the bindings just forward API calls to the Rust code. This is the reason rgb-lib APIs never use complex input or output parameters. So I would first add the required APIs for the on-chain swap in the Rust code and then expose them through the bindings.

1. I would first focus on the Rust API design for the swap flow, and only then decide whether anything extra needs to be exposed through the bindings
2. I would avoid exposing raw RGB/PSBT internals directly. Many of those types contain Rust-specific or library-specific structures, such as confined collection types from the amplify crate, so exposing them through UniFFI would require converting them into simpler DTOs. Rather than designing DTOs that mirror low-level internals, I think it is better to design a higher-level API around the actual swap flow
3. Yes, keeping consignments file-path based would definitely be the best approach. Passing large binary consignments through FFI is more error-prone and less portable. In an RGB-for-RGB swap, the 2 counterparties will likely need to exchange 2 consignments, one for each asset being swapped. I think the proxy server could be used for that exchange, so I'd like to better understand why consignment files would be needed at the API boundary
4. Static blinding is needed when determinism is required. For this swap flow I think the 2 parties will still need to interact, so I don't think static blinding is necessarily required. But if you think it is needed for the flow you have in mind, let's discuss the details
5. If possible the bindings should only forward the API call to rgb-lib. Validation and invariants should live in the Rust API implementation, not be duplicated in each binding layer
6. I would suggest a small swap-oriented API rather than exposing generic primitives. If you already designed the flow you need, please share some more details and I can help define the API design in more detail

[Arshia-r-m]

Hi, thanks for detailed response

We added a small swap-oriented module in rgb-lib (src/wallet/onchain_swap.rs) that exposes a four-message flow between maker and taker. All logic lives in Rust; the UniFFI layer only forwards calls.

The messages are plain DTOs (PSBT strings, asset-ID strings, script-pubkey hex, blinding u64, file paths):

1. create_swap_offer(maker_gives, maker_receives, fee, expiration, proxy_url) -> OnchainSwapOffer — maker generates a receive destination (BTC address or RGB script + blinding) and a swap ID.
2. accept_swap_offer(offer) -> OnchainSwapRequest — taker selects their inputs, generates their receive destination, returns the request.
3. accept_swap_request(request) -> OnchainSwapProposal — maker builds the coordinated PSBT, colors their RGB leg with color_psbt_and_consume, signs their inputs, attaches their consignment paths (optionally posted to the proxy).
4. complete_swap_proposal(proposal) -> OnchainSwapCompletion — taker validates the PSBT structure against an independently rebuilt expected PSBT (inputs, outputs, OP_RETURN host), colors their RGB leg, signs, finalizes.

Plus accept_swap_transfers(completion, role) for the receiving side to validate consignments (proxy endpoint when available, local file path fallback).

This works end-to-end for RGB↔BTC in both directions, but the RGB->RGB, there are some problems.

For an RGB↔RGB swap we need to color the same PSBT twice — once on the maker side for maker_gives, once on the taker side for maker_receives — committing both transitions to a single MPC root on the shared OP_RETURN. With the current API the maker's first color_psbt already finalizes the commitment, so the taker's subsequent coloring conflicts with the sealed PSBT.

Proposed solution
We'd like to split the coloring primitive into a two-phase API in rust_only.rs, roughly:

• color_psbt_stage(psbt, coloring_info) -> Fascia — appends the caller's transition(s) to the PSBT via push_rgb_transition / set_rgb_contract_consumer and returns the partial fascia, but does not call set_as_unmodifiable or rgb_commit. Idempotent w.r.t. previously staged contracts.
• color_psbt_finalize(psbt, static_blinding) -> Vec — sets opret_host, writes MPC entropy, calls rgb_commit once, then consumes the fascia and returns the consignments for every staged contract.

Questions:

• Does the staged primitive split look acceptable in principle, or is there a different decomposition you'd prefer?
• Are there RGB-level invariants we'd be breaking by having two parties contribute transitions before rgb_commit is called?

[zoedberg]

First of all I wouldn't add a new module. If the APIs will be available only for the singlesig wallet please put them in the singlesig.rs module and the necessary method implementations in offline.rs/online.rs according to the necessity of the API impl of being online or not. Objects can go in objects.rs.

The APIs need a better description, for example create_swap_offer gets a proxy_url but the description doesn't mention what the proxy would be used for. Also, to give an informed reply, we need to define what the objects would contain.

Does the staged primitive split look acceptable in principle, or is there a different decomposition you'd prefer?

If possible, I would design a flow that works for both RGB<>BTC and RGB<>RGB. I'm not sure the color_psbt_stage and color_finalize approach is the correct one, I need to grasp more details in order to answer this.

Are there RGB-level invariants we'd be breaking by having two parties contribute transitions before rgb_commit is called?

An interactive RGB transfer is possible, check https://github.com/rgb-protocol/rgb-tests/blob/0b35facf99e35f5bc425d294717eb7e94d4cf7c8/tests/transfers.rs#L1064

About static blinding and PSBT deterministic reconstruction I have some doubts, parties already need to interact to perform the swap, what is this part useful for?
Also note that in general the 2 parties may not know the history of the asset(s), so they need to be able to share consignment(s) in order to validate the history before proceeding.

Finally, note that we can consider adding APIs to the proxy to support this use case, only if necessary and no other ways are possible.

[Arshia-r-m]

Thanks again for the guidance. I refactored the proposal a bit to better match with the structure you explained.

Currently, the same flow supports BTC<>RGB and RGB<>RGB, and I'll open an PR soon so you can also take a look at them in details, but before that there are some design points I'd like your opinion on:

For now, asset history is exchanged through the existing proxy consignment mechanism, using a distinct lookup key. This avoids requiring proxy API changes, but semantically asset history and transfer consignments are different payloads. Do you think reusing the existing proxy endpoint is acceptable for a first version, or would you prefer adding a dedicated proxy API for swap asset-history exchange?

I’d also appreciate your opinion on the RGB-RGB internal flow: internally the maker reconstructs the fascia from the finalized PSBT in order to consume the RGB state and generate their consignment. Does this seem compatible with the RGB invariants you’d expect rgb-lib to preserve?

Also:

I'm not sure the color_psbt_stage and color_finalize approach is the correct one

By saying that you mean exposing them as a high level APIs or using them as part of the flow?

[nicbus]

For now, asset history is exchanged through the existing proxy consignment mechanism, using a distinct lookup key. This avoids requiring proxy API changes, but semantically asset history and transfer consignments are different payloads. Do you think reusing the existing proxy endpoint is acceptable for a first version, or would you prefer adding a dedicated proxy API for swap asset-history exchange?

Assuming asset history is exchanged via a consignment (although not a transfer one) I don't see issues in using the existing RGB proxy consignment.* APIs.

I’d also appreciate your opinion on the RGB-RGB internal flow: internally the maker reconstructs the fascia from the finalized PSBT in order to consume the RGB state and generate their consignment. Does this seem compatible with the RGB invariants you’d expect rgb-lib to preserve?

Reconstructing the fascia from the PSBT should be ok.

Also:

I'm not sure the color_psbt_stage and color_finalize approach is the correct one

By saying that you mean exposing them as a high level APIs or using them as part of the flow?

It's hard to validate a concept without a relatively detailed explanation of the architecture or logic flow. Having a sufficiently clear understanding of the idea is fundamental to analyze it and, with the currently available information, I don't think it's possible to tell if the proposed solution fits the problem.
In short, we need to dig deeper. Can you please provide a more detailed explanation of how it would all work?