От первого вызова до финализированного состояния.

NexusSDK — интерфейс для разработчиков ORBITRA ONE™. Он предоставляет рыночные примитивы, а также примитивы идентичности, активов и агентов в виде типизированных сервисов на основе тех же нативных модулей, которые обеспечивают работу Orbitra Prime и расчёты в Orbitra L1.

Сервисы

• Рыночные API — заявки, книги заявок, RFQ и клиринговые дельты в ApexMatch, с предрисковой проверкой Aegis по каждой заявке.
• Asset Studio — выпуск и администрирование токенизированных активов с разрешениями эмитента, событиями жизненного цикла и контролем критериев допуска.
• Идентичность агентов — ИИ-агенты и боты регистрируются как подотчётные идентичности, каждая привязана к политике Cortex.
• Обмен данными — публикация и лицензирование наборов данных и сигналов с проверяемым происхождением.
• VaultID — проверка удостоверений допуска и разрешений без обработки документов, удостоверяющих личность.
• Платежи — платёжные запросы и расчёты с той же детерминированной финальностью, что и сделки.

Принципы проектирования

• Каждый вызов выполняется идентичностью с явными, ограниченными по объёму разрешениями.
• Каждое изменение состояния возвращает подписанное подтверждение, которое можно проверить независимо.
• Лимиты, заданные на стороне клиента, повторно проверяются протоколом.
• Учётные данные и адреса конечных точек поступают из окружения, а не из исходного кода.

Названия пакетов и crate в этих примерах приведены по демонстрационному образцу. Реальные названия опубликованных пакетов, учётные данные изолированной среды и адреса конечных точек предоставляются вместе с доступом к SDK — зарегистрируйте интерес разработчика.

Установка

# TypeScript and JavaScript
npm install @orbitra/nexus-sdk

# Python
pip install orbitra-nexus

# Rust
cargo add orbitra-nexus

Настройка учётных данных

SDK считывает две переменные окружения. Не включайте обе в систему контроля версий и загружайте их из менеджера секретов или среды развёртывания. Начните с учётных данных изолированной среды: она не связана с реальными активами и рынками.

• ORBITRA_API_KEY — ограниченные по объёму учётные данные, предоставляемые вместе с доступом к SDK.
• ORBITRA_ENDPOINT — адрес конечной точки окружения, предоставляемый вместе с этими учётными данными.

# Both values are issued with SDK access. Never commit them to a repository.
export ORBITRA_API_KEY="<issued-with-sdk-access>"
export ORBITRA_ENDPOINT="<issued-with-sdk-access>"

Первый вызов

import { NexusClient } from '@orbitra/nexus-sdk';

const apiKey = process.env.ORBITRA_API_KEY;
const endpoint = process.env.ORBITRA_ENDPOINT;

if (!apiKey || !endpoint) {
  throw new Error('Set ORBITRA_API_KEY and ORBITRA_ENDPOINT before running this example.');
}

const nexus = new NexusClient({ apiKey, endpoint });

const account = await nexus.accounts.current();
console.log(account.id, account.permissions);

Ответ описывает счёт, стоящий за учётными данными: его удостоверения VaultID, разрешения, выданные этому ключу, и рынки, к которым у него есть доступ. Ошибка разрешения означает, что ключ действителен, но не имеет нужной области действия для этого действия. В последующих примерах используется сокращение NexusClient.fromEnv(), которое считывает те же две переменные.

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

Типы идентичности

• Физическое лицо — человек, обладающий удостоверениями допуска, выданными в процессе онбординга.
• Институт — организация с субсчетами, ролями и правилами согласования двумя лицами.
• Приложение — сервис, зарегистрированный разработчиком и обладающий только теми разрешениями, которые он декларирует.
• Агент — ИИ-агент или бот, привязанный к политике Cortex и отзываемый его владельцем.

Ключи с ограниченной областью действия

