umi-top-community/umi-core-php

UMI Core PHP Library by Community

1.0.8 2022-07-20 13:16 UTC

Requires

• php: >=7.1
• php-64bit: >=7.1
• ext-hash: *

Suggests

• ext-sodium: *

MIT

• UMI
• UMI Community

• umi
• umi.top

README

UMI Core - PHP Library

<br/>

Оглавление

• Введение
• Установка
  • Composer
• Примеры
  • Мнемоники
    • Seed из мнемонической фразы
  • Ключи
    • Ключ из seed
    • Подписать сообщение
    • Проверить подпись
  • Адреса
    • Адрес в формате Bech32
    • Адрес из приватного или публичного ключа
    • Префикс
  • Транзакции
    • Перевести монеты
    • Создать структуру
    • Обновить настройки структуры
    • Установить адрес для начисления профита
    • Установить адрес для перевода комиссии
    • Активировать транзитный адрес
    • Деактивировать транзитный адрес
    • Отправить транзакцию в сеть
• Лицензия

Введение

Для работы библиотеки требуются 64-битная версия PHP >= 5.4 и стандартное расширение hash.

Установка

Библиотека опубликована в репозитории Packagist и может быть установлена с помощью менеджера зависимостей Composer.

Composer

composer require umi-top-community/umi-core-php

Примеры

Мнемоники

UMI не накладывает никаких ограничений на способ генерации и хранения приватных ключей.
Для совместимости, рекомендуем использовать bip39.

Seed из мнемонической фразы

Пример с использованием библиотеки bitcoin-php:

<?php declare(strict_types=1);

include __DIR__ . '/../vendor/autoload.php';

use BitWasp\Bitcoin\Mnemonic\Bip39\Bip39SeedGenerator;
use UmiTop\UmiCore\Key\SecretKey;
use UmiTop\UmiCore\Address\Address;

$mnemonic = 'mix tooth like stock powder emerge protect index magic';

$bip39 = new Bip39SeedGenerator();
$seed = $bip39->getSeed($mnemonic)->getBinary();

$address = Address::fromKey(SecretKey::fromSeed($seed));

echo $address->getBech32(), PHP_EOL;

Ключи

В UMI применяется Ed25519 (RFC 8032) — схема подписи EdDSA использующая SHA-512 и Curve25519.

Ключ из seed

Seed может быть любой длины. Оптимальным вариантом является длина 32 байта.

<?php declare(strict_types=1);

include __DIR__ . '/../vendor/autoload.php';

use UmiTop\UmiCore\Key\SecretKey;

$seed = random_bytes(32);
$secKey = SecretKey::fromSeed($seed);
$bytes = $secKey->getBytes();

Подписать сообщение

<?php declare(strict_types=1);

include __DIR__ . '/../vendor/autoload.php';

use UmiTop\UmiCore\Key\SecretKey;

$secKey = SecretKey::fromSeed(random_bytes(32));
$message = 'Hello World';
$signature = $secKey->sign($message);

echo base64_encode($signature), PHP_EOL;

Проверить подпись

<?php declare(strict_types=1);
      
include __DIR__ . '/../vendor/autoload.php';

use UmiTop\UmiCore\Address\Address;

$address = 'umi18d4z00xwk6jz6c4r4rgz5mcdwdjny9thrh3y8f36cpy2rz6emg5s6rxnf6';
$message = 'Hello World';
$signature = base64_decode(
    'Jbi9YfwLcxiTMednl/wTvnSzsPP9mV9Bf2vvZytP87oyg1p1c9ZBkn4gNv15ZHwEFv3bVYlowgyIKmMwJLjJCw=='
);
$pubKey = Address::fromBech32($address)->getPublicKey();
$isValid = $pubKey->verifySignature($signature, $message);

var_dump($isValid);

Адреса

UMI использует адреса в формате Bech32 (bip173) длиной 62 символа. Префикс имеет длину 3 символа.
Специальным случаем являются Genesis-адреса, существующие только в Genesis-блоке, такие адреса имеют длину 65 символов и всегда имеют префикс genesis.

