UMI Core - JavaScript Library
Оглавление
Введение
Библиотека написана на TypeScript и
скомпилирована в модули CommonJS и ES Module. Работает
во всех актуальных браузерах и Node.js.
Для совместимости с устаревшими браузерами скомпилирована iife версия,
поддерживается Internet Explorer 5 и выше.
Установка
Библиотека опубликована в репозитории npm и может быть установлена с помощью пакетного менеджера, например, npm или Yarn:
npm
npm install @umi-top/umi-core-jsyarn
yarn add @umi-top/umi-core-jsОтдельным файлом
Если требуется, библиотеку можно скачать в виде отдельного файла:
CommonJS: index.js,
ES Module: index.mjs
или IIFE index.min.js.
Также можно скачать аннотации типов для
TypeScript: index.d.ts
и Flow: index.js.flow.
Подключение
CommonJS
Если вы используете Node.js:
const umi = require('@umi-top/umi-core-js')ES Modules
Если вы используете webpack, Rollup, Parcel или Node.js (>= v13).
Для более эффективной работы алгоритма tree shaking рекомендуем импортировать только используемые значения:
import { Address, PublicKey, SecretKey, Transaction } from '@umi-top/umi-core-js'Импортировать все содержимое модуля. Этот вариант будет использоваться в примерах ниже.
import * as umi from '@umi-top/umi-core-js'CDN
Библиотеку можно использовать напрямую в браузере.
Если требуется максимальная совместимость, можно использовать IIFE вариант:
<script src="https://unpkg.com/@umi-top/umi-core-js"></script>В современных браузерах можно импортировать es6 модуль:
<script type="module">
import * as umi from 'https://unpkg.com/@umi-top/umi-core-js/lib/index.mjs'
</script>Примеры
Мнемоники
UMI не накладывает никаких ограничений на способ генерации и хранения приватных
ключей.
Для совместимости рекомендуем использовать
bip39.
Seed из мнемонической фразы
Пример с использованием библиотеки bip39:
// npm install bip39
const bip39 = require('bip39')
const mnemonic = bip39.generateMnemonic(256)
const seed = bip39.mnemonicToSeedSync(mnemonic)Ключи
В UMI применяется Ed25519 (RFC 8032) — схема подписи EdDSA, использующая SHA-512 и Curve25519.
Ключ из seed
Seed может быть любой длины. Оптимальным вариантом является длина 32 байта.
const seed = new Uint8Array(32)
const secretKey = umi.SecretKey.fromSeed(seed)
const publicKey = secretKey.getPublicKey()Подписать сообщение
В метод SecretKey#sign() необходимо передать массив байтов, поэтому если
требуется подписать текстовое сообщение, его нужно преобразовать:
const message = umi.textEncode('Hello World')
const signature = secretKey.sign(message)
console.log(umi.base64Encode(signature))Проверить подпись
Метод PublicKey#verifySignature() принимает массив байтов, поэтому если
подпись передается в виде текста, ее необходимо декодировать:
const address = 'umi18d4z00xwk6jz6c4r4rgz5mcdwdjny9thrh3y8f36cpy2rz6emg5s6rxnf6'
const message = umi.textEncode('Hello World')
const signature = umi.base64Decode(
'Jbi9YfwLcxiTMednl/wTvnSzsPP9mV9Bf2vvZytP87oyg1p1c9ZBkn4gNv15ZHwEFv3bVYlowgyIKmMwJLjJCw=='
)
const pubKey = umi.Address.fromBech32(address).getPublicKey()
const isValid = pubKey.verifySignature(signature, message)
console.log(isValid ? 'true' : 'false')Адреса
UMI использует адреса в формате Bech32
(bip173)
длиной 62 символа. Префикс имеет длину 3 символа.
Специальным случаем являются Genesis-адреса, существующие только
в Genesis-блоке, такие адреса имеют длину 65 символов
и всегда имеют префикс genesis.
Адрес в формате Bech32
Создать адрес из строки Bech32 можно, используя статический метод Address.fromBech32(),
и экспортировать с помощью Address#getBech32():
const bech32 = 'umi18d4z00xwk6jz6c4r4rgz5mcdwdjny9thrh3y8f36cpy2rz6emg5s6rxnf6'
const address = umi.Address.fromBech32(bech32)
console.log(address.getBech32())Адрес из приватного или публичного ключа
Статический метод Address.fromKey() создает адрес из приватного
или публичного ключа:
const seed = new Uint8Array(32)
const secKey = umi.SecretKey.fromSeed(seed)
const pubKey = secKey.getPublicKey()
const address1 = umi.Address.fromKey(secKey)
const address2 = umi.Address.fromKey(pubKey)
console.log(address1.getBech32(), address2.getBech32())Префикс
По умолчанию адреса имеют префикс umi.
Изменить префикс можно с помощью метода Address#setPrefix():
const bech32 = 'umi18d4z00xwk6jz6c4r4rgz5mcdwdjny9thrh3y8f36cpy2rz6emg5s6rxnf6'
const address = umi.Address.fromBech32(bech32).setPrefix('aaa')
console.log(address.getBech32())Транзакции
Перевести монеты
Поля sender, recipient и value являются обязательными.
Сумма указывается в UMI-центах, т.е. 1.23 UMI = 123.
const secKey = umi.SecretKey.fromSeed(new Uint8Array(32))
const sender = umi.Address.fromKey(secKey).setPrefix('umi')
const recipient = umi.Address.fromKey(secKey).setPrefix('aaa')
const tx = new umi.Transaction()
.setVersion(umi.Transaction.Basic)
.setSender(sender)
.setRecipient(recipient)
.setValue(42)
.sign(secKey)
console.log('txid: ', umi.hexEncode(tx.getHash()))
console.log('base64: ', umi.base64Encode(tx.getBytes()))Создать структуру
Поля sender, prefix, name, profitPercent и feePercent являются
обязательными.
Префикс имеет длину 3 символа. Название указывается в кодировке UTF-8 и может
иметь длину до 35 байтов. Проценты указываются в сотых долях процента,
т.е. 1.23% = 123.
const secKey = umi.SecretKey.fromSeed(new Uint8Array(32))
const sender = umi.Address.fromKey(secKey).setPrefix('umi')
const tx = new umi.Transaction()
.setVersion(umi.Transaction.CreateStructure)
.setSender(sender)
.setPrefix('aaa')
.setName('🙂')
.setProfitPercent(500)
.setFeePercent(2000)
.sign(secKey)
console.log('txid: ', umi.hexEncode(tx.getHash()))
console.log('base64: ', umi.base64Encode(tx.getBytes()))Обновить настройки структуры
Поля sender, prefix, name, profitPercent и feePercent являются
обязательными.
Необходимо задать все поля, даже если они не изменились.
const secKey = umi.SecretKey.fromSeed(new Uint8Array(32))
const sender = umi.Address.fromKey(secKey).setPrefix('umi')
const tx = new umi.Transaction()
.setVersion(umi.Transaction.UpdateStructure)
.setSender(sender)
.setPrefix('aaa')
.setName('🙂')
.setProfitPercent(500)
.setFeePercent(2000)
.sign(secKey)
console.log('txid: ', umi.hexEncode(tx.getHash()))
console.log('base64: ', umi.base64Encode(tx.getBytes()))Установить адрес для начисления профита
Поля sender и recipient являются обязательными.
Адрес для начисления профита должен принадлежать структуре.
const secKey = umi.SecretKey.fromSeed(new Uint8Array(32))
const sender = umi.Address.fromKey(secKey).setPrefix('umi')
const newPrf = umi.Address.fromBech32('aaa18d4z00xwk6jz6c4r4rgz5mcdwdjny9thrh3y8f36cpy2rz6emg5svsuw66')
const tx = new umi.Transaction()
.setVersion(umi.Transaction.UpdateProfitAddress)
.setSender(sender)
.setRecipient(newPrf)
.sign(secKey)
console.log('txid: ', umi.hexEncode(tx.getHash()))
console.log('base64: ', umi.base64Encode(tx.getBytes()))Установить адрес для перевода комиссии
Поля sender и recipient являются обязательными.
Адрес для перевода комиссии должен принадлежать структуре.
const secKey = umi.SecretKey.fromSeed(new Uint8Array(32))
const sender = umi.Address.fromKey(secKey).setPrefix('umi')
const newFee = umi.Address.fromBech32('aaa18d4z00xwk6jz6c4r4rgz5mcdwdjny9thrh3y8f36cpy2rz6emg5svsuw66')
const tx = new umi.Transaction()
.setVersion(umi.Transaction.UpdateFeeAddress)
.setSender(sender)
.setRecipient(newFee)
.sign(secKey)
console.log('txid: ', umi.hexEncode(tx.getHash()))
console.log('base64: ', umi.base64Encode(tx.getBytes()))Активировать транзитный адрес
Поля sender и recipient являются обязательными.
Адрес должен принадлежать структуре.
const secKey = umi.SecretKey.fromSeed(new Uint8Array(32))
const sender = umi.Address.fromKey(secKey).setPrefix('umi')
const transit = umi.Address.fromBech32('aaa18d4z00xwk6jz6c4r4rgz5mcdwdjny9thrh3y8f36cpy2rz6emg5svsuw66')
const tx = new umi.Transaction()
.setVersion(umi.Transaction.CreateTransitAddress)
.setSender(sender)
.setRecipient(transit)
.sign(secKey)
console.log('txid: ', umi.hexEncode(tx.getHash()))
console.log('base64: ', umi.base64Encode(tx.getBytes()))Деактивировать транзитный адрес
Поля sender и recipient являются обязательными.
Адрес должен принадлежать структуре.
const secKey = umi.SecretKey.fromSeed(new Uint8Array(32))
const sender = umi.Address.fromKey(secKey).setPrefix('umi')
const transit = umi.Address.fromBech32('aaa18d4z00xwk6jz6c4r4rgz5mcdwdjny9thrh3y8f36cpy2rz6emg5svsuw66')
const tx = new umi.Transaction()
.setVersion(umi.Transaction.DeleteTransitAddress)
.setSender(sender)
.setRecipient(transit)
.sign(secKey)
console.log('txid: ', umi.hexEncode(tx.getHash()))
console.log('base64: ', umi.base64Encode(tx.getBytes()))Отправить транзакцию в сеть
Пример для браузера с использованием Fetch API (polyfill):
const tx = new umi.Transaction()
fetch('https://testnet.umi.top/json-rpc', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
jsonrpc: '2.0',
id: '',
method: 'sendTransaction',
params: {
base64: umi.base64Encode(tx.getBytes())
}
})
}).then(function(response) {
console.log(response.status, response.statusText)
return response.json()
}).then(function(json) {
console.log('parsed json', json)
}).catch(function(ex) {
console.log('parsing failed', ex)
})Пример для Node.js с использованием модуля https:
const umi = require('@umi-top/umi-core-js')
const https = require('https')
const tx = new umi.Transaction()
const data = JSON.stringify({
jsonrpc: '2.0',
id: '',
method: 'sendTransaction',
params: {
base64: Buffer.from(tx.getBytes()).toString('base64')
}
})
const options = {
hostname: 'testnet.umi.top',
port: 443,
path: '/json-rpc',
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Content-Length': data.length
}
}
const req = https.request(options, (res) => {
console.log(`statusCode: ${res.statusCode}`)
res.on('data', (d) => {
process.stdout.write(d)
})
})
req.on('error', (error) => {
console.error(error)
})
req.write(data)
req.end()Лицензия
Лицензия MIT
Copyright © 2020 UMI
Данная лицензия разрешает лицам, получившим копию данного программного
обеспечения и сопутствующей документации (в дальнейшем именуемыми
«Программное обеспечение»), безвозмездно использовать Программное обеспечение
без ограничений, включая неограниченное право на использование, копирование,
изменение, слияние, публикацию, распространение, сублицензирование и/или
продажу копий Программного обеспечения, а также лицам, которым предоставляется
данное Программное обеспечение, при соблюдении следующих условий:
Указанное выше уведомление об авторском праве и данные условия должны быть
включены во все копии или значимые части данного Программного обеспечения.
ДАННОЕ ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ», БЕЗ КАКИХ-ЛИБО
ГАРАНТИЙ, ЯВНО ВЫРАЖЕННЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ ГАРАНТИИ ТОВАРНОЙ
ПРИГОДНОСТИ, СООТВЕТСТВИЯ ПО ЕГО КОНКРЕТНОМУ НАЗНАЧЕНИЮ И ОТСУТСТВИЯ НАРУШЕНИЙ,
НО НЕ ОГРАНИЧИВАЯСЬ ИМИ. НИ В КАКОМ СЛУЧАЕ АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ
ОТВЕТСТВЕННОСТИ ПО КАКИМ-ЛИБО ИСКАМ, ЗА УЩЕРБ ИЛИ ПО ИНЫМ ТРЕБОВАНИЯМ, В ТОМ
ЧИСЛЕ, ПРИ ДЕЙСТВИИ КОНТРАКТА, ДЕЛИКТЕ ИЛИ ИНОЙ СИТУАЦИИ, ВОЗНИКШИМ ИЗ-ЗА
ИСПОЛЬЗОВАНИЯ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ ИЛИ ИНЫХ ДЕЙСТВИЙ С ПРОГРАММНЫМ
ОБЕСПЕЧЕНИЕМ.