Перейти к основному содержимому

Формат команд

Каждая операция PiNS — это экранированная транзакция PIVX на протокольный адрес регистратора, где сумма является платежом, а memo — подписанной командой. И то и другое едет в одной ноте, поэтому намерение и оплата связаны неразрывно: сопоставлять отдельные ссылки или счета не нужно.

Эта страница описывает точный формат передачи. Команда, построенная по нему, будет принята и регистратором, и схемой с нулевым разглашением.

Строение​

Все команды — это ASCII с разделителями-двоеточиями, начинающиеся с маркера протокола и версии:

PiNS:1:{OP}:{name}:…:{ed25519_pubkey_hex}:…:{nonce}:{signature_hex}

Поля между ними зависят от операции:

ОперацияСтруктура memoОплачиваемая сумма
REG регистрацияPiNS:1:REG:{name}:{address}:{pubkey}:{nonce}:{sig}плата за регистрацию по длине имени
UPD смена адресаPiNS:1:UPD:{name}:{address}:{pubkey}:{nonce}:{sig}плата за изменение
CHG передача правPiNS:1:CHG:{name}:{new_pubkey}:{nonce}:{sig}плата за изменение
LST выставить на продажуPiNS:1:LST:{name}:{pubkey}:{price}:{nonce}:{sig}плата за изменение
ULT снять с продажиPiNS:1:ULT:{name}:{pubkey}:{nonce}:{sig}плата за изменение
BUY покупкаPiNS:1:BUY:{name}:{address}:{pubkey}:{nonce}:{sig}ровно выставленная цена

Для CHG поле {new_pubkey} — это ключ принимающего владельца, а подпись делает передающий владелец: передачу санкционирует именно текущий владелец.

Подписываемое сообщение​

Подпись покрывает команду без завершающего :{signature} — то есть всё от маркера до nonce включительно:

PiNS:1:REG:richard.pivx:ps1f84lvgj…:0101…0101:1780000001

Правила здесь точные, и клиент, нарушивший любое из них, получит подпись, которую схема отвергнет:

  • pubkey — строчный hex, 64 символа.
  • price присутствует только у LST.
  • address присутствует только у REG, UPD и BUY.
  • price и nonce — десятичные, без ведущих нулей, без знака и без дополнения.
  • Подпись — Ed25519 по ровно этим байтам, в hex-кодировке, 128 символов.

Проверка строгая: неканонические подписи и ключи малого порядка отвергаются.

Правила полей​

Имя​

ПравилоЗначение
Символыa-z, 0-9, дефис
Длина1–64 символа вместе с зоной
Регистртолько нижний — имя хранится и хешируется в нижнем регистре
Дефисыне в начале, не в конце, никогда не подряд
Зоны.pivx, .private, .secure, .safe

Допускается ровно одна точка, отделяющая метку от зоны.

Целевой адрес​

Адрес, в который разрешается имя, должен быть экранированным платёжным адресом PIVX Sapling основной сети — bech32, человекочитаемый префикс ps, ровно 78 символов. Прозрачные и любые иные адреса не принимаются.

Длина не произвольна. Платёжный адрес Sapling — это 43 байта полезной нагрузки: 11-байтовый диверсификатор плюс 32-байтовый pk_d, что в bech32 кодируется 69 символами данных плюс 6-символьная контрольная сумма, то есть ps + разделитель + 69 + 6 = 78.

Это правило самого протокола: индексатор и схема применяют его одинаково и вдобавок требуют адрес в нижнем регистре — контрольная сумма Bech32 не учитывает регистр, так что иначе два написания одного адреса дали бы два разных листа дерева. Оно не связано с тем, как платит регистратор: возвраты и выручка от продаж никогда не идут на адрес, на который указывает имя, а зачисляются на внутренний баланс ключа Ed25519, откуда их выводит владелец ключа.

подсказка

Принимается только современная форма bech32

Старая тестовая форма ptestsapling… (88 символов) отвергается в обеих сетях, и схема требует того же, что и регистратор. Любой современный кошелёк PIVX выдаёт в основной сети форму ps….

Nonce​

Nonce — это временная метка Unix в секундах на момент подписания.

  • Он должен быть строго больше nonce, записанного для этого имени сейчас. Именно это предотвращает повторное использование старой подписанной команды.
  • Он не может опережать несущий его блок более чем на 300 секунд — этого хватает, чтобы поглотить обычное расхождение часов, но не позволяет задать nonce далеко в будущем.

Для первой регистрации подойдёт любая текущая временная метка.

Команда, nonce которой не больше записанного, отклоняется, а её платёж возвращается на ваш внутренний баланс, вывод с которого стоит 5% сервисной комиссии. Так бывает, если часы отстают, или если две команды для одного имени подписаны в пределах одной секунды. Поэтому берите большее из текущего времени и последнего nonce имени плюс одна секунда, где последний nonce — это nonce, который возвращает разрешение имени, или nonce вашей команды для этого имени, которая ещё ждёт обработки, смотря что позже.

Цена​

Цену несёт только LST. Это целое число сатоши (1 PIVX = 100 000 000 сатоши), и оно должно быть больше нуля.

Повторно выставить уже выставленное имя по новой цене можно — отправьте ещё одну команду LST. Побеждает последняя.

Ограничение размера​

Memo в PIVX занимает ровно 512 байт, и вся команда должна в них поместиться. Фиксированные части расходуют предсказуемый объём:

PiNS:1:{OP}: … marker, version, operation 11 bytes
{pubkey} 64 hex characters 65 bytes with separator
{nonce} 10 digits today 11 bytes with separator
{signature} 128 hex characters 128 bytes
{address} 78 characters 79 bytes with separator

Адрес Sapling всегда занимает ровно 78 символов, поэтому, в отличие от формата с переменной длиной, бюджет легко просчитать: на имя остаётся около 218 байт — намного больше максимума в 64 символа, который имя вообще может занять. На практике команда всегда помещается. Клиентам всё же стоит вычислять бюджет, а не полагаться на него вслепую, чтобы будущее поле никогда не переполнило memo незаметно.

Оплата​

Сумма определяет корректность не меньше, чем memo:

Длина считается по метке, без учёта зоны: ab.pivx — это имя из 2 символов.

Команда с недоплатой или переплатой не обрабатывается, как и memo, не прошедшее проверку формата или подписи. И то и другое возвращается на ваш внутренний баланс, если платёж не меньше 0.01 PIVX и memo читается хотя бы настолько: заголовок PiNS:1:, известная операция и действительный публичный ключ — для CHG существующее имя. CHG называет нового владельца, а не того, кто его подписал, поэтому возврат по нему уходит тому владельцу имени, который его подписал, а CHG, не подписанный ни одним владельцем, не возвращается. Возвраты зачисляются после 120 подтверждений, и затем их можно вывести — см. Вопросы и ответы.

Платёж с memo, в котором есть хоть один символ вне печатаемого ASCII, автоматически не возвращается, сколько бы он ни платил, как и платёж меньше 0.01 PIVX: о таких платежах сообщается команде PIVX Name — см. Вопросы и ответы.

Порядок обработки​

Команды обрабатываются в том порядке, в котором их создал PIVX: по высоте блока, затем по индексу транзакции внутри блока. Регистратор не выбирает порядок и не может его переставить так, чтобы каждый независимый индексатор не вычислил при этом другой корень.

Транзакция несёт одну команду: первый из её выходов на адрес регистратора, по индексу выхода, чьё memo — правильно составленная команда. Остальные выходы на адрес регистратора в той же транзакции не обрабатываются и автоматически не возвращаются, поэтому отправляйте каждую команду отдельной транзакцией.

Для конкурирующих операций — двух REG на одно имя или двух BUY по одному объявлению — побеждает первая в этом порядке, а остальным средства возвращаются на внутренний баланс.

Разобранный пример​

Регистрация richard.pivx:

1. Generate an Ed25519 keypair. The public key is your identity across all your names.

2. Build the message to sign (note: no trailing signature field):

PiNS:1:REG:richard.pivx:ps1f84lvgj0awz…:3757ee1a…a53:1780000001

3. Sign it with the private key; hex-encode the 64-byte signature.

4. Append it to form the memo:

PiNS:1:REG:richard.pivx:ps1f84lvgj0awz…:3757ee1a…a53:1780000001:cfec7a58…04

5. Send a shielded transaction to the registrar address, with that memo, paying the
registration fee for a 7-character name.

Когда платёж наберёт 40 подтверждений — это около 40 минут, — команда попадает в следующий пакет, который закрывается примерно через десять минут, а затем доказывается и закрепляется в блокчейне. С этого момента richard.pivx разрешается через любой индексатор, причём с доказательством Меркла, которое вы можете проверить сами.