Torii Окончательные точки
Torii Это HTTP, SSE, и WebSocket шлюз для Iroha 3. Он служит как для учетной записи APIs и конечных пунктов оператора.
Действующие правила протокола:
- канонический бинарный формат - Norito
- Многие конечные точки также поддерживают JSON, когда вы отправляете
Accept: application/json - показатели выставлены в формате Prometheus
Для получения подробностей о формате, обсуждении контента, флагах макетов, хэшах схемы и руководства Norito RPC см. ссылку Norito.
Общие цели
| Окончательный момент | Формат | Цель |
|---|---|---|
POST /transaction | Norito | Представьте подписанную транзакцию |
POST /query | Norito | Отправить подписанный запрос |
GET /events | WebSocket | Подпишитесь на потоки событий |
GET /block/stream | WebSocket | Поток обязательных блоков |
GET /peers | JSON | Список сверстников, раскрытых Torii |
GET /health | JSON | Конечная точка легкой жизненности |
GET /api_version | JSON | По умолчанию API версия |
GET /status | JSON | Резюме о статусе операторов на высоком уровне |
GET /metrics | Прометей | Прометейский крап-концовый пункт |
GET /schema | JSON | Снимок схемы модели данных , выполненный узлом |
GET /openapi или GET /openapi.json | JSON | OpenAPI документ для активного Torii HTTP маршруты |
GET /v1/parameters | JSON | Снимок параметров узла |
GET /v1/node/capabilities | JSON | Способность узлов и метаданные модели данных |
GET /v1/api/versions | JSON | Поддерживаемые версии Torii API |
GET /v1/events/sse | SSE | Поток событий для долгоживущих клиентов |
GET /v1/time/now | JSON | Снимок узлового стенового часа |
GET /v1/time/status | JSON | Состояние синхронизации времени |
/openapi является авторитетным списком конечных точек для ведущего узла. создать функции и конфигурацию времени запуска, поэтому генерируемые клиенты должны предпочитать живое OpenAPI Документ по списку маршрутов, скопированный вручную. Torii API консоль чтобы загрузить этот живой документ, тестировать JSON маршруты, копия curl запросы, и генерировать клиентский код из текущей схемы.
Попробуйте просмотреть маршруты Taira
Общая Taira тестовая сеть раскрывает ту же поверхность Torii JSON, которую клиенты приложений используют для изучения только на чтении. Эти команды не требуют ключей:
TAIRA_ROOT=https://taira.sora.org
curl -fsS "$TAIRA_ROOT/status" \
| jq '{blocks, txs_approved, txs_rejected, queue_size, peers}'
curl -fsS "$TAIRA_ROOT/openapi.json" \
| jq -r '.paths | keys[]' \
| grep '^/v1/' \
| head -n 20
curl -fsS "$TAIRA_ROOT/v1/node/capabilities" \
| jq '{abi_version, data_model_version, query: .query.aggregate.supported_resources}'Попробуйте ресурс читает против нынешнего состояния мира:
curl -fsS "$TAIRA_ROOT/v1/domains?limit=5" \
| jq -r '.items[].id'
curl -fsS "$TAIRA_ROOT/v1/assets/definitions?limit=5" \
| jq -r '.items[] | [.id, .name, .total_quantity] | @tsv'Если маршрут публичной тестируемой сети возвращает 502, выходит из строя или сообщает о насыщенной очереди, обращайтесь с ним как с проблемой доступности конечных точек и попробуйте вновь позже, прежде чем дебгурировать свой клиентский код.
Консенсус и конечные точки загрузки
| Окончательный момент | Формат | Цель |
|---|---|---|
GET /v1/sumeragi/commit-certificates | JSON | Последние резюме сертификатов обязательств |
GET /v1/sumeragi/validator-sets | JSON | Валидатор устанавливает историю |
GET /v1/sumeragi/validator-sets/{height} | JSON | Валидатор установлен на высоте блока |
GET /v1/sumeragi/status | Norito или JSON | Подробный снимок состояния консенсуса |
GET /v1/sumeragi/status/sse | SSE | Постоянный поток консенсуса о состоянии |
GET /v1/sumeragi/leader | JSON | Современная информация о лидерах |
GET /v1/sumeragi/qc | Norito или JSON | Последнее резюме кворум-сертификата |
GET /v1/sumeragi/checkpoints | JSON | Резюме консенсусных контрольных пунктов |
GET /v1/sumeragi/consensus-keys | JSON | Активные ключи консенсуса |
GET /v1/sumeragi/bls_keys | JSON | Активные BLS ключи консенсуса |
GET /v1/sumeragi/phases | JSON | Последнее образец задержки на фазу |
GET /v1/sumeragi/rbc | JSON | RBC сеансы и показатели пропускной способности |
GET /v1/sumeragi/rbc/sessions | JSON | Активный снимок сессии RBC |
GET /v1/sumeragi/pacemaker | JSON | Статус кардиоразвивателя |
GET /v1/sumeragi/params | JSON | Параметры текущего действия в цепочке Sumeragi |
GET /v1/sumeragi/collectors | JSON | Краткий снимок детерминистического коллекционного плана |
GET /v1/sumeragi/key-lifecycle | JSON | Состояние жизненного цикла ключевого консенсуса |
GET /v1/sumeragi/telemetry | JSON | Телеметрический снимок консенсуса |
GET /v1/sumeragi/evidence | JSON | Записи доказательств, дополнительно фильтрованные по строке запросов |
GET /v1/sumeragi/evidence/count | JSON | Количество доказательств . |
POST /v1/sumeragi/evidence/submit | JSON | Представьте доказательства консенсуса |
GET /v1/sumeragi/commit_qc/{hash} | Norito или JSON | Завершить запись QC для хэширования блока |
GET /v1/runtime/abi/active | JSON | Описатель активного времени выполнения ABI |
GET /v1/runtime/abi/hash | JSON | Активный ход времени ABI хэш |
GET /v1/runtime/metrics | JSON | Снимок показателей времени запуска |
GET /v1/runtime/upgrades | JSON | Список обновлений запускного времени |
POST /v1/runtime/upgrades/propose | JSON | Предложим обновление рабочего времени . |
POST /v1/runtime/upgrades/activate/{id} | JSON | Активировать предложенную модернизацию рабочего времени |
POST /v1/runtime/upgrades/cancel/{id} | JSON | Отменить предлагаемое обновление рабочего времени |
Семейства маршрута App и SORA
Когда Torii построен с набором функций, ориентированных на приложение, он раскрывает дополнительные семейства JSON для исследователей, услуги SORA, мостовые потоки, доказательства и хранилище.
| Семейство маршрутов | Цель |
|---|---|
/v1/accounts/*, /v1/domains/*, /v1/assets/* | JSON чтения, помощники по запросу, помощники для включения в систему и просмотр портфеля или владельца |
/v1/nfts/*, /v1/rwas/*, /v1/confidential/* | NFT, активы в реальном мире и конфиденциальные виды активов |
/v1/aliases/*, /v1/assets/aliases/*, /v1/sns/*, /v1/identifiers/* | Название, псевдонимы и разрешение идентификатора |
/v1/explorer/* | Ориентированные на эксплуатант учетная запись, активы, блоки, транзакции, инструкции, показатели и потоки |
/v1/transactions/*, /v1/pipeline/*, /v1/iso20022/* | История транзакций, восстановление или состояние трубопровода, а также ISO 20022 помощников |
/v1/contracts/* | Контрактный код, развертывание, объединение, вызов, просмотр, событие, деятельность, сборка и маршруты состояния |
/v1/multisig/*, /v1/controls/* | Многозначные предложения, одобрения и помощники по контролю переводов |
/v1/bridge/*, /v1/ledger/*, /v1/proofs/* | Окончательность, доказательство состояния, доказательство блокировки, сохранение доказательств и маршруты запроса доказательства |
/v1/da/* | Доступность данных, манифесты, политики доказательства, обязательства и конкретные намерения |
/v1/zk/* | ZK корни, проверка доказательств, проверка IVM, подсчет голосов, ключи от проверки, записи доказательств и приложения |
/v1/gov/*, /v1/ministry/* | Предложения по управлению, бюллетени голосования, состояние совета, защищенные пространства имен, предложения по повестке дня, принятие закона и завершение |
/v1/nexus/*, /v1/sccp/* | Nexus полоса, пространство данных, и перекрестная цепочка доказательства помощников |
/v1/musubi/* | Musubi чтение реестра пакетов и конструкторы инструкций |
/v1/subscriptions/* | Планы подписки, жизненный цикл подписки, использование и оплата помощников |
/v1/sorafs/*, /sorafs/*, /.well-known/sorafs/* | SoraFS обнаружение поставщиков, проверка мощности, закладка, сбор хранилищ и предоставление общественного контента |
/v1/soracloud/*, /v1/soradns/*, /soradns/*, /api/* | SoraCloud жизненный цикл услуг, частные вычислительные/модельные потоки, публичное открытие и хостинг приложений |
/v1/connect/*, /v1/vpn/* | Iroha Соединение сессий, транспорт WebSocket, сессии VPN, профили и расписки |
/v1/app-api/*, /v1/api/*, /v1/content/* | Приложения API связывания и пакеты/CID поддерживаемый маршрутизатор контента |
/v1/operator/*, /v1/mcp | Аутентификация оператора и родный мост MCP JSON-RPC |
/v1/offline/*, /v1/repo/*, /v1/space-directory/*, /v1/ram-lfe/* | Готовность онлайн, соглашения о хранилищах данных, манифесты пространства данных и помощники RAM-LFE |
/v1/kaigi/*, /v1/webhooks/*, /v1/notify/*, /v1/telemetry/* | Сотрудничество, веб-связь, оповещение с толчком и интеграция телеметрии в реальном времени |
ISO 20022 Мост
Torii раскрывает мост ISO 20022 под /v1/iso20022/* при включении приложения-направления API и время работы моста. это не общецелевой шлюз к клирингу ISO 20022 года, а поддерживаемый подмножество для преобразования выбранных платежных сообщений в подписанные переводы Iroha и для отслеживания их состояния в регистре.
Torii ISO 20022 Конечные точки
| Метод и конечный пункт | Цель |
|---|---|
POST /v1/iso20022/pacs008 | Передача кредита FI к FI клиенту и составление соответствующего перечисления активов Iroha |
POST /v1/iso20022/pacs009 | Предоставление кредитной передачи FI к FI , используемой для финансирования PvP или денежных средств, связанных с ценными бумагами |
POST /v1/iso20022/pacs002 | Представьте отчет о состоянии платежей |
POST /v1/iso20022/pacs004 | Представьте декларацию о платеже |
POST /v1/iso20022/camt056 | Подача заявки на отмену платежа |
POST /v1/iso20022/sese023 | Подача инструкции по расчету ценных бумаг |
POST /v1/iso20022/sese024 | Отправить сообщение о состоянии расчета ценных бумаг |
POST /v1/iso20022/sese025 | Представление подтверждения расчетов по ценным бумагам |
POST /v1/iso20022/colr012 | Отправить сообщение о замене гарантий |
GET /v1/iso20022/messages/{msg_id} | Прочтите запись канонического моста для одного сообщения . |
GET /v1/iso20022/audit/messages | Прочитайте манифест проверки сообщений с подделом . |
GET /v1/iso20022/messages/{msg_id}/pacs002 | Отдать текущий платежный статус как pacs.002 XML |
GET /v1/iso20022/messages/{msg_id}/pacs004 | Внести заявление о текущем платеже как pacs.004 XML |
GET /v1/iso20022/messages/{msg_id}/camt029 | Отдать текущую резолюцию отмены как camt.029 XML |
GET /v1/iso20022/messages/{msg_id}/sese024 | Внести текущий статус расчетов в sese.024 XML |
GET /v1/iso20022/messages/{msg_id}/sese025 | Внести текущее подтверждение расчетов как sese.025 XML |
В заявлении pacs.008 должно быть указано сообщение ID, сумма межбанковского расчетов, валюта, дата расчета, должник и кредитор IBANs, а также должник или кредитор BICs. При настройке справочных данных мост также проверяет переходы валют BIC, IBAN и ISO 4217, прежде чем генерируемая операция входит в трубопровод.
В заявлении pacs.009 должны содержаться бизнес-сообщение ID, определение сообщения ID, время создания, сумма межбанковского расчета, валюта, дата расчета; инструктирующий агент BICs, должник и кредитор IBANs. Если сообщение включает в себя Purp, мост в настоящее время принимает финансирование только для целей ценных бумаг: Purp=SECU.
Конечные точки подачи pacs.008 и pacs.009 принимают конверты XML ISO или формат плоского поля, используемый при испытаниях моста. Факультативные поля SplmtryData могут закрепить целевую книгу Iroha источник и целевой счет IDs или адреса, а также определение актива ID. Ответ 202 Accepted с message_id, transaction_hash, status, pacs002_code и решенной учетной книгой/счетом/активом контекстом.
Дополнительная поддержка анализа и картографирования
В настоящее время IVM ISO Helper также подтверждает и материализует следующие сообщения для семьи конверта подтверждение, картографирование расчетов или дальнейшее согласование. Torii Маршруты.
| Семья сообщений | Текущая поддержка |
|---|---|
head.001 | Подтверждение заголовка бизнес-заявки для ISO конверты, в том числе: BizMsgIdr, MsgDefIdr, время создания и опциональный отправитель/получатель BIC поля |
pacs.007, pacs.028, pacs.029 | Отмена платежей, запрос на статус и разрешение/анализ статуса расследования |
pain.001, pain.002 | Начало оплаты заказчиком и подтверждение отчета о состоянии платежа |
camt.052, camt.053, camt.054 | Отчет о счете, заявление и подтверждение уведомления |
Kaigi Заседания
Kaigi предоставляет платные аудио/видео комнаты в режиме реального времени на SORA Nexus. Используйте его, когда приложение нуждается в создании сеансов с учетной записью, изменениях списка, манифестациях реле, шифрованной сигнализации и измерении использования вместо того, чтобы держать все состояние конференций вне цепочки.
Животный цикл, ориентированный на бухгалтерский учет, составляет:
CreateKaigi: создать вызов под доменом и хранить его политику, график, метаданные и дополнительный релейный манифест.JoinKaigiиLeaveKaigi: обновление списка вызовов. В частном режиме участники используют обязательства, аннулирующие факты и доказательства списка вместо того, чтобы непосредственно раскрывать счет участника IDs.RecordKaigiUsage: дополнить измеренным длительностью и объемом газа.EndKaigi: закрыть сессию и записать окончательную часовую печать.
Torii выявляет телеметрию эстафеты в /v1/kaigi/relays, /v1/kaigi/relays/{relay_id}, /v1/kaigi/relays/health, и /v1/kaigi/relays/events когда приложение API Состояние сеанса отражается в виде Kaigi Доменные события, такие как KaigiRosterSummary, KaigiRelayManifestUpdated, KaigiRelayHealthUpdated, и KaigiUsageSummary.
CLI Тестирование дыма
Начните с iroha kaigi CLI, когда вы хотите проверить, что конечная точка Torii принимает транзакции Kaigi до подключения UI. Команда быстрого запуска создает временную комнату против активного конечного пункта Torii и печатает резюме с идентификатором звонка, командой "соединяйтесь" и намеком на spool SoraNet:
iroha kaigi quickstart --auto-join-host --summary-out kaigi-summary.jsonДля сценарийных потоков, управляйте жизненным циклом комнаты явно:
iroha kaigi create \
--domain streaming \
--call-name daily \
--host <i105-account-id> \
--privacy-mode transparent \
--room-policy authenticated
iroha kaigi join --domain streaming --call-name daily --participant <i105-account-id>
iroha kaigi leave --domain streaming --call-name daily --participant <i105-account-id>
iroha kaigi record-usage \
--domain streaming \
--call-name daily \
--duration-ms 120000 \
--billed-gas 1500
iroha kaigi end --domain streaming --call-name dailyИспользование --room-policy public для помещений, которые могут быть подвергнуты воздействию без просмотров билетов; или --room-policy authenticated когда выходы должны требовать аутентификации зрителя. --privacy-mode zk-roster-v1 только после того, как сеть имеет Kaigi конфигурированные ключи для проверки списка и использования; в противном случае соединения, листы, и частные записи использования не выполняются во время детерминистической проверки.
Испытания с помощью демонстрации JavaScript
Используйте настольную демо soramitsu/iroha-demo-javascript для тестирования конечного конечного портфеля. Демо - это приложение Electron and Vue, которое разговаривает напрямую с Torii через локальное связывание @iroha/iroha-js и включает в себя маршрут /kaigi для браузерных носителей один к одному.
Используйте демо с @iroha/iroha-js от Iroha Источник хранилища. демо-пины SDK через file:../iroha/javascript/iroha_js, Так что держите оба касса в этом сестреном расположении:
mkdir iroha-wallet-workspace
cd iroha-wallet-workspace
git clone https://github.com/hyperledger-iroha/iroha.git
git clone https://github.com/soramitsu/iroha-demo-javascript.git
cd iroha/javascript/iroha_js
npm install
npm run build:native
npm run build:dist
cd ../../../iroha-demo-javascript
npm install
npm run devИспользуйте Node.js 20 или новейший и цепочку инструментов Rust, чтобы нативный модуль iroha_js_host мог создавать. Возобновить SDK в братец Iroha кассу после изменения его источника; чистый упаковка не содержит рабочее пространство Cargo, необходимое для npm run build:native.
Для контролируемого испытания укажите демонстрацию на конечную точку Kaigi-способной Torii:
Запустить узел Iroha с включенным приложением SORA/Kaigi, обращающимся к приложению APIs или использовать общедоступную конечную точку, которая раскрывает необходимые поверхности Kaigi.
Проверяйте базовую доступность с помощью
/health, а затем проверьте поверхность прямого маршрута с помощью/openapiили/openapi.json. Некоторые развертывания также раскрывают/v1/health, но/health- это портативная проверка жизненности.Для TAIRA проверьте маршруты телеметрии эстафеты, прежде чем попробовать живую встречу:
bashTAIRA=https://taira.sora.org curl -fsS "$TAIRA/health" curl -fsS "$TAIRA/v1/kaigi/relays" curl -fsS "$TAIRA/v1/kaigi/relays/health"
Эти проверки доказывают, что телеметрия эстафеты Torii и Kaigi доступна. Они не создают встречи; CreateKaigi и JoinKaigi все еще нуждаются в финансируемых кошельках и подписанном представлении транзакций. 4. Откройте демо, перейдите к Настройкам, нажмите Torii URL и позвольте приложению загрузить цепочку ID и сетевой префикс с конечной точки. 5. Создать или восстановить два локальных кошелька в демо. Используйте отдельные окна приложений, профили или машины, чтобы хост и гость имели отдельное состояние кошелька.
Для испытания Kaigi UI:
- В окне хоста откройте Kaigi, выберите Начало встречи, нажмите заголовок и выберите частное приглашение или прозрачное приглашение.
- Выберите включить камеру и микрофон, так что WebRTC имеет местные средства массовой информации.
- Выберите ссылку на встречу. Живой кошелек отправляет
CreateKaigi; затем в приложении отображается приглашениеiroha://kaigi/join?call=...&secret=...и обратный маршрут#/kaigi?.... - Оставьте окно хозяина открытым и делитесь приглашением с гостем.
- В окне гостей открыть приглашение или вставить его в встречу Join, включить местные средства массовой информации и выбрать Meeting Join. Живый кошелек получает зашифрованное предложение хоста из Torii и отправляет
JoinKaigiс зашифренными метаданными ответа. - Ведущий должен автоматически подать первый ответ путем трансляции или опроса Kaigi сигналов звонка. В обоих окнах должны отображаться подключенные средства связи и обновленные данные соединения.
- Завершить сессию с хоста или использовать команду CLI
iroha kaigi endдля того же звонка ID.
Приватные Kaigi нужды защищены XOR для оплаты частной платы входного пункта. Если демо сообщает о том, что частные Kaigi нужды защитены XOR, используйте запрос самозащиты в приложении и попробуйте снова сделать или присоединиться к действию. Если генерация доказательств, частное финансирование или живая сигнализация недоступны, демо может вернуться к прозрачному / ручному потоку. В этом случае открыть Advanced Signaling, скопируйте сырое предложение или пакет ответа и вставьте его в другое окно.
Для автоматизированных проверок в демо-репо, запустить:
npm test -- tests/kaigiView.spec.ts tests/preloadKaigiBridge.spec.ts
npm run e2e:ui
npm run verifyЦеленаправленные аптеки Vitest охватывают создание ссылок на встречи Kaigi, компактную загрузку приглашений, частные вызовы моста для создания / присоединения / окончания, запросы самозащиты, ручные отказы и опросы ответов. Тест на дым UI включает маршрут /kaigi на настольных и мобильных порталах зрения. Живые средства массовой информации между двумя кошельками все еще нуждаются в ручном тесте двух окон, потому что разрешения на камеру браузера / микрофон и потоки сверстников медиа специфичны для окружающей среды.
Для кода интеграции образца см. Встроенный Kaigi в приложение JavaScript.
Статус и показатели
Окончательные точки статуса и показателей являются первыми вещами, которые вводятся в панели управления:
/statusраскрывает поля сверстников, блоков, очередей и консенсуса высшего уровня./metricsраскрывает счетчики, метры и гистограммы Прометея
На Nexus- включенные узлы, выход состояния также включает в себя полосы и разделы с пониманием пространства данных. nexus.enabled = false, Эти разделы выпущены.
JSON против Norito
Некоторые конечные точки оператора возвращаются Norito По умолчанию, когда конечная точка поддерживает JSON, отправлять:
Accept: application/jsonЭто особенно полезно для:
/v1/sumeragi/status/v1/sumeragi/qc/v1/sumeragi/commit_qc/{hash}
Когда конечный пункт принимает или возвращает напечатанное Norito непосредственно, использование application/x-norito как тип содержания или предпочтительный Accept ценность. Norito для деталей перевозки.
Профили телеметрии
Видимость конечных точек зависит от настройки telemetry.profile узла. Текущая конфигурация предоставляет пять уровней профиля:
| Профиль | /status | /metrics | маршруты разработчиков |
|---|---|---|---|
disabled | нет | нет | нет |
operator | да | нет | нет |
extended | да | да | нет |
developer | да | нет | да |
full | да | да | да |
CLI Сорткоды
iroha CLI уже включает в себя многие из этих конечных пунктов:
iroha --config ./localnet/client.toml --output-format text ops sumeragi status
iroha --config ./localnet/client.toml --output-format text ops sumeragi phases
iroha --config ./localnet/client.toml ops sumeragi params
iroha --config ./localnet/client.toml --output-format text ops sumeragi telemetry