Official TxMS logo
TxMS is a tool designed for converting binary data into a sequence of printable characters, following a process known as Binary-to-text encoding. This tool also enables the reverse operation, where text containing encoded transactions is decoded back into its original hexadecimal format. For SMS processing, TxMS utilizes the UTF-16 Big Endian (UTF-16BE) encoding standard to ensure proper handling and interpretation of the binary data.
Choose the provider that is most reliable for your needs and region.
You can find the open-source server processor at DataLayerHost/txms-server.
This tool is used for converting HEX encoding to UTF-16 Big Endian (UTF-16BE) and vice versa.
UTF-16 is a character encoding that can encode all 1,112,064 valid Unicode code points.
Big-endian is an order in which the "big end" (most significant value in the sequence) is stored first at the lowest storage address.
In contrast, little-endian is an order where the "little end" (least significant value in the sequence) is stored first.
Byte Index | 0 | 1 |
---|---|---|
Big-Endian | 12 | 34 |
Little-Endian | 34 | 12 |
An SMS can encode 160 7-bit characters into 140 bytes. However, not all characters represent a single character. Certain characters in GSM 03.38 require an escape character, such as: |, ^, {, }, €, [, ~, ]
and \
.
For Unicode SMS, we are limited to 70 characters (or 67 in multipart SMS).
Most providers do not accept invisible control characters, unused code points, or any type of invisible separator. They replace these with the character �
(U+FFFD
), which makes the transaction invalid.
Modern providers and phones support UCS-2 (a now-defunct character encoding), which has been replaced with UTF-16 Big Endian (UTF-16BE).
To prevent the rejection of certain characters, we prefix them with a tilde ~
character (007E), followed by the 2+2 hex digits converted to Unicode characters.
Both 2 hex digits receive the 01
prefix.
For example:
- We receive the hex
09CA
, which is not a valid Unicode character in Bengali. - We split it into two 2+2 parts.
- We prefix the first half with
01
, resulting in0109
, which is converted to ĉ. - We prefix the second part with
01
, resulting in01CA
, which is converted to NJ. - The converted characters are prefixed with a
~
tilde. - The result is the
~ĉNJ
string.
To divide transactions in the data feed, use the Line feed character. In scripts, this is usually referred to as \n
or \r
, depending on the OS.
Based on these findings, you should be capable of sending CORE transactions (or any others) encoded in UTF-16BE on modern networks and phones through SMS.
Notes:
- In some instances, you may need to swap the buffer from Little Endian to Big Endian.
- Base62 is a great tool for converting UTF-16 characters into ASCII.
- We exclude certain characters from the UTF-16 Basic Multilingual Plane:
Core Blockchain transactions should be packed into 2-3 SMS messages.
TxMS, while dependent on UTF-16, is shorter, making it slightly more efficient than plain HEX in the context of SMS.
However, there is a significant difference in the length of the messages.
In native systems that support UTF-16, you will always achieve the best or most competitive results.
The sms
function has been extended to support multiple numbers. You can now provide an array of numbers, and each will be validated individually. Valid numbers will be concatenated with a comma ,
to form the SMS endpoint.
- If the number is
true
, the default number for the mainnet (1) will be used. - If the number is a string, it must be formatted as
+
followed by digits. - If the number is an array, each element will be checked for validity.
- An optional
encodeMessage
parameter (default:true
) allows you to encode the message usingencodeURIComponent
and an internalencode
function. If set tofalse
, the message will only be encoded usingencodeURIComponent
.
npm i txms.js
yarn add txms.js
import txms from 'txms.js';
let encoded = txms.encode(hex);
let decoded = txms.decode(string);
var txms = require('txms.js').default;
var encoded = txms.encode(hex);
var decoded = txms.decode(string);
The library is designed to be compatible with both module systems, so you can choose the import style that best fits your project. Whether you’re working in a modern ES module environment or maintaining legacy CommonJS code, txms.js can be seamlessly integrated.
encode(hex: string): string
— Convert hex transaction into UTF-16BE.decode(data: string): string
— Convert UTF-16BE into hex transaction.getEndpoint(network?: number | string, countriesList?: string | Array<string>): { [key: string]: Array<string> }
— Get an object of SMS endpoints (phone numbers) per country.sms(number?: boolean | string | number | Array<string>, message?: string, network?: number | string, encodeMessage?: boolean, platform?: string): string
— Create an SMS URI based on the provided parameters.mms(number?: boolean | string | number | Array<string>, message?: string, network?: number | string, encodeMessage?: boolean, platform?: string): string
— Create an MMS URI based on the provided parameters.
hex
= hexadecimal representation of transaction without 0x prefix. (If a prefix is present, it is removed.)data
= UTF-16BE data.network
(default: 1) = ID of Core Blockchain network or its name (such as: mainnet, devin).countriesList
(default: all) = ISO 3166 Alpha-2 country/ies code/s.number
= boolean, string, number, or array of these, representing the phone number(s) for the SMS.message
= the SMS message content.encodeMessage
(default:true
) = whether to encode the message before usingencodeURIComponent
.platform
= the platform to use for the SMS URI. Currently supported:ios
,global
. Default:global
.ios
uses the&body=
, whileglobal
uses the?
for?body=
parameter.
npm i -g txms.js
txms {type} {value} {location}
- type:
encode
(e
),decode
(d
),getendpoint
(g
) - value: message; network for getendpoint
- location: ISO 3166 Alpha-2 country/ies code/s for getendpoint
echo {value} | txms {type} {location}
The aliases
and countries
objects in txms.js
are designed to be extendable, allowing you to add new networks and countries as needed.
To add a new alias for a network, you can use the addAlias
function:
import { addAlias } from 'txms.js';
// Add a new alias
addAlias('testnet', 2);
This will allow you to use testnet as an alias for the network with ID 2
.
To add new country codes and phone numbers for a specific network, use the addCountry function:
import { addCountry } from 'txms.js';
// Add new country codes and phone numbers for the testnet
addCountry(2, 'uk', ['+441234567890']);
This will associate the UK country code ('uk'
) and the phone number +441234567890
with the network ID 2
.
These utility functions make it easy to customize txms.js
to support additional networks and countries based on your needs.
Unit tests are included and can be executed with the command yarn test
or npm run test
.
GitHub automatically tests the commits into the source code.
Contributions and extensions to our test cases are welcome.
We use the Core Blockchain - Devin (testnet) wallets for tests.
We can send an SMS back with the status and stream success/failure statuses into the database.
If you need an API endpoint or want to receive an SMS back to the sender's number, please contact us.
You can use our predefined endpoints or create your own service.
To provide the best results, we check the online status of the service with the uptime checker.
Follow these steps:
- Test your service.
- Return the 200 "OK" status code at the
yoururl.tld/ping
endpoint. - Submit a Listing request.
This tool doesn't encrypt, it converts. Therefore, anyone can read your signed transaction, but don't worry as they could do this on the Blockchain anyway.
Stay safe. Do not broadcast your private key or any sensitive data you wish to safeguard.
You can deploy your own server to process the SMS/MMS messages.
DataLayer is offering open-source server processor for SMS and MMS messages.
The service is free to use, but you may incur charges from your mobile provider.
Prices may vary depending on the provider and the country.
In Slovakia, for example, the price is 0.06 EUR (worldwide) per SMS. This can be 0.12 - 0.18 EUR for a 2,3-part SMS which corresponds to one transaction.
This is placing TxMS in slight preference (2 or 3 messages), because it is more efficient than HEX (3 messages).
If you need to send a larger transaction, you can use MMS (Multimedia Messaging Service).
MMS is better suited for larger files and Blockchain transactions.
One MMS has 1600 characters. The MMS text limit is 5000 characters. MMS object has a limit of 2048 KB.
To send MMS, you can use two options:
- You can place the content as text document with extension
.txms
and send it to the same number. Each transaction can be divided with new line. You can place multipletxms
files in one MMS. - Place transaction(s) in the text message body and send it to the same number. Each transaction can be divided with new line.
MMS has about the same price as SMS (in Slovakia), but the downside is that smartphone should have enabled the MMS service and the data are stored on 3rd party server.
Warning: MMS documents are stored on the server and available to download for certain period of time.
You're welcome to contribute in any capacity.
We welcome:
- Forking this repository
- Opening a pull request
- Creating your own SMS endpoint
- Sending us some Øres / ₡ores: cb7147879011ea207df5b35a24ca6f0859dcfb145999
- Starring this repository
To contribute, please follow the steps:
- Fork the repository.
- Create a new branch.
- Make your changes.
- Commit your changes.
- Push your changes.
- Open a pull request.
Please ensure your code is well-documented and follows the project's coding standards.
Licensed under the CORE License.