API-ключи выдаются идентичности с определённой областью действия: какие сервисы, какие рынки, какие действия и на какой срок. Используйте отдельный ключ для каждой среды и каждого приложения и отзывайте ключи, которые больше не нужны.

import { NexusClient } from '@orbitra/nexus-sdk';

const nexus = NexusClient.fromEnv();

export async function canTradeOptions(subjectId: string): Promise<boolean> {
  // Returns whether the credential is present and valid, never the data behind it.
  const result = await nexus.vaultid.verify({
    subject: subjectId,
    credential: 'eligibility.options',
  });

  return result.valid;
}

Не собирайте в своём приложении документы, удостоверяющие личность, чтобы воссоздать проверки критериев допуска. Вместо этого запрашивайте удостоверение: VaultID подтверждает только его наличие и действительность — не более.

Каждый вызов, изменяющий состояние, возвращает подтверждение — подписанную запись того, что сеть сделала с вашим запросом: когда он был получен, где он был упорядочен, какое решение принял Aegis и что изменилось в результате.

Содержание подтверждения

• Получение — отметка времени приёма и подпись шлюза, принявшего запрос.
• Упорядочивание — каноническая позиция, присвоенная в результате справедливого упорядочивания.
• Решение по риску — решение Aegis и, в случае отказа, лимит, который был бы нарушен.
• Результат — исполнения, клиринговые дельты, события контрактов или переводы, возникшие в результате перехода.
• Финальность — ссылка на сертификат финальности QSE после того, как переход становится финальным.

Переход становится финальным, когда его покрывает сертификат финальности QSE. Не нужно ждать какой-либо глубины подтверждений: после сертификации состояние не реорганизуется в рамках заявленной модели отказов.

import { NexusClient } from '@orbitra/nexus-sdk';

const nexus = NexusClient.fromEnv();

export async function confirmFinal(transitionId: string): Promise<boolean> {
  // Resolves once a QSE quorum certificate covers the transition.
  const finality = await nexus.finality.wait(transitionId);

  // Checks the certificate signatures locally against the validator set it names.
  const verified = await nexus.finality.verify(finality.certificate);

  return finality.status === 'final' && verified;
}

Рыночные API напрямую предоставляют доступ к ApexMatch. Заявки — это подписанные намерения: SDK подписывает их вашим ключом, шлюз проверяет подпись, справедливое упорядочивание присваивает позицию, а прежде чем заявка попадёт в книгу заявок, выполняется предрисковая проверка Aegis.

Клиентская политика добавляет второй уровень защиты. SDK проверяет её перед подписанием, поэтому заявка, выходящая за пределы ваших собственных лимитов, никогда не покидает ваш процесс. Aegis всё равно применяет лимиты уровня счёта на барьере протокола.

import { NexusClient, definePolicy } from '@orbitra/nexus-sdk';

// fromEnv() reads ORBITRA_API_KEY and ORBITRA_ENDPOINT.
const nexus = NexusClient.fromEnv();

// Evaluated locally before the order is signed.
// Aegis enforces account-level limits again at the protocol gate.
const policy = definePolicy({
  markets: { allow: ['EURUSD'] },
  maxOrderNotional: '50000',
  maxLeverage: 2,
  requirePostOnly: true,
});

const receipt = await nexus.orders.place(
  {
    market: 'EURUSD',
    side: 'buy',
    type: 'limit',
    price: '1.0850',
    size: '10000',
    postOnly: true,
    clientOrderId: 'docs-example-001',
  },
  { policy },
);

console.log(receipt.status, receipt.sequence, receipt.riskVerdict);

Типы заявок

Основные типы — рыночная, лимитная, стоп, стоп-лимит, пост-онли и только на уменьшение — являются нативными. Продвинутые, алгоритмические и институциональные типы строятся на тех же примитивах; полное описание языка заявок приведено в разделе Исполнение.

Идентификаторы рынков, цены и объёмы в этих примерах приведены для демонстрации. Доступ к рынкам через API подчиняется тем же правилам критериев допуска и юрисдикции, что и интерфейс.

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

