![](\"https://img.shields.io/npm/v/@rosen-bridge/rosen-extractor\")
\n ![](\"https://img.shields.io/npm/l/@rosen-bridge/rosen-extractor\")
\n\n
\n\n## Table of contents\n\n- [Description](#description)\n- [Installation](#installation)\n- [Usage](#usage)\n\n## Description\n\n`@rosen-bridge/rosen-extractor` is a core Rosen Bridge module responsible for extracting and validating bridge request data from blockchain transactions. It converts chain-specific transaction data into a standardized bridge request format consumed by Rosen Watcher and Guard services as part of the bridge verification and execution pipeline.\n\nThe extractor module is responsible for identifying and parsing bridge requests embedded in transactions across supported blockchains. It achieves this through a set of chain-specific extractors (such as `ErgoNodeRosenExtractor`, `CardanoKoiosExtractor`, and others), each of which understands the transaction structure and data formats of its respective chain and provider.\n\nIn addition to raw data extraction, the module performs several validation and normalization steps required by the bridge protocol (note that these steps are taken in the `AbstractRosenExtractor` class):\n\n- Destination addresses are validated against the target chain using `@rosen-bridge/address-codec` package.\n- Tokens are resolved through `TokenMap` to ensure the requested asset is supported on both the source and target chains.\n- Transfer amounts are normalized to account for differing decimal precisions across blockchains using `TokenMap.wrapAmount`.\n\nThe output of the extractor is a normalized bridge request object containing the target chain and address, source transaction information, token identifiers on both chains, transfer amount, and the bridge and network fees specified in the transaction. This object represents the canonical input used by Rosen Watchers for observation and by Guards for verification and signing.\n\nThe fees extracted by this package represent the values explicitly declared by the user in the transaction. They do not reflect the effective fees enforced by the protocol. If the specified fees are below the configured minimum fee—defined on-chain on Ergo—the Rosen Guards will apply the minimum fee instead. For more information on fee configuration and enforcement, see the [`@rosen-bridge/minimum-fee`](https://www.npmjs.com/package/@rosen-bridge/minimum-fee) package.\n\nThe extracted bridge request data includes the following fields:\n\n- **`toChain`**: Target blockchain\n- **`toAddress`**: Destination address on the target blockchain\n- **`bridgeFee`**: Bridge fee specified in the transaction\n- **`networkFee`**: Network fee specified in the transaction\n- **`fromAddress`**: Source address transferring assets to the lock address\n- **`sourceChainTokenId`**: Token identifier on the source blockchain\n- **`amount`**: Transfer amount\n- **`targetChainTokenId`**: Token identifier on the target blockchain\n- **`sourceTxId`**: Source transaction identifier\n- **`rawData`**: Raw transaction data from which the request was extracted\n\n> Note: The `rawData` field is a small subset of the original transaction data while omitting the irrelevant data. It is included for reference and debugging purposes. For example, on Bitcoin, the `rawData` is the scriptPubKey of OP_RETURN output that contains Rosen data while on Bitcoin-Runes, it is the entire transaction outputs.\n\nThere are two functions that can be used to extract the bridge request data:\n\n1. `extractData`: This function takes a transaction data as input and returns the extracted bridge request data. It is implemented in the child classes based on the chain and provider.\n2. `get`: This function wraps the `extractData` function and adds additional validation and normalization steps (i.e., validate the destination address and normalize the amount). It is recommended to use this function instead of `extractData` as it provides a more consistent and reliable output. It is implemented in the `AbstractRosenExtractor` class.\n\n## Installation\n\n```sh\nnpm i @rosen-bridge/rosen-extractor\n```\n\n## Usage\n\nThis package requires the `@rosen-bridge/address-manager` package for the decoding and validation of addresses in the bridge request. Please make sure to initialize the `AddressManager` before using any of the extractor classes. You can define the validator and decoder functions based on your needs. Alternatively, you can initialize it with the implementations of `address-codec` package:\n\n```ts\nimport { ConsoleLogger } from '@rosen-bridge/abstract-logger';\nimport { chainValidators, chainDecoders } from '@rosen-bridge/address-codec';\nimport { AddressManager } from '@rosen-bridge/address-manager';\n\nAddressManager.init(chainValidators, chainDecoders, new ConsoleLogger());\n```\n\nTo use the class, The transaction data must be provided in the format expected by the specific extractor class being used. Here's a basic example of how to use this package:\n\n```typescript\nimport { ErgoNodeRosenExtractor } from '@rosen-bridge/rosen-extractor';\nimport { TokenMap } from '@rosen-bridge/tokens';\nimport ergoNodeClientFactory from '@rosen-clients/ergo-node';\n\n// generate the Ergo node client\nconst ergoNodeUrl = '';\nconst nodeClient = ergoNodeClientFactory(ergoNodeUrl);\n\n// get the transaction from Ergo node\nconst lockTxId =\n '9115d6d6f22269949de1118f1415e7ef8aa717b232f3c6a3710178475a87af05'; // a sample lock transaction\nconst tx = await nodeClient.getTxById(lockTxId);\n\n// generate the TokenMap\nconst tokenMapJson = {}; // you can get the token map json from GitHub releases (https://github.com/rosen-bridge/contract/releases)\nconst tokenMap = new TokenMap();\nawait tokenMap.updateConfigByJson(tokenMapJson);\n\n// generate the Rosen Extractor for Ergo Node provider\nconst ergoLockAddress =\n 'nB3L2PD3J4rMmyGk7nnNdESpPXxhPRQ4t1chF8LTXtceMQjKCEgL2pFjPY6cehGjyEFZyHEomBTFXZyqfonvxDozrTtK5JzatD8SdmcPeJNWPvdRb5UxEMXE4WQtpAFzt2veT8Z6bmoWN'; // the Rosen lock address on Ergo the time of the sample\nconst rosenExtractor = new ErgoNodeRosenExtractor(ergoLockAddress, tokenMap);\n\n// extract and display the Rosen data\nconst res = rosenExtractor.get(tx);\nconsole.log(res);\n```\n","readmeFilename":"README.md"}