Norito

Norito - это Iroha Канонический слой сериализации. Это формат байтов, используемый, когда сверстники, SDKs, CLI инструменты, Torii, Kura, и генерируемые артефакты должны быть согласны на точно такую же полезную нагрузку.

Использование Norito когда данные являются частью консенсуса, подписания, хэширования, настойчивости или перекрестного SDK Совместимость. JSON когда конечная точка явно предлагает человекочитаемую проекцию для операторов, панелей управления или быстрого дебгугирования.

Где появляется Norito

Поверхность .	Как Norito используется
Транзакции и запросы	Подписанные транзакции и полезные загрузки запросов, представленные через Torii, шифруются как Norito.
Бытие .	kagami genesis sign производит подписанный блок .nrt, который совпадает с загрузкой при запуске.
Torii ответы, напечатанные	Конечные точки, которые поддерживают типовые бинарные ответы используют Accept: application/x-norito.
SDKs	Rust, Python, JavaScript, Kotlin/Java, Swift, и Android клиенты используют Norito сооружения или связывания вместо ручной работы байтов.
Kura хранилище	Блоковые полезные нагрузки, боковые машины для восстановления, списки и маркеры обязательств хранятся в виде данных с рамкой Norito.
Манифесты	Nexus, доступность данных, SoraFS, трансляция и приложение-ориентированные манифесты используют Norito при подписании или хэшировании манифеста.
Поток	Norito В потоковой передаче используются манифесты Norito, заголовки сегментов, системы управления и устройства соответствия.

Norito - это не язык умных контрактов. Это детерминистический конверт и кодек, который осуществляет транзакции, контрактные звонки, манифестует и печатает полезные нагрузки API.

Модель полезной нагрузки

Каждый проводный или дискный Norito полезная нагрузка оформляется заголовком, а затем кодируемыми байтами полезной нагрузки. Загрузки без заголовка, или голые, предназначены для внутреннего хэширования, эталонов и помощников APIs которые незамедлительно завязывают результат в заголовке перед транспортировкой.

Поле заголовка	Размер .	Цель .
Магия .	4 байта	ASCII NRT0, используется для раннего отказа от данных, не относящихся к Norito.
Майор .	1 байт	Формат основной версии. текущие полезные нагрузки используют 0.
Младший	1 байт	Декодируйте подсказку для v1. Текущая стоимость - 0x00. Флаги описывают планировку.
Схема хеш	16 байтов	Идентификация типа, используемая типовыми декодерами для отказа от неожиданных полезных нагрузок.
Сжатие	1 байт	0 = None, 1 = Zstd. Неизвестные значения отвергаются.
Длина полезной нагрузки	8 байтов	Некомпрессированная длина полезной нагрузки, как минимум u64.
CRC64	8 байтов	CRC64-XZ контрольная сумма некомпрессированного полезного груза.
Флаги	1 байт	Лейтенантные флаги для компактных длин, упакованных последовательностей и упакованной строчки.

Заголовок составляет 40 байтов. Декодеры подтверждают магию, версию, поддерживаемую маску флага, длину полезной загрузки, сумму проверки и хэш схемы перед реконструкцией введенного значения.

Вкладные флаги