import { NexusClient } from '@orbitra/nexus-sdk';

const nexus = NexusClient.fromEnv();

// Nothing is submitted: Aegis returns the projected post-trade state.
const simulation = await nexus.risk.simulate({
  orders: [
    { market: 'EURUSD', side: 'buy', type: 'limit', price: '1.0850', size: '10000' },
  ],
  scenarios: ['volatility-shock', 'liquidity-drain'],
});

console.log('margin used', simulation.marginUsed);
console.log('liquidation distance', simulation.liquidationDistance);

for (const breach of simulation.policyBreaches) {
  console.warn(breach.policy, breach.limit, breach.projected);
}

Что возвращает симуляция

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

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

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

Каждое намерение, предлагаемое агентом, проходит через контур Cortex — наблюдение, рассуждение, предложение, симуляция, авторизация, исполнение. Механизм политик авторизует или отклоняет каждое из них, и каждое действие формирует подтверждение, отнесённое к этому агенту.

{
  "policyVersion": "1",
  "capital": { "maxAllocation": "100000", "asset": "USD" },
  "loss": { "dailyLimit": "2000", "lifetimeLimit": "10000" },
  "leverage": { "ceiling": 3 },
  "markets": { "allow": ["EURUSD", "GBPUSD"], "deny": [] },
  "session": { "hours": "Mon-Fri 07:00-17:00 UTC", "expiresAfter": "P30D" },
  "confirmation": { "requiredAboveNotional": "25000" },
  "dataSources": ["prism:fx-majors", "account:portfolio"],
  "kill": { "onBreach": "revoke-all", "cancelOpenOrders": true }
}

import { readFile } from 'node:fs/promises';
import { NexusClient } from '@orbitra/nexus-sdk';

const nexus = NexusClient.fromEnv();

const policy = JSON.parse(await readFile('./policies/fx-hedger.json', 'utf8'));

const agent = await nexus.agents.register({ name: 'fx-hedger', policy });

// At any time, one command revokes every permission the agent holds.
await nexus.agents.kill(agent.id);

Остановка агента

Средство отключения одной командой отзывает все разрешения, которыми обладает агент. Открытые заявки отменяются в соответствии с политикой, а ключ агента больше не может подписывать.

Автоматизация, включая автоматизацию с использованием ИИ, может давать сбои или работать не так, как ожидается. Политики ограничивают возможный ущерб, но не устраняют риск. См. ИИ и автоматизированная торговля.

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

use orbitra_nexus_wasm::prelude::*;
use orbitra_nexus_wasm::market::{LimitOrder, MarketId, OrderReceipt, Side};

/// Rebalances a treasury position with post-only limit orders on one market.
/// The capability list is checked at deployment; any other call is rejected at runtime.
#[contract(capabilities = [market::place_order, market::cancel_order, storage::read_write])]
pub struct TreasuryRebalancer {
    market: MarketId,
    max_order_size: Decimal,
}

#[contract_impl]
impl TreasuryRebalancer {
    #[call(owner_only)]
    pub fn rebalance(
        &mut self,
        ctx: &mut Context,
        side: Side,
        price: Decimal,
        size: Decimal,
    ) -> Result<OrderReceipt> {
        ensure!(size <= self.max_order_size, ContractError::SizeAboveLimit);

        let order = LimitOrder::new(self.market.clone(), side, price, size).post_only(true);

        // Native call into ApexMatch. Aegis pre-risk applies to the contract's own account.
        ctx.market().place_order(order)
    }
}

Сборка

rustup target add wasm32-unknown-unknown
cargo build --release --target wasm32-unknown-unknown

• Вычисления и хранилище имеют явную цену, поэтому стоимость контракта определяется тем, что он делает.
• Декларированный доступ к состоянию позволяет независимым контрактам выполняться параллельно в VectorLanes.
• Рыночные вызовы из контракта проходят предрисковую проверку Aegis для собственного счёта контракта, как и любая другая заявка.
• При развёртывании модуль отправляется вместе со списком полномочий; модуль, вызывающий недекларированный примитив, отклоняется.

EVM Capsule — изолированный домен совместимости для байт-кода и инструментов Ethereum. У него собственные потолки по газу и ресурсам, доступ к основным активам осуществляется только через шлюз с ограничением частоты, а автоматические выключатели могут остановить его без влияния на основную среду выполнения.

Капсула — это граница совместимости, а не основная среда выполнения. Нативные рыночные примитивы вызываются из NexusWASM; капсула подключается к основным активам только через свой управляемый шлюз.

Этапы миграции

• Развернуть без изменений. Существующие контракты и привычные инструменты работают внутри капсулы с тарификацией по её собственным потолкам.
• Переносить активы обдуманно. Перемещайте активы через шлюз с ограничением частоты, с лимитами маршрутов, соответствующими вашей экспозиции.
• Измерять. Определите, где нативная производительность или доступ к рынку важны больше всего — как правило, это обработка заявок, расчёты и логика риска.
• Переносить код. Реализуйте заново эти пути как контракты NexusWASM, которые вызывают ApexMatch и Aegis напрямую, сохраняя версию в капсуле как эталон.
• Проверить и вывести из эксплуатации. Прогоните одни и те же входные данные через обе версии, переведите пользователей на нативные контракты, когда результаты совпадут, и сверните развёртывание в капсуле.

Операторы запускают клиент узла, чтобы воспроизводить финализированное состояние, обслуживать приложения или, после допуска в качестве валидаторов, выполнять обязанности предлагающего и комитета в рамках QSE. Один клиент обслуживает каждую роль: конфигурация поступает из окружения, а ключи подписи хранятся в HSM или модуле подписи MPC.

# Verify the release before installing it. Release-signing keys are published with operator access.
orbitra-node verify-release ./orbitra-node.tar.gz --signature ./orbitra-node.tar.gz.sig

# Configuration comes from the environment. Keys stay in the HSM or MPC signer.
export ORBITRA_NETWORK="<issued-with-operator-access>"
export ORBITRA_ENDPOINT="<issued-with-operator-access>"
export ORBITRA_SIGNER="hsm"   # or "mpc"

orbitra-node init --network "$ORBITRA_NETWORK" --signer "$ORBITRA_SIGNER"
orbitra-node start

# Inspect assigned duties, quorum participation and service measurements.
orbitra-node status --duties --service

# Rehearse a Q-Switch signature-suite rotation without applying it.
orbitra-node keys rotate --suite next --dry-run

Показанные названия команд приведены для демонстрации. Клиент оператора, его ключи для подписи релизов и идентификаторы сети предоставляются вместе с доступом оператора — см. Валидаторы.

Правила эксплуатации

• Проверяйте подпись каждого релиза перед установкой или обновлением.
• Ссылайтесь на ключи через подписывающее устройство, а не через файл: ключи валидатора не должны храниться на хосте узла.
• Экспортируйте показатели обязанностей и обслуживания в собственную систему мониторинга и оповещений.
• Выполняйте ротацию наборов подписей через команды Q-Switch, а не путём произвольной замены ключей.

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

Каждое примечание к выпуску фиксирует

• Новые, изменённые и удалённые интерфейсы с примером каждой новой формы.
• Устаревшие элементы, замену для каждого из них и шаги для перехода.
• Изменения наборов подписей или форматов удостоверений, введённые через Q-Switch.
• Параметры протокола, влияющие на операторов узлов и валидаторов.
• Исправления безопасности после согласования раскрытия информации.

Вы читаете превью-издание. Его интерфейсы описаны в соответствии со спроектированной реализацией и могут измениться до выхода в общий доступ; каждое изменение фиксируется в примечаниях к выпуску той версии, которая его вводит.