{"id":13408977,"url":"https://github.com/ezalabs/multiversx-spring-boot-starter-reactive","last_synced_at":"2025-03-14T14:30:27.292Z","repository":{"id":44780924,"uuid":"410107912","full_name":"ezalabs/multiversx-spring-boot-starter-reactive","owner":"ezalabs","description":"Spring Boot Starter Reactive for MultiversX Network integration ","archived":false,"fork":false,"pushed_at":"2023-10-05T11:17:15.000Z","size":484,"stargazers_count":14,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-05-20T03:15:53.269Z","etag":null,"topics":["blockchain","multiversx","spring-boot-starter"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ezalabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-24T21:36:34.000Z","updated_at":"2024-07-30T22:50:59.196Z","dependencies_parsed_at":"2023-07-30T14:08:03.826Z","dependency_job_id":"f5afd01e-71ac-4bb0-b10e-7ada30d91161","html_url":"https://github.com/ezalabs/multiversx-spring-boot-starter-reactive","commit_stats":null,"previous_names":["crldev-software/multiversx-spring-boot-starter-reactive","crldev-software/elrond-spring-boot-starter-reactive","ezalabs/multiversx-spring-boot-starter-reactive"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ezalabs%2Fmultiversx-spring-boot-starter-reactive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ezalabs%2Fmultiversx-spring-boot-starter-reactive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ezalabs%2Fmultiversx-spring-boot-starter-reactive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ezalabs%2Fmultiversx-spring-boot-starter-reactive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ezalabs","download_url":"https://codeload.github.com/ezalabs/multiversx-spring-boot-starter-reactive/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243593170,"owners_count":20316147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","multiversx","spring-boot-starter"],"created_at":"2024-07-30T20:00:57.041Z","updated_at":"2025-03-14T14:30:26.912Z","avatar_url":"https://github.com/ezalabs.png","language":"Java","funding_links":[],"categories":["MultiversX community"],"sub_categories":["SDKs and dev tools"],"readme":"# MultiversX Spring Boot Starter Reactive\n\nThis is a **Spring Boot Starter** project for integrating with the **MultiversX Network**, with the\ngoal of achieving an **effortless autoconfigured integration** with the network.\\\nThe client is implemented using project Reactor as the Reactive Streams' specification\nimplementation, allowing **fully non-blocking operations** and providing **efficient demand\nmanagement** when interacting with the network, ideal for building **scalable reactive\nmicroservices**.\n\n\n[![java](https://img.shields.io/badge/Java17-07405E?style=for-the-badge\u0026logo=java\u0026logoColor=white)](https://openjdk.java.net/projects/jdk/11)\n[![spring](https://img.shields.io/badge/SpringBoot3.0-217346?style=for-the-badge\u0026logo=spring\u0026logoColor=white)](https://spring.io/projects/spring-boot)\n[![reactor](https://img.shields.io/badge/reactor-navy?style=for-the-badge\u0026logo=s\u0026logoColor=white)](https://projectreactor.io/)\n\n## Author\n\n[@carlo-stanciu](https://www.github.com/carlo-stanciu)\n\n\n## Features\n\n- Auto synchronise network configurations from the MultiversX Network at startup based on the\n  configured gateway\n- Non-blocking network requests with the reactive MultiversX client\n- Easy to use Interactors for executing various blockchain operations\n- A lot of abstracted complexity in creating addresses, wallets, transactions\n\n## Usage\n\nTo use the starter, add the following dependency to the dependencies section of your build\ndescriptor:\n\n- Maven (in your pom.xml)\n\n```\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.ezalabs\u003c/groupId\u003e\n  \u003cartifactId\u003emultiversx-spring-boot-starter-reactive\u003c/artifactId\u003e\n  \u003cversion\u003e1.2.1\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n- Gradle (in your build.gradle file)\n\n```\ndependencies {\n  implementation(group: 'io.ezalabs', name: 'multiversx-spring-boot-starter-reactive', version: '1.2.1')\n}\n```\n\n- And some other required dependencies for cryptographic functions:\n\n```\nimplementation group: 'org.bouncycastle', name: 'bcmail-jdk15on', version: '1.70'\nimplementation group: 'org.bouncycastle', name: 'bcpkix-jdk15on', version: '1.70'\nimplementation group: 'org.bouncycastle', name: 'bcprov-jdk15on', version: '1.70'\nimplementation group: 'org.bouncycastle', name: 'bcprov-ext-jdk15on', version: '1.70'\nimplementation group: 'org.bitcoinj', name: 'bitcoinj-core', version: '0.16.2'\n```\n\n## Documentation\n\nFirst part of integration is setting up ```application.yaml```. If nothing is set, defaults will be\nused.\n\n```yml\nspring:\n  multiversx:\n    client:\n      (optional) gateway: devnet (default) (mainnet | testnet | devnet)\n      (optional) customProxyUrl: https://custom-proxy.com\n      readTimeoutMillis: 10000 (default)\n      writeTimeoutMillis: 10000 (default)\n```\n\nThe project uses object notations from the **blockchain terminology** like **Address, Wallet,\nTransaction, Nonce, Gas, Signature** etc ... so it's required to be familiar with them.\n\nAn **[Address](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/account/Address.java)**\ncan be instantiated in two ways:\n\n```\n- fromHex (public key in HEX String)\n- fromBech32 (address in Bech32 String)\n```\n\nA **[Wallet](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/wallet/Wallet.java)**\nis used for **signing transactions**. It can be instantiated in multiple ways:\n\n```\n- fromPrivateKeyBuffer (private key in byte[] format)\n- fromPrivateKeyHex (private key in HEX String)\n- fromPemFile (using a PEM file as an input) (both File \u0026 reactive FilePart supported)\n- fromMnemonic (using a mnemonic phrase)\n- fromKeyStore (not yet implemented)\n```\n\nWe can generate a mnemonic phrase by\nusing **[MnemonicsUtils](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/util/MnemonicsUtils.java)**\n.\n\nThe interaction with the MultiversX Network is done with the help of a set components called **\nInteractors**, which provide all the required functionalities based on segregated parts of the\nnetwork:\n\n**[Account Interactor](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/interactor/account/MxAccountInteractor.java)**\n\n```\n- getAccountInfo\n- getBalance\n- getNonce\n- getTransactions\n- getStorageValue\n- getStorage\n```\n\n**[Block Interactor](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/interactor/block/MxBlockInteractor.java)**\n\n```\n- queryHyperblockByNonce\n- queryHyperblockByHash\n- queryShardBlockByNonceFromShard\n- queryShardBlockByHashFromShard\n```\n\n**[Network Interactor](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/interactor/network/MxNetworkInteractor.java)**\n\n```\n- getNetworkConfig\n- getShardStatus\n- getNodeHeartbeatStatus\n```\n\n**[Transaction Interactor](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/interactor/transaction/MxTransactionInteractor.java)**\n\n```\n- sendTransaction\n- sendBatchOfTransactions\n- simulateTransaction\n- estimateTransactionCost\n- queryTransactionInfo\n- queryTransactionStatus\n```\n\nThe Transaction Interactor has methods used for a more granular approach to transaction operations.\\\nIn order to create a sendable transaction, we must first create an instance of a transaction\nusing **[Transaction](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/transaction/Transaction.java)**\ndomain object (setting **nonce, gasLimit, version** etc), then sign it using a wallet and transform\nit to a payload for the Transaction Interactor (using **toSendable()** method).\n\nFor a more simple way of doing transaction operations, the interactor also has overloaded methods\nfor **sending, simulating and estimating.**\nThe methods are abstracting the complexity of transaction creation: automatically assigns proper\nnonce value, computes fee based on data input and applies the signature before execution. The\nrequired inputs are\na **[Wallet](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/wallet/Wallet.java)**\nand the following payload with minimum necessary data:\n\n**[TransactionRequest](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/interactor/transaction/TransactionRequest.java)**\n\n```\n - receiver address\n - value\n - data\n - gas limit (optional)\n```\n\nExample usage:\n\n```java\n@Autowired MxTransactionInteractor interactor;\n\n    Mono\u003cTransactionHash\u003e sendTransaction(File pemFile){\n    var wallet=WalletCreator.fromPemFile(pemFile);\n\n    var tRequest=TransactionRequest.builder()\n    .receiverAddress(Address.fromBech32(\"erd1gklqdvxxxxxxxxxxxxxxxxxxxxx\"))\n    .value(Balance.fromEgld(3.5))\n    .data(PayloadData.fromString(\"hello MultiversX\"))\n    .build();\n\n    return interactor.sendTransaction(wallet,tRequest);\n    }\n```\n\n**[Smart Contract Interactor](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/interactor/smartcontract/MxSmartContractInteractor.java)**\n\n```\n- callFunction\n- query\n- queryHex\n- queryString\n- queryInt\n```\n\nThis component has methods which interact with the smart contracts on the network (obviously).\n\nIn order to call a smart contract function, we need to pass an instance of ContractFunction:\n\n**[ContractFunction](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/smartcontract/ContractFunction.java)**\n\n```\n - smart contract address\n - function name\n - array of arguments\n - value\n - gas limit (optional)\n```\n\nExample usage:\n\n```java\n@Autowired MxSmartContractInteractor interactor;\n\n    Mono\u003cTransactionHash\u003e callFunction(File pemFile){\n    var wallet=WalletCreator.fromPemFile(pemFile);\n\n    var function=ContractFunction.builder()\n    .smartContractAddress(Address.fromBech32(\"erd1xxxxxxxxxxxxxxxxxxxx8llllsh6u4jp\"))\n    .functionName(FunctionName.fromString(\"addName\"))\n    .args(List.of(FunctionArg.fromString(\"MultiversX\"))\n    .value(Balance.zero())\n    .build();\n\n    return interactor.callFunction(wallet,function);\n    }\n```\n\nThe ContractFunction generates a payload based on function name and args (HEX encoded), creates,\nassigns nonce, gas (if not specified, default is used), signs and executes a transaction.\n\nAlso, for querying we can use the following object:\n\n**[ContractQuery](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/smartcontract/ContractQuery.java)**\n\n```\n - smart contract address\n - function name\n - array of arguments\n - value\n - caller address (optional)\n```\n\n**[ESDT Interactor](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/interactor/esdt/MxESDTInteractor.java)**\n\n```\n- processEsdtTransaction\n- getTokensForAccount\n- getTokenRolesForAccount\n- getAllTokens\n- getTokenProperties\n- getTokenSpecialRoles\n- getNftDataForAccount\n- getNftSftForAccount\n- getTokensWithRole\n```\n\nThis component has methods which cover all the ESDT related transaction and queries on the network.\n\n```processEsdtTransaction``` takes an ***ESDTTransaction*** arg, which has multiple implementations:\n\n* **[ESDTIssuance](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/esdt/ESDTIssuance.java)** (\n  can be of type FUNGIBLE, SEMI_FUNGIBLE, NON_FUNGIBLE or META)\n* **[ESDTGlobalOp](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/esdt/ESDTGlobalOp.java)** (\n  can be of type PAUSE, UNPAUSE, FREEZE, UNFREEZE or WIPE)\n* **[ESDTLocalOp](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/esdt/ESDTLocalOp.java)** (\n  can be of type MINT or BURN)\n* **[ESDTTransfer](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/esdt/ESDTTransfer.java)**\n* **[ESDTNFTMultiTransfer](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/esdt/ESDTNFTMultiTransfer.java)**\n* **[ESDTUpgrade](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/esdt/ESDTUpgrade.java)**\n* **[ESDTOwnershipTransfer](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/esdt/ESDTOwnershipTransfer.java)**\n* **[ESDTRoleAssignment](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/esdt/ESDTRoleAssignment.java)** (\n  can be SET or UNSET)\n* **[NFTCreation](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/esdt/NFTCreation.java)**\n* **[NFTAttributesUpdate](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/esdt/NFTAttributesUpdate.java)**\n* **[NFTAddURI](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/esdt/NFTAddURI.java)**\n* **[NFTCreationRoleTransfer](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/esdt/NFTCreationRoleTransfer.java)**\n* **[NFTStopCreation](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/esdt/NFTStopCreation.java)**\n* **[NFTSFTLocalOp](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/esdt/NFTSFTLocalOp.java)** (\n  can be of type ADD or BURN)\n* **[NFTSFTGlobalOp](src/main/java/io/ezalabs/multiversxspringbootstarterreactive/domain/esdt/NFTSFTGlobalOp.java)** (\n  can be of type FREEZE, UNFREEZE or WIPE)\n\nExample on how to issue a fungible ESDT:\n\n```java\n@Autowired MxESDTInteractor interactor;\n\n    Mono\u003cTransactionHash\u003e issueEsdt(File pemFile){\n    var wallet=WalletCreator.fromPemFile(pemFile);\n\n    var transaction=ESDTIssuance.builder()\n    .type(Type.FUNGIBLE)\n    .tokenName(TokenName.fromString(\"Fung Token\"))\n    .tokenTicker(TokenTicker.fromString(\"FNGTNK\"))\n    .initialSupply(TokenInitialSupply.fromNumber(BigInteger.TEN))\n    .decimals(TokenDecimals.fromNumber(2))\n    .properties(Set.of(\n    new TokenProperty(TokenPropertyName.CAN_FREEZE,true),\n    new TokenProperty(TokenPropertyName.CAN_CHANGE_OWNER,true),\n    new TokenProperty(TokenPropertyName.CAN_ADD_SPECIAL_ROLES,true)));\n\n    return interactor.processEsdtTransaction(wallet,transaction);\n    }\n```\n\nFor all transaction, the gas limit is already configured, but you can always set a custom value.\n\nThe rest of the ESDT operations are done in a similar fashion. NFT, SFT and META creation are also\nmade super easy. You can follow\nthe **[MultiversX ESDT documentation](https://docs.multiversx.com/tokens/esdt-tokens/)** where you\nhave the steps for all operations regarding ESDT, which are all covered by this framework.\n\n\u003cbr\u003e\n\n## Demo\n\nYou can find an example of a spring-boot service using this\nframework **[HERE](https://github.com/ezalabs/multiversx-spring-boot-demo)**.\n\n## Next features\n\nIn the next releases the following features have been planned:\n\n- Account storage API\n- Wallet Connect integration\n- Wallet Creator - method to instantiate wallet from password-protected JSON keystore file\n- Other enhancements\n\n## Changelog\n\n[All notable features and changes to this project will be documented in CANGELOG.md file](CHANGELOG.md)\n\n## Contributing\n\nContributions are always welcome!\n\nYou can get in touch with me using the links below and figure out together how to make the project\nbetter.\n\nAlso, if you appreciate my effort and want to help me develop \u0026 maintain the MultiversX Spring Boot\nFramework, you can buy me some coffee via xPortal.\n\n## 🔗 Links\n\n[![portfolio](https://img.shields.io/badge/ezalabs-purple?style=for-the-badge\u0026logo=noi\u0026logoColor=white)](https://ezalabs.io)\n[![linkedin](https://img.shields.io/badge/linkedin-0A66C2?style=for-the-badge\u0026logo=linkedin\u0026logoColor=white)](https://www.linkedin.com/carlo-cristian-stanciu)\n[![twitter](https://img.shields.io/badge/Twitter-1DA1F2?style=for-the-badge\u0026logo=twitter\u0026logoColor=white)](https://twitter.com/carlo_stanciu)\n\n\n\n  ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fezalabs%2Fmultiversx-spring-boot-starter-reactive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fezalabs%2Fmultiversx-spring-boot-starter-reactive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fezalabs%2Fmultiversx-spring-boot-starter-reactive/lists"}