Skip to content

Add RGB contract consignment import and export - #103

Open
Jainakin wants to merge 1 commit into
RGB-Tools:masterfrom
Jainakin:hardik/contract-consignment-import
Open

Add RGB contract consignment import and export#103
Jainakin wants to merge 1 commit into
RGB-Tools:masterfrom
Jainakin:hardik/contract-consignment-import

Conversation

@Jainakin

Copy link
Copy Markdown

Closes #56

Problem

Asset registries need a standard RGB contract consignment that can be verified and imported independently of any asset transfer. An asset ID alone cannot reconstruct or validate the contract, while a transfer consignment carries ownership history that is not appropriate for contract preload.

Changes

  • re-export RgbContract and expose Wallet::export_asset_contract
  • add offline Wallet::import_asset_contract for contracts without external media
  • add Wallet::import_asset_contract_with_media for contracts whose attachment bytes are supplied out of band
  • return canonical metadata and whether the complete contract state was already imported
  • make repeated imports idempotent and repair media-only, stock-only, and database-only interrupted states
  • move pure attachment extraction to the offline wallet surface and cover every NIA, CFA, IFA, and UDA media location
  • add explicit RGB stock persistence control so write errors reach the caller and read-only operations do not rewrite stock

The exported value uses rgb-ops' standard ASCII-armored RGB CONSIGNMENT Display/FromStr representation, including the canonical ID, contract ID, schema, version, type, and SHA-256 checksum headers.

Safety and semantics

  • import validates the supported schema, exact wallet network, contract identity, and full contract consignment before mutation
  • a private non-panicking resolver rejects witness-bearing/history-shaped input
  • contract preload registers public contract identity and metadata only; it creates no allocation, transfer, or wallet ownership, so the initial wallet balance is zero
  • post-transfer exports are verified to contain only the standalone contract and no private transfer bundles or terminals
  • media is matched by the digest committed in the contract, streamed with bounded memory, re-hashed while copying, atomically placed, and directory-synced on Unix targets
  • stock is durably persisted before the SQL transaction commits; every interruption prefix is retryable
  • the existing save_new_asset transfer-consignment API and its behavior are unchanged

Validation

Green locally:

  • cargo fmt -- --check
  • strict Clippy with all features, no default features, Electrum-only, and Esplora-only
  • release builds with all features, no default features, Electrum-only, and Esplora-only
  • no-default-feature tests: 42 passed, including offline export/import
  • contract-focused Docker integration tests: 9 passed
  • doc tests: 2 passed
  • full all-feature suite: 309 passed and 5 ignored

The remaining three local all-feature failures are the existing external multisig-hub tests (multisig::fail, multisig::send_to_oneself, and multisig::success), all returning Missing or invalid credentials from the local hub environment. Upstream Linux CI is still required before this draft is ready for review.

Coverage

Tests cover:

  • canonical armor serialization and parser round-trip
  • NIA, CFA, IFA, and UDA
  • all declared contract/token media locations
  • missing, unexpected, duplicate, corrupt, and repaired media
  • wrong-network rejection
  • malicious history-bearing contract input
  • a real export after a settled transfer
  • zero-balance semantics and idempotent re-import
  • stock-only and database-only recovery
  • deterministic runtime-lock contention and successful retry
  • unknown-asset export errors

@Jainakin
Jainakin marked this pull request as ready for review August 18, 2026 05:38
@codecov

codecov Bot commented Aug 19, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 88.18182% with 39 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.04%. Comparing base (fd1aca2) to head (a806aee).

Files with missing lines Patch % Lines
src/wallet/rust_only.rs 86.64% 37 Missing ⚠️
src/utils.rs 90.47% 2 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master     #103      +/-   ##
==========================================
- Coverage   96.24%   96.04%   -0.20%     
==========================================
  Files          24       24              
  Lines       13418    13706     +288     
==========================================
+ Hits        12914    13164     +250     
- Misses        504      542      +38     
Flag Coverage Δ
rust 96.04% <88.18%> (-0.20%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add method to export/import contract consignment

1 participant