Norito Сохраняет варианты расположения в последнем байте заголовка. COMPACT_LEN (0x02Явные префиксы с фиксированной шириной длины остаются читаемыми, когда звонки кодируют flags = 0x00.

Флаг .	Хекс .	Статус	Влияние
PACKED_SEQ	0x01	Поддержка	Кодирует коллекции переменного размера с таблицей офорта плюс соседним блоком данных.
COMPACT_LEN	0x02	По умолчанию	Использует канонические неподписанные варианты для префиксов длины на значение.
PACKED_STRUCT	0x04	Поддержка	Кодируются производные строки в виде упакованных полевых нагрузок.
VARINT_OFFSETS	0x08	Резервировано .	Отклоняется в v1; компенсации упакованной последовательности являются фиксированной шириной u64.
COMPACT_SEQ_LEN	0x10	Резервировано .	Отклоняется в v1; заголовки высокого уровня длины последовательности являются фиксированной шириной u64.
FIELD_BITSET	0x20	Поддерживается требованиями	Добавляет набор битов для упакованных строков, так что только поля, которые требуют выраженных размеров, имеют префиксы размера. PACKED_STRUCT и COMPACT_LEN.

Флаги являются ясными. Декодеры не выводят расположение из формы полезной нагрузки, меньшей версии или эвристики. Неизвестные или недействительные комбинации отклоняются так, чтобы все коллеги интерпретировали полезную нагрузку одинаково.

Правила кодирования

Norito использует детерминистические макеты для общих форм данных, которые появляются в модели данных Iroha:

• Стриги [len][utf8-bytes]; при включении len следует за COMPACT_LEN.
• При установке COMPACT_LEN длина на значение используется компактный варинт.
• Когда COMPACT_LEN отсутствует, протяженность по значению - это 8-байтный небольшой эндиан u64.
• Заголовки длины последовательности фиксируются на 8-байтном небольшом эндианском u64 в v1.
• Vec<u8> кодируется как [len_u64][raw-bytes] вместо одной длины на байт.
• В упакованных последовательностях используются монотонные (len + 1) компенсации u64, за которыми следуют полезные нагрузки соединенных элементов.
• Карты кодируют учетные записи с фиксированными u64 и использовать детерминистический порядок ключей. HashMap записи сортируются по ключам перед кодированием; BTreeMap использует свой естественный порядок.
• BigInt использует небольшие байты пополнения двойки с длиной байта u32 и крышкой в 512 бит.
• Numeric кодируется как (mantissa, scale), где мантисса хранит целое число, а масштаб хранит количество фракционных цифр.

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

Схема Hashes

Типовые полезные нагрузки Norito содержат хэш схемы 16 байтов в заголовке. По умолчанию хэш происходит от имени полностью квалифицированного типа. Строительства, которые позволяют структурированную схему хэширования, вместо этого производят хэш из канонической схемы.

Типовые декодеры отвергают несоответствия схемы. Это защищает клиентов от случайного декодирования действительной Norito рамы как неправильного типа и является обычным режимом неисправности, когда пачка фиксации SDK выходит из модели данных узла.

Сжатие и ускорение

Norito поддерживает явное и адаптивное сжатие без изменения логической полезной нагрузки:

Особенность	Цель .
to_bytes	Зашифровка заголовка последует за некомпрессированной полезной нагрузкой.
to_compressed_bytes	Зашифровать с помощью Zstd и записать тег на сжатие в заголовок.
to_bytes_auto	Применить детерминистическую эвристику, чтобы решить, стоит ли сжатие.
Ускорение CRC64	Использует портативный CRC64-XZ везде, с CLMUL на x86_64 или PMULL на aarch64, когда это доступно.
GPU CRC64 и сжатие	Опциональные металлические или CUDA вспомогательные устройства могут ускорять большие полезные нагрузки, а затем возвращаться на пути CPU.

Ускорение аппаратного обеспечения никогда не изменяет декодированное содержание. Ускорители CRC и JSON должны совпадать с портативными выпускными битами по битам. Байты фрема Zstd могут отличаться между кодерами CPU и GPU, но декодируемая полезная нагрузка и метаданные заголовка Norito остаются определяющими для проверки.

JSON Поддержка

Norito включает в себя оригинальный набор JSON для конечных точек и инструментов, которые нуждаются в JSON без выхода из системы типа Norito.

JSON функция	Случай использования
norito::json::{to_json, from_json}	Детерминистический тип JSON кодирование/декодирование.
Красивые и писательские помощники	CLI выход, установки и интеграция потока std::io.
Значения DOM	Программная манипуляция с помощью модели значения JSON Norito.
Быстрый тип JSON	Структурная лента для декодирования/кодирования горячих DTO путей.
Читатель нулевой копии	Сканирование токенов, которое по возможности заимствует строки из ввода.
Ускорители стадии 1	Факультативное AVX2, NEON, металлическое или CUDA структурное индексирование с скалярным отказом.

Iroha код должен быть предпочтен norito::json помощники для печатания API полезные нагрузки, добавление простых serde_json к производственным путям риски, отличающиеся от схемы и поведения по обработке полевых работ, ожидаемого SDKs и Torii экстракторы.

Поддержка по производству

Rust типы данных, как правило, используют производные макрос вместо ручного кодекса. Norito двойные кодеки, схемы и JSON Помощники.

Общими атрибутами поля являются:

Атрибут	Влияние
#[norito(rename = "other")]	Использует стабильное сериализированное название для схемы и совместимости JSON.
#[norito(skip)]	Кодер исключает поле. Декодер указывает его значение Default.
#[norito(default)]	Использует Default, когда декодированная полезная нагрузка не несет поля.
#[norito(skip_serializing_if = "...")]	Выключает поля из JSON при совпадении предиката, сохранив при этом дефолты детерминистического декодирования.

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

Семьи с коробками

При создании связей Iroha или SDK из источника, функции Norito выбирают, какие помощники и ускорители доступны:

Семья особенностей	Что это делает возможным ?
derive	Реэкспортированные процессуальные макро для двойных, схемы и JSON производных.
compression	Zstd поддержка полезных нагрузок с заголовками.
packed-seq	Упакованные макеты коллекции с использованием оффсетных таблиц.
packed-struct	Запакованные производные структуры.
compact-len	Префиксы Varint на длину значения.
columnar	Norito Колонновые блоки, адаптивные кодеки строков AoS/NCB и заимствованные просмотра для сканирующих путей; включены в набор функции по умолчанию node-codec.
strict-safe	Преобразует панику в ошибочных путях в структурированные ошибки.
simd-accel	CPU ускорение, где это возможно, с детерминистическим отступлением.
json	Нативный JSON анализатор, писатель, DOM, напечатанные производные и быстрые пути.
json-std-io	Помощники читателя и писателя, слоированные на стеке JSON.
metal-stage1, cuda-stage1	Функциональные GPU JSON структурные индексы обратных источников.
metal-stage2	Необходимо классифицировать метаданные по металлу для структурной ленты JSON.
metal-crc64, cuda-crc64	Факультативные помощники GPU CRC64 для больших полезных грузов.
gpu-compression	Факультативное металлическое или CUDA Zstd ускорение для больших полезных нагрузок.
stage1-validate	Проверка дебага, которая сравнивает ускоренные структурные индексы JSON с масштабным выходом.

Доступность функций может отличаться между SDKs и профилями релиза. Формат провода остается управляемым заголовком и схемой, а не локальными флагами построения.

Torii и Norito RPC

Torii раскрывает JSON для многих маршрутов операторов, но типовые бинарные маршруты используют Norito. Тип средств массовой информации для тока типа Norito HTTP тела является application/x-norito.

Используйте эти заголовки, когда конечная точка принимает или возвращает Norito:

Content-Type: application/x-norito
Accept: application/x-norito

Когда конечная точка поддерживает оба представления, клиенты могут отправить четкий список предпочтений:

Accept: application/x-norito, application/json

Ошибки декодирования обнаружены как указано в тексте Torii Обычные причины включают в себя недействительную магию, не поддерживаемая версия, не поддерживаемый флаг функций, несовместимость сумм проверки, неправильный формат UTF-8, недействительная тег Enum, и несоответствие схемы.

Транспорт Norito RPC выбирается посредством конфигурации транспорта. панели оператора должны отслеживать задержку запроса, неисправности, активные соединения, байты ответа и torii_norito_decode_failures_total отдельно от трафика JSON.

Norito Поток

Norito Стриминг расширяет тот же детерминистический подход к средствам массовой информации и транспортным поверхностям в режиме реального времени.

Качество потоковой передачи	Цель .
Манифесты	Объявить обязательства сегмента, маршруты конфиденциальности, возможности, профиль кодека, пакет шифрования и метаданные ключевого содержания.
Заголовки сегмента	Бинд номер сегмента, продолжительность, количество частей, сроки, режим энтропии, звуковой резюме и корни Меркеля.
Частичные обязательства	Пусть зрители и релеи проверят части полезной нагрузки с манифестом перед подачей или расшифровкой.
Управляющие кадры	Проводить объявления, отзывы, ключевые обновления и переговоры о возможностях.
HPKE ключевые обновления	Переключите транспортные секреты с использованием переговорного комплекта и монотонно увеличивающихся счетчиков.
Переговоры о возможностях	Пересекает поддерживаемые биты функций, границы датаграмма, каденцию обратной связи и требования к конфиденциальности.
FEC и обратная связь	Использует детерминистические отчеты получателей и решения о паритете для траекторий потери в режиме реального времени.
Векторы соответствия	Различные языковые устройства доказывают, что SDKs расшифровывает те же манифесты, сегменты и потоки энтропии.

Специфические для потока кодеки и антропические профили отделены от основного формата транзакции/запроса Norito, но их манифесты и контрольные данные все еще используют Norito, так что маршрутизация, расчет, повторное воспроизведение и аудит доказательств остаются воспроизводимо.

Руководство по эксплуатации

• Предпочтительнее SDK конструкторы и генерируемые связывания, чем ручной работы Norito байтов.
• Обращайтесь с несовместимостью схемы как с проблемой версии или фиксации, а не как с проходящей сетью.
• Архив .nrt, .norito, и манифестирующие артефакты в выпуске или пакете происшествий, которые их создали.
• Использование Norito в качестве источника истины для подписанных, хэшированных или сохранившихся данных. JSON проекции для панелей управления и ручной проверки.
• При добавлении нового конечного пункта Torii, записывайте, принимает ли он JSON, Norito или оба, и выставьте поддерживаемые типы содержания в /openapi.
• Прежде чем включить ускоритель, выполните тесты паритета с скалярным выходом. Если ускоритель провалится, используйте детерминистический скалярный откат. Семантика полезной нагрузки должна оставаться неизменной.

Сюжетные страницы

• конечные точки Torii
• Ссылка на Бытие
• Схема модели данных
• JavaScript / TypeScript SDK
• Python SDK
• Swift и iOS SDK

Ссылки вверх

• Спецификация формата Norito
• Коробка Norito README