Адрес в формате Bech32

Создать адрес из строки Bech32 можно используя статический метод Address::fromBech32() и экспортировать с помощью Address->getBech32():

<?php declare(strict_types=1);
      
include __DIR__ . '/../vendor/autoload.php';

use UmiTop\UmiCore\Address\Address;

$bech32 = 'umi18d4z00xwk6jz6c4r4rgz5mcdwdjny9thrh3y8f36cpy2rz6emg5s6rxnf6';
$address = Address::fromBech32($bech32);

echo $address->getBech32(), PHP_EOL;

Адрес из приватного или публичного ключа

Статический метод Address::fromKey() создает адрес из приватного или публичного ключа:

<?php declare(strict_types=1);
      
include __DIR__ . '/../vendor/autoload.php';

use UmiTop\UmiCore\Address\Address;
use UmiTop\UmiCore\Key\SecretKey;
use UmiTop\UmiCore\Key\PublicKey;

$secKey = SecretKey::fromSeed(random_bytes(32));
$address1 = Address::fromKey($secKey);

echo $address1->getBech32(), PHP_EOL;

$pubKey = new PublicKey(random_bytes(32));
$address2 = Address::fromKey($pubKey);

echo $address2->getBech32(), PHP_EOL;

Префикс

По умолчанию адреса имеют префикс umi. Изменить префикс можно с помощью метода Address->setPrefix():

<?php declare(strict_types=1);
      
include __DIR__ . '/../vendor/autoload.php';

use UmiTop\UmiCore\Address\Address;

$bech32 = 'umi18d4z00xwk6jz6c4r4rgz5mcdwdjny9thrh3y8f36cpy2rz6emg5s6rxnf6';
$address = Address::fromBech32($bech32)->setPrefix('aaa');

echo $bech32, PHP_EOL;
echo $address->getBech32(), PHP_EOL;

Транзакции

Перевести монеты

Поля sender, recipient и value являются обязательными.
Сумма указывается в UMI-центах, т.е. 1.23 UMI = 123.

<?php declare(strict_types=1);

include __DIR__ . '/../vendor/autoload.php';

use UmiTop\UmiCore\Address\Address;
use UmiTop\UmiCore\Key\SecretKey;
use UmiTop\UmiCore\Transaction\Transaction;

$secKey = SecretKey::fromSeed(random_bytes(32));
$sender = Address::fromKey($secKey)->setPrefix('umi');
$recipient = Address::fromKey($secKey)->setPrefix('aaa');
$value = 42;

$trx = new Transaction();
$trx->setVersion(Transaction::BASIC)
    ->setSender($sender)
    ->setRecipient($recipient)
    ->setValue($value)
    ->sign($secKey);

echo 'txid:   ', bin2hex($trx->getHash()), PHP_EOL;
echo 'base64: ', base64_encode($trx->getBytes()), PHP_EOL;

Создать структуру

Поля sender, prefix, name, profitPercent и feePercent являются обязательными.
Префикс имеет длину 3 символа. Название указывается в кодировке UTF-8 и может иметь длину до 35 байтов. Проценты указываются в сотых долях процента, т.е. 1.23% = 123.

<?php declare(strict_types=1);

include __DIR__ . '/../vendor/autoload.php';

use UmiTop\UmiCore\Address\Address;
use UmiTop\UmiCore\Key\SecretKey;
use UmiTop\UmiCore\Transaction\Transaction;

$secKey = SecretKey::fromSeed(random_bytes(32));
$sender = Address::fromKey($secKey)->setPrefix('umi');

$trx = new Transaction();
$trx->setVersion(Transaction::CREATE_STRUCTURE)
    ->setSender($sender)
    ->setPrefix('aaa')
    ->setName('🙂')
    ->setProfitPercent(500)
    ->setFeePercent(2000)
    ->sign($secKey);

echo 'txid:   ', bin2hex($trx->getHash()), PHP_EOL;
echo 'base64: ', base64_encode($trx->getBytes()), PHP_EOL;

Обновить настройки структуры

Поля sender, prefix, name, profitPercent и feePercent являются обязательными.
Необходимо задать все поля, даже если они не изменились.

<?php declare(strict_types=1);

include __DIR__ . '/../vendor/autoload.php';

use UmiTop\UmiCore\Address\Address;
use UmiTop\UmiCore\Key\SecretKey;
use UmiTop\UmiCore\Transaction\Transaction;

$secKey = SecretKey::fromSeed(random_bytes(32));
$sender = Address::fromKey($secKey)->setPrefix('umi');

$trx = new Transaction();
$trx->setVersion(Transaction::UPDATE_STRUCTURE)
    ->setSender($sender)
    ->setPrefix('aaa')
    ->setName('🙂')
    ->setProfitPercent(500)
    ->setFeePercent(2000)
    ->sign($secKey);

echo 'txid:   ', bin2hex($trx->getHash()), PHP_EOL;
echo 'base64: ', base64_encode($trx->getBytes()), PHP_EOL;

Установить адрес для начисления профита

Поля sender и recipient являются обязательными.
Адрес для начисления профита должен принадлежать структуре.

<?php declare(strict_types=1);

include __DIR__ . '/../vendor/autoload.php';

use UmiTop\UmiCore\Address\Address;
use UmiTop\UmiCore\Key\SecretKey;
use UmiTop\UmiCore\Transaction\Transaction;

$secKey = SecretKey::fromSeed(random_bytes(32));
$sender = Address::fromKey($secKey)->setPrefix('umi');
$newPrf = Address::fromBech32('aaa18d4z00xwk6jz6c4r4rgz5mcdwdjny9thrh3y8f36cpy2rz6emg5svsuw66');

$trx = new Transaction();
$trx->setVersion(Transaction::UPDATE_PROFIT_ADDRESS)
    ->setSender($sender)
    ->setRecipient($newPrf)
    ->sign($secKey);

echo 'txid:   ', bin2hex($trx->getHash()), PHP_EOL;
echo 'base64: ', base64_encode($trx->getBytes()), PHP_EOL;

Установить адрес для перевода комиссии

Поля sender и recipient являются обязательными.
Адрес для перевода комиссии должен принадлежать структуре.

<?php declare(strict_types=1);

include __DIR__ . '/../vendor/autoload.php';

use UmiTop\UmiCore\Address\Address;
use UmiTop\UmiCore\Key\SecretKey;
use UmiTop\UmiCore\Transaction\Transaction;

$secKey = SecretKey::fromSeed(random_bytes(32));
$sender = Address::fromKey($secKey)->setPrefix('umi');
$newFee = Address::fromBech32('aaa18d4z00xwk6jz6c4r4rgz5mcdwdjny9thrh3y8f36cpy2rz6emg5svsuw66');

$trx = new Transaction();
$trx->setVersion(Transaction::UPDATE_FEE_ADDRESS)
    ->setSender($sender)
    ->setRecipient($newFee)
    ->sign($secKey);

echo 'txid:   ', bin2hex($trx->getHash()), PHP_EOL;
echo 'base64: ', base64_encode($trx->getBytes()), PHP_EOL;

Активировать транзитный адрес

Поля sender и recipient являются обязательными.
Адрес должен принадлежать структуре.

<?php declare(strict_types=1);

include __DIR__ . '/../vendor/autoload.php';

use UmiTop\UmiCore\Address\Address;
use UmiTop\UmiCore\Key\SecretKey;
use UmiTop\UmiCore\Transaction\Transaction;

$secKey = SecretKey::fromSeed(random_bytes(32));
$sender = Address::fromKey($secKey)->setPrefix('umi');
$transit = Address::fromBech32('aaa18d4z00xwk6jz6c4r4rgz5mcdwdjny9thrh3y8f36cpy2rz6emg5svsuw66');

$trx = new Transaction();
$trx->setVersion(Transaction::CREATE_TRANSIT_ADDRESS)
    ->setSender($sender)
    ->setRecipient($transit)
    ->sign($secKey);

echo 'txid:   ', bin2hex($trx->getHash()), PHP_EOL;
echo 'base64: ', base64_encode($trx->getBytes()), PHP_EOL;

Деактивировать транзитный адрес

Поля sender и recipient являются обязательными.
Адрес должен принадлежать структуре.

<?php declare(strict_types=1);

include __DIR__ . '/../vendor/autoload.php';

use UmiTop\UmiCore\Address\Address;
use UmiTop\UmiCore\Key\SecretKey;
use UmiTop\UmiCore\Transaction\Transaction;

$secKey = SecretKey::fromSeed(random_bytes(32));
$sender = Address::fromKey($secKey)->setPrefix('umi');
$transit = Address::fromBech32('aaa18d4z00xwk6jz6c4r4rgz5mcdwdjny9thrh3y8f36cpy2rz6emg5svsuw66');

$trx = new Transaction();
$trx->setVersion(Transaction::DELETE_TRANSIT_ADDRESS)
    ->setSender($sender)
    ->setRecipient($transit)
    ->sign($secKey);

echo 'txid:   ', bin2hex($trx->getHash()), PHP_EOL;
echo 'base64: ', base64_encode($trx->getBytes()), PHP_EOL;

Отправить транзакцию в сеть

Пример с использованием расширений cURL и JSON:

<?php declare(strict_types=1);

include __DIR__ . '/../vendor/autoload.php';

use UmiTop\UmiCore\Transaction\Transaction;

$trx = new Transaction();

$payload = json_encode(
    [
        'jsonrpc' => '2.0',
        'id' => '',
        'method' => 'sendTransaction',
        'params' => [
            'base64' => base64_encode($trx->getBytes())
        ]
    ]
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://testnet.umi.top/json-rpc");
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_VERBOSE, true);

$response = curl_exec($ch);

curl_close($ch);

echo $response, PHP_EOL;

Лицензия

Лицензия MIT

Copyright © 2020 UMI

Данная лицензия разрешает лицам, получившим копию данного программного
обеспечения и сопутствующей документации (в дальнейшем именуемыми
«Программное обеспечение»), безвозмездно использовать Программное обеспечение
без ограничений, включая неограниченное право на использование, копирование,
изменение, слияние, публикацию, распространение, сублицензирование и/или
продажу копий Программного обеспечения, а также лицам, которым предоставляется
данное Программное обеспечение, при соблюдении следующих условий:

Указанное выше уведомление об авторском праве и данные условия должны быть
включены во все копии или значимые части данного Программного обеспечения.

ДАННОЕ ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ», БЕЗ КАКИХ-ЛИБО
ГАРАНТИЙ, ЯВНО ВЫРАЖЕННЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ ГАРАНТИИ ТОВАРНОЙ
ПРИГОДНОСТИ, СООТВЕТСТВИЯ ПО ЕГО КОНКРЕТНОМУ НАЗНАЧЕНИЮ И ОТСУТСТВИЯ НАРУШЕНИЙ,
НО НЕ ОГРАНИЧИВАЯСЬ ИМИ. НИ В КАКОМ СЛУЧАЕ АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ
ОТВЕТСТВЕННОСТИ ПО КАКИМ-ЛИБО ИСКАМ, ЗА УЩЕРБ ИЛИ ПО ИНЫМ ТРЕБОВАНИЯМ, В ТОМ
ЧИСЛЕ, ПРИ ДЕЙСТВИИ КОНТРАКТА, ДЕЛИКТЕ ИЛИ ИНОЙ СИТУАЦИИ, ВОЗНИКШИМ ИЗ-ЗА
ИСПОЛЬЗОВАНИЯ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ ИЛИ ИНЫХ ДЕЙСТВИЙ С ПРОГРАММНЫМ
ОБЕСПЕЧЕНИЕМ.