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

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

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

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

Строение​

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

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

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

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

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

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

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

zNS:1:REG:richard.zcash:u1…:0101…0101:1780000001

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

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

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

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

Имя​

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

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

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

Адрес, в который разрешается имя, должен быть Unified Address основной сети с приёмником Orchard. Адреса без него не принимаются.

Причина практическая, а не произвольная: регистратор принимает и выплачивает средства через ключевой материал Orchard, который согласно ZIP 229 покрывает и пул Ironwood. На адрес без приёмника Orchard нельзя заплатить, поэтому его нельзя использовать ни для возвратов, ни для выручки от продаж.

подсказка

Ironwood не добавляет нового приёмника

Ironwood — это новый пул стоимости, а не новый формат адреса. Кошельки переносят в него ноты, тогда как адрес получения остаётся адресом Orchard. Unified Address современного кошелька работает без изменений.

Nonce​

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

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

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

Цена​

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

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

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

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

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

Остаётся 296 байт, которые делят между собой имя и целевой адрес, вместе с разделителем после каждого. Даже самое длинное имя, 64 символа, оставляет адресу 232: больше, чем нужно адресу только с приёмником Orchard (106 символов), но Unified Address с несколькими приёмниками бывает длинным, поэтому при очень длинном имени очень длинный адрес может не поместиться. Клиентам стоит вычислять этот бюджет и предупреждать пользователя до оплаты, а не давать транзакции провалиться постфактум.

Оплата​

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

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

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

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

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

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

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

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

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

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):

zNS:1:REG:richard.zcash:u1mvnsq85wane…:3757ee1a…a53:1780000001

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

4. Append it to form the memo:

zNS:1:REG:richard.zcash:u1mvnsq85wane…: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.

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