🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →
Sign In

@webmobix/isin-lib-solidity

Package Overview
Dependencies
Maintainers
2
Versions
2
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@webmobix/isin-lib-solidity - npm Package Compare versions

Comparing version
1.0.0
 to
1.0.1
+140
README.md
# isin-lib-solidity
A Solidity library for efficient and reversible conversion between International Securities Identification Numbers (ISINs) as strings and `uint256` values directly within EVM smart contracts.
This library is crucial for smart contracts that need to manage or reference financial instruments identified by ISINs, enabling a direct and gas-optimized link between off-chain ISIN strings and on-chain `uint256` identifiers.
## Why This Library Matters
Financial instruments use 12-character alphanumeric ISINs for global identification. Smart contracts on EVM blockchains, however, primarily use `uint256` for unique IDs (like NFT tokenIds). This data type mismatch can be a hurdle. `isin-lib-solidity` provides a gas-efficient, on-chain solution using base36 encoding to convert ISIN strings to `uint256` and back. This ensures a reliable one-to-one mapping, vital for integrating traditional financial assets with DeFi applications directly on the blockchain.
## Features
- Converts ISIN strings (must be uppercase A-Z, 0-9, and 12 characters long) to `uint256`.
- Converts `uint256` values back to 12-character ISIN strings, padding with leading zeros if necessary.
- Uses base36 encoding, implemented with gas optimization in mind for Solidity.
- Includes input validation for ISIN string format and length.
- Designed as a library for easy integration into other smart contracts.
## Installation
**Using a package manager (e.g., npm/yarn for Hardhat/Truffle projects):**
```bash
npm install your-package-name # Or your actual package name
# or
yarn add your-package-name # Or your actual package name
```
Then import in your Solidity contract:
```solidity
// Adjust path if your package structure is different
import "your-package-name/contracts/ISINLib.sol";
```
```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
import "./ISINLib.sol"; // Or from node_modules if installed
contract FinancialProductRegistry {
mapping(uint256 => string) public idToIsinString;
mapping(string => uint256) public isinStringToId; // Be mindful of gas costs for string keys
event ProductRegistered(
string indexed isinString,
uint256 indexed instrumentId
);
/**
* @notice Registers a product using its ISIN string.
* @param isinString The ISIN of the product as a 12-character string (uppercase A-Z, 0-9).
*/
function registerProduct(string memory isinString) public {
// The ISINLib.toUint256 function already requires 12 chars.
// Additional check for empty string can be done if needed, though ISINLib will revert.
// require(bytes(isinString).length > 0, "ISINLib: ISIN string cannot be empty");
require(
isinStringToId[isinString] == 0,
"ISINLib: Product already registered with this ISIN"
);
uint256 instrumentId = ISINLib.toUint256(isinString); // Library function call
idToIsinString[instrumentId] = isinString;
isinStringToId[isinString] = instrumentId;
// --- Placeholder for NFT minting logic (e.g., ERC721 _mint) ---
// _mint(msg.sender, instrumentId);
// --- End Placeholder ---
emit ProductRegistered(isinString, instrumentId);
}
/**
* @notice Retrieves the ISIN string for a given instrument ID.
* @param instrumentId The uint256 ID of the instrument.
* @return The ISIN string.
*/
function getIsinFromId(
uint256 instrumentId
) public view returns (string memory) {
string memory isinString = idToIsinString[instrumentId];
// ISINLib.fromUint256(0) returns "000000000000".
// If an ID 0 is not a valid instrumentId, or if empty string means not found:
require(
bytes(isinString).length > 0,
"ISINLib: Instrument ID not found or ISIN is empty"
);
return isinString;
}
/**
* @notice Retrieves the instrument ID for a given ISIN string.
* @param isinString The ISIN string of the instrument.
* @return The uint256 instrument ID.
*/
function getIdFromIsin(
string memory isinString
) public view returns (uint256) {
uint256 instrumentId = isinStringToId[isinString];
require(instrumentId != 0, "ISINLib: ISIN not found"); // Assumes ID 0 is not used for valid ISINs
return instrumentId;
}
}
```
## API
The ISINLib.sol library provides the following core functions:
`function toUint256(string memory isin) internal pure returns uint256 numericValue)`
- Encodes an ISIN string to a uint256 value.
- Parameters:
- isin (string memory): The ISIN string to encode (must be uppercase A-Z, 0-9, and 12 characters long).
- Returns: The uint256 representation of the ISIN.
- Reverts if the ISIN string is not 12 characters long or contains invalid characters.
`function fromUint256(uint256 value) internal pure returns (string memory isin)`
- Decodes a uint256 back to an ISIN string.
- Parameters:
- value: The uint256 value to decode.
- Returns: The original ISIN string (12 characters, padded with leading '0's if necessary). "000000000000" for input 0.
- Reverts if the input value is greater than MAX_ISIN_VALUE (36^12 - 1).
## Sister Libraries
This library can be complemented by similar libraries in other languages for consistent ISIN <=> uint256 conversion across different environments:
- For JavaScript/TypeScript front-end or Node.js applications
[https://github.com/webmobix/isin-lib-js](https://github.com/webmobix/isin-lib-js)
- For Java applications
[https://github.com/webmobix/isin-lib-java](https://github.com/webmobix/isin-lib-java)
## Contributing
Contributions are welcome.
+59
-55
package.json
{
"name": "@webmobix/isin-lib-solidity",
"version": "1.0.0",
"description": "ISIN to uint256 conversion library",
"main": "index.js",
"files": [
"src/**/*.sol",
"artifacts/contracts/**/*.json",
"!artifacts/contracts/**/*.dbg.json"
],
"scripts": {
"prepare": "husky install",
"clean": "rimraf artifacts cache types",
"build": "hardhat compile && forge build",
"test": "hardhat test && forge test",
"test:hardhat": "hardhat test",
"test:foundry": "forge test",
"lint": "solhint 'src/**/*.sol'",
"format": "prettier --write 'src/**/*.sol' 'test/**/*.sol'",
"docs": "hardhat docgen"
},
"keywords": [
"solidity",
"ethereum",
"smart-contracts",
"isin",
"blockchain"
],
"author": "Danny Thuering <danny@webmobix.com> (https://webmobix.com)",
"license": "Apache-2.0",
"devDependencies": {
"@nomiclabs/hardhat-ethers": "^2.0.0",
"@nomiclabs/hardhat-waffle": "^2.0.0",
"@typechain/ethers-v5": "^7.0.0",
"@typechain/hardhat": "^2.0.0",
"@types/chai": "^4.0.0",
"@types/mocha": "^8.0.0",
"@types/node": "^16.0.0",
"chai": "^4.0.0",
"ethereum-waffle": "^3.0.0",
"ethers": "^5.0.0",
"hardhat": "^2.0.0",
"hardhat-gas-reporter": "^1.0.0",
"husky": "^7.0.0",
"prettier": "^2.0.0",
"prettier-plugin-solidity": "^1.0.0",
"rimraf": "^3.0.0",
"solhint": "^3.0.0",
"ts-node": "^10.0.0",
"typechain": "^5.0.0",
"typescript": "^4.0.0"
},
"peerDependencies": {
"@openzeppelin/contracts": "^4.0.0"
}
}
"name": "@webmobix/isin-lib-solidity",
"version": "1.0.1",
"description": "ISIN to uint256 conversion library",
"main": "index.js",
"files": [
"src/**/*.sol",
"artifacts/contracts/**/*.json",
"!artifacts/contracts/**/*.dbg.json"
],
"scripts": {
"prepare": "husky install",
"clean": "rimraf artifacts cache types",
"build": "hardhat compile && forge build",
"test": "hardhat test && forge test",
"test:hardhat": "hardhat test",
"test:foundry": "forge test",
"lint": "solhint 'src/**/*.sol'",
"format": "prettier --write 'src/**/*.sol' 'test/**/*.sol'",
"docs": "hardhat docgen"
},
"keywords": [
"solidity",
"ethereum",
"smart-contracts",
"isin",
"blockchain"
],
"repository": {
"type": "git",
"url": "https://github.com/webmobix/isin-lib-solidity.git"
},
"author": "Danny Thuering <danny@webmobix.com> (https://webmobix.com)",
"license": "Apache-2.0",
"devDependencies": {
"@nomiclabs/hardhat-ethers": "^2.0.0",
"@nomiclabs/hardhat-waffle": "^2.0.0",
"@typechain/ethers-v5": "^7.0.0",
"@typechain/hardhat": "^2.0.0",
"@types/chai": "^4.0.0",
"@types/mocha": "^8.0.0",
"@types/node": "^16.0.0",
"chai": "^4.0.0",
"ethereum-waffle": "^3.0.0",
"ethers": "^5.0.0",
"hardhat": "^2.0.0",
"hardhat-gas-reporter": "^1.0.0",
"husky": "^7.0.0",
"prettier": "^2.0.0",
"prettier-plugin-solidity": "^1.0.0",
"rimraf": "^3.0.0",
"solhint": "^3.0.0",
"ts-node": "^10.0.0",
"typechain": "^5.0.0",
"typescript": "^4.0.0"
},
"peerDependencies": {
"@openzeppelin/contracts": "^4.0.0"
}
}