In the growing domain of tokenized real-world assets, one challenge consistently slows things down: how do you map traditional financial identifiers, like ISINs, onto blockchain-native data types?
It’s not just a developer nuisance. This gap impacts efficiency, data integrity, and the usability of tokenized assets in DeFi systems.
The problem: ISINs vs. smart contract IDs
An ISIN (International Securities Identification Number) is a 12-character code that uniquely identifies financial instruments like stocks, bonds, and derivatives. Its format—two letters for the country, nine characters for the security, and a check digit—makes it readable but not blockchain-friendly.
On the other side, Ethereum and other EVM-compatible blockchains rely on uint256 values to uniquely identify tokens, particularly for standards like ERC-721 (used in NFTs). These numerical identifiers are efficient, compact, and gas-optimized.
So what happens when you need to represent a traditional ISIN-tagged instrument in a smart contract? You hit a type mismatch: ISINs are strings, while smart contracts prefer numbers. Storing ISINs as strings on-chain is both expensive and slow.
Our fix: clean, reversible conversion using base36
To solve this, we built a suite of open-source libraries that convert ISINs into uint256 values using base36 encoding—and back again. Base36 is a compact way of encoding alphanumeric strings using the characters 0-9 and A-Z. Because ISINs only use those characters, base36 is a perfect match.
The conversion process:
- ISIN to uint256: Normalize the ISIN (uppercase), convert it from base36 to base10.
- uint256 to ISIN: Convert the number from base10 back to base36 and pad to 12 characters.
This ensures a 1:1 reversible mapping that maintains the integrity and usability of the identifier.
Our tools: isin-lib libraries for every layer
We’ve built three language-specific libraries to support different use cases:
JavaScript / TypeScript (isin-lib-js)
Perfect for browser apps and Node.js backends.
import { isinToUint256, uint256ToIsin } from "@webmobix/isin-lib-js";
const isin = "US0378331005";
const uintVal = isinToUint256(isin);
console.log(uint256ToIsin(uintVal));
Java (isin-lib-java)
Ideal for enterprise systems.
BigInteger uintVal = ISINConverter.isinToUint256("US0378331005");
System.out.println(ISINConverter.uint256ToIsin(uintVal));
Solidity (isin-lib-solidity)
Engineered for low-gas, on-chain execution.
string isin = "US0378331005";
uint256 id = ISINLib.isinToUint256(isin);
Each library maintains consistency across platforms, ensuring seamless integration between backend systems, front-end apps, and on-chain smart contracts.
Why it matters
Tokenization isn’t just theoretical—many financial institutions are actively exploring it. Having a robust, efficient, and verifiable way to bring ISIN-identified instruments onto the blockchain is a crucial step in making tokenization viable at scale.
By offering a deterministic conversion mechanism across JavaScript, Java, and Solidity, we’ve built a foundational bridge between TradFi and DeFi, grounded in both real-world finance and smart contract best practices.
Explore the libraries
- TypeScript/JavaScript: github.com/webmobix/isin-lib-js
- Java: github.com/webmobix/isin-lib-java
- Solidity: github.com/webmobix/isin-lib-solidity
If you’re developing financial applications, token registries, or on-chain asset systems, this libraries are ready to plug into your stack.