npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@unisat/rgb-service

v2.2.0

Published

Local RGB wallet service for transaction orchestration and state management

Readme

RGB Service

@unisat/rgb-service is the local RGB wallet orchestration boundary. It does not depend on rgb-sdk, does not persist a mnemonic or xpub, and does not ask a backend to build a PSBT.

The host supplies five adapters:

  • RgbStateSource: address-scoped colored UTXO snapshots and post-broadcast indexing.
  • RgbProtocolEncoder: local invoice, transition, commitment, PSBT and consignment logic.
  • RgbStorage: encrypted extension or platform storage for local state and UTXO locks.
  • RgbTransport: consignment delivery only.
  • BitcoinBroadcaster: raw transaction broadcast only.

The intended flow is:

sync colored UTXOs -> prepare local RGB PSBT -> HD keyring signs
-> publish consignment -> recipient validates and ACKs -> broadcast raw transaction
-> sync txid/outpoints

RGB proxy transport

The extension uses the RGB HTTP JSON-RPC proxy protocol for consignment transport. Configure public endpoints with rgbProxyEndpoints in the current chain entry of @unisat/wallet-shared so they are embedded in locally created blind invoices. rpcs:// is sent over HTTPS; rpc:// is supported only for local development. After signing, the wallet posts the consignment, waits for ack.get to return true, and only then broadcasts the Bitcoin transaction. The signed transfer remains in encrypted local storage while the acknowledgement is pending and is retried by the next RGB sync.

protocol/nia.ts implements the NIA fungible Transition, OpCommitment and OpId layers. protocol/nia-genesis.ts implements the no-media NIA Genesis used by the issue flow, including its contract ID. Both are checked against deterministic rgb-lib vectors. A fallback that creates an ordinary BTC transaction is unsafe and must not be added.

Before encoding, the service produces a local fungible transition plan. It conserves the requested allocation and records every other allocation on an input UTXO that needs a preservation transition. This prevents an encoder from silently losing co-located RGB assets.

protocol/strict.ts implements the strict-encoding primitive writer. In particular, confined collection lengths use a fixed little-endian width selected from their declared maximum bound.

protocol/anchor.ts applies the RGB OpretFirst placement rule before a commitment is written. protocol/mpc.ts produces the LNPBP-4 MPC commitment that is embedded in that output. protocol/fascia.ts serializes the OpretFirst Fascia once the local PSBT builder has produced the witness transaction. protocol/psbt-commit.ts writes the MPC, OPRET and RGB proprietary records and updates the unsigned transaction before signing.

protocol/psbt.ts encodes the BIP174 proprietary key/value records used by the RGB reference implementation for OPRET hosts, OPRET commitments and RGB transitions. It accepts strict-serialized transition bytes from the caller; schema-specific transition serialization remains a separate step.

BFA local codec

protocol/local-bfa-encoder.ts builds the BFA transfer PSBT, Transition, Opret commitment and signed v1 WitnessBundle in the extension. The existing blind and witness invoice encoders also run in the extension and are independent of the asset schema. protocol/bfa-consignment.ts wraps the new bundle with the validated BFA Genesis and ancestor bundles in the v1 transfer format.

The send codec requires ValidatedBfaTransferHistory: a BFA Genesis, exact ancestor v1 WitnessBundles and proved OS_ASSET allocations. The local validateBfaTransferConsignment implementation checks the supported v1 mint/transfer profile, operation IDs, Bitcoin witness commitments and parent seals, and finalized EVM FundsIn events. It requires a Bitcoin confirmation resolver and an EVM JSON-RPC transport. The wallet background selects the RPC from rgbEvmRpcUrls in wallet-shared/src/constants/common.ts by the chain ID committed in Genesis. The T0 map is intentionally empty until a bridge RPC is configured. Unsupported contract features fail closed. The wallet routes BFA send and receive through this validator and local encoder; received and sent histories are merged into the encrypted local checkpoint. If Bitcoin or EVM chain data is temporarily unavailable, a BFA receive remains pending instead of being rejected.

The BFA burn path consumes validated asset allocations and commits a TS_BURN transition to a locally signed Bitcoin transaction. It has no invoice, recipient, proxy post, or acknowledgement. The signed v1 transfer consignment has no terminals and is retained in the encrypted wallet state for export as an RGB\0TFR .rgb file from transfer details. Broadcast failures require an explicit retry; ordinary synchronization never rebroadcasts a burn. Burning does not submit a redemption request to an EVM bridge.

For Arbitrum One, the wallet keeps the legacy direct-route format: a 20-byte EVM address is left-padded with 12 zero bytes in burnReason. For Ethereum, Polygon PoS, Plasma, and Tron, it constructs the V1 destination record and commits its EIP-712-style hash as burnReason. The record contains version, destinationChainId, dstEid, and chain-native recipient bytes. The UI downloads the original record as JSON alongside the .rgb consignment; both are needed by the redemption operator. The exported JSON uses the gateway's BfaBurnDestination fields, including a 0x-prefixed hex recipient, and belongs in the burnDestination field of /unlock/verify and /unlock requests. The wallet retains the record in its encrypted state and verifies its hash on export. The destination cannot be changed after signing. A V1 hash alone is insufficient to redeem a burn.

The staging gateway OpenAPI documents burnDestination for both /unlock/verify and /unlock. The older public integration guide still shows only the legacy request body. Before using a V1 burn with real funds, confirm that the chosen route and token are enabled in the target deployment. This wallet does not submit the unlock request.

Enablement requirement

The address-scoped UTXO snapshot supplies only the parent operation pointer needed to consume an allocation. It is not enough to create a standards-valid recipient consignment: that requires the asset Genesis and every parent transfer/bundle on the allocation's validation path. Those opaque RGB payloads may be fetched from a transport or restored from encrypted local storage, but they must never be reconstructed by a backend wallet service.

The BFA path requires complete validated ancestry before a send. It does not attempt to reconstruct missing transitions from an address-scoped balance.

Synthetic round-trip stress test

An RGB transfer embeds its ancestor witness bundles in the next Consignment. Consequently, repeatedly moving one asset A -> B -> A makes the newest Consignment grow approximately linearly with the transfer count, while the total encoding and validation work across the run is approximately quadratic.

Run the local history stress test without a proxy, broadcaster, real key, or testnet fee:

RGB_STRESS_ROUNDS=100 pnpm --filter @unisat/rgb-service test:roundtrip-stress
RGB_STRESS_ROUNDS=1000 RGB_STRESS_LOG_EVERY=100 pnpm --filter @unisat/rgb-service test:roundtrip-stress

The test uses blind invoices pointed at alternating, synthetic Taproot funding UTXOs. It validates the complete Consignment history each round and prints JSON metrics for Consignment bytes, history bundle count, per-step latency, and total serialized bytes. It is a local protocol/load test only: it does not test two real keyrings, proxy ACKs, Bitcoin confirmation, or backend indexing.

Validation attestations

A wallet API may run the same v1 validator and sign a short-lived attestation bound to the exact payload hash, network, Genesis and bundle DAG. The wallet accepts it only from a release-pinned Ed25519 key, reparses the payload with its private blind seals, and checks every attested bundle identity and edge. Invalid, expired and dynamic-reject-list attestations fall back to complete local validation; blind-seal ownership and invoice matching never move to the server.

Legacy NIA v0 transfers are accepted through a constrained compatibility boundary: the service parses and converts them to the canonical v1 envelope, then uses the same v1 validator and allocation matching path as a native v1 transfer. Accepted history is stored as v1 while the original v0 payload is retained only as recovery compatibility data. The legacy parser is not an independent acceptance authority.