← BSN Naming Provider
Atlas · 23 сентября 2026

Как связать имя из BSN с Onym и показать его в чатах

У меня есть Stellar-аккаунт, в котором уже записано имя в BSN. Хочется использовать это же имя в Onym, чтобы оно появлялось в моём профиле и рядом с сообщениями в чатах. Соответственно, нужен сервис, который прочитает имя, проверит, что я действительно связываю этот аккаунт со своей идентичностью Onym, и даст другим клиентам возможность проверить результат.

Для этого сделан BSN Naming Provider, а в веб-версии Onym появилась его поддержка. Ниже разберём весь процесс на моём Stellar-адресе: сначала то, что делает пользователь, а затем запросы, которые при этом выполняет клиент.

1. Откуда берётся имя

Возьмём мой адрес в основной сети Stellar:

GCPJUXPETZEIJNEAAEO2LGZIA6IQNNWGOHPNP4ZQECDS6IKKIGJO5LFV

В его данных есть тег Name со значением Valerij Utrosin. Именно эту строку мы и будем использовать для отображения. Увидеть её можно через Horizon, публичный API Stellar:

ACCOUNT='GCPJUXPETZEIJNEAAEO2LGZIA6IQNNWGOHPNP4ZQECDS6IKKIGJO5LFV'
curl -fsS "https://horizon.stellar.org/accounts/$ACCOUNT" \
  | jq -r '.data.Name | @base64d'

В BSN имена хранятся в data entries аккаунта, а Horizon возвращает их значения в Base64, поэтому в примере есть декодирование. Провайдер сначала ищет Name; если такого тега нет, проверяет вариант name с маленькой буквы. Имя читается из основной сети Stellar, даже когда сам чат Onym работает с контрактом в тестовой сети.

Здесь я использую своё имя как пример. Если повторяете процесс для себя, подставьте адрес аккаунта, которым управляете, и проверьте его тег Name.

2. Как связать Stellar-аккаунт с идентичностью Onym

У идентичности Onym есть публичный ключ Ed25519, которым клиент подписывает сообщения и запросы. Из этого ключа получается Stellar-адрес, начинающийся с G. Его можно посмотреть в разделе «Моя идентичность». Именно этот адрес надо указать в BSN как значение тега OwnershipFull или его свободного пронумерованного варианта.

Получается следующая связка: в моём существующем Stellar-аккаунте записано, какой идентичности Onym разрешено использовать его имя, а клиент Onym подтверждает владение своим ключом подписью запроса. Для этой проверки не требуется заранее создавать или пополнять выведенный из ключа Onym Stellar-аккаунт, поскольку он используется как представление публичного ключа.

В веб-клиенте это делается через «Моя идентичность → Имя из BSN». Вставляете свой Stellar-адрес и нажимаете «Создать транзакцию привязки». Клиент заново загружает данные аккаунта, находит свободный тег и собирает готовую XDR-транзакцию. Когда мы проверяли мой адрес, первые три тега были заняты, поэтому выбирался OwnershipFull3. При следующем обращении свободный номер может оказаться другим.

В транзакции одна операция ManageData, которая добавляет выбранный тег со Stellar-адресом вашей идентичности Onym. На экране видны это значение, комиссия, дополнительный резерв под запись и время, до которого транзакция действует. Можно скопировать XDR, скачать файл или открыть ссылку в кошельке с поддержкой SEP-7, после чего подписать и отправить транзакцию своим Stellar-кошельком.

Для разработчика эта же подготовка выглядит так. Дальнейшие TypeScript-примеры рассчитаны на код внутри web/src нашего клиента, где переменная client — уже разблокированный экземпляр Client. Используемые функции есть в репозитории; запускать эти фрагменты в консоли браузера пользователю не требуется.

import { prepareBindingTransaction } from "./stellarBinding";

const stellarAccount =
  "GCPJUXPETZEIJNEAAEO2LGZIA6IQNNWGOHPNP4ZQECDS6IKKIGJO5LFV";

const transaction = await prepareBindingTransaction(
  stellarAccount,
  client.identity.stellarAccount,
);

// Показываем пользователю и передаём в его Stellar-кошелёк.
console.log(transaction.tag);   // Например, OwnershipFull3
console.log(transaction.xdr);   // Неподписанная транзакция
console.log(transaction.uri);   // Ссылка web+stellar:tx?...

XDR собирается в браузере с помощью официального Stellar SDK. Срок её действия — 15 минут. Если за это время с того же аккаунта отправили другую транзакцию, надо нажать «Сформировать заново», чтобы получить актуальный sequence number. После успешной отправки возвращаемся в Onym и нажимаем «Я отправил — проверить связь».

3. Что показывает предварительная проверка

У провайдера есть метод preview, который позволяет узнать найденное имя и проверить, есть ли нужный тег связи. Для него достаточно публичных данных. В поле subject передаётся строка onym:key: и Ed25519-ключ Onym в виде 64 шестнадцатеричных символов нижнего регистра. В интерфейсе нужный ключ подписан «Ed25519 — подпись».

BASE='https://atlas.predhit.com/bsn-np'
ACCOUNT='GCPJUXPETZEIJNEAAEO2LGZIA6IQNNWGOHPNP4ZQECDS6IKKIGJO5LFV'
# Подставьте свой публичный ключ из «Ed25519 — подпись».
PUBKEY='ВАШ_ED25519_КЛЮЧ_64_HEX_СИМВОЛА'
SUBJECT="onym:key:$PUBKEY"

jq -n --arg account "$ACCOUNT" --arg subject "$SUBJECT" \
  '{stellarAccount: $account, subject: $subject}' \
  | curl -fsS "$BASE/v1/preview" \
      -H 'Content-Type: application/json' --data-binary @-

Когда связи ещё нет, ответ будет примерно таким. Значение value здесь сокращено для чтения; настоящий API возвращает полный Stellar-адрес, который требуется записать в тег.

{
  "eligible": false,
  "tag": "OwnershipFull",
  "value": "G…адрес вашей идентичности Onym…",
  "name": "Valerij Utrosin"
}

После появления нужного тега eligible станет true, а в ответе будут displayName, nameTag, bindingTag и onymAccount. На этом этапе пользователь видит найденное имя и может перейти к его получению. Для отображения проверенного имени в чатах дальше понадобятся подписанная запись провайдера и подтверждение владельца.

4. Как получить подписанную запись имени

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

curl -fsS "$BASE/manifest.json" | jq
curl -fsS "$BASE/profile.json" | jq
curl -fsS "$BASE/policy.json" | jq

В нашей веб-версии публичный ключ этого провайдера закреплён в коде. Функция namingManifest() проверяет ключ и подпись манифеста, поэтому при неожиданной замене ключа проверка остановится. Конкретный BSN-профиль основан на проекте Association Naming Onym; его HTTP-методы и правила описаны в нашей спецификации.

Затем клиент вызывает request-issuance. Запрос подписывается ключом текущей идентичности Onym и включает адрес Stellar-аккаунта, время создания, срок действия и случайный nonce, чтобы один и тот же подписанный запрос нельзя было выполнить повторно.

import { hex } from "./bytes";
import { limitedJson } from "./transport";
import {
  NAMING_URL, namingManifest, requestProof, verifyResolution,
} from "./naming";

const subject = "onym:key:" + hex(client.identity.signingPublic);
const manifest = await namingManifest();

const request = requestProof(
  "request-issuance",
  { stellarAccount },
  client.identity,
);

const rawOffer = await limitedJson(
  NAMING_URL + "v1/request-issuance",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(request),
  },
);

const offer = verifyResolution(rawOffer, subject, manifest.policy);
const row = offer.records[0];
if (!row || row.status !== "unaccepted" ||
    row.record.stellarAccount !== stellarAccount ||
    Date.parse(row.record.expiresAt) <= Date.now()) {
  throw new Error("Предложение имени не прошло проверку");
}
const record = row.record;
// Показываем record.displayName и источник пользователю.

Провайдер проверит подпись, прочитает Stellar и убедится, что тег указывает на ключ подписавшего запрос. В результате появится AssociationRecord со статусом unaccepted, то есть предложение имени, ожидающее подтверждения. В записи будут субъект, имя для отображения, Stellar-аккаунт, номер версии, срок действия и подпись провайдера.

Есть деталь, которую важно учесть при интеграции: строка «Valerij Utrosin» находится в record.displayName. Поле record.name содержит полный Stellar-адрес, который используется как уникальная часть имени внутри провайдера. Поэтому одинаковые человеческие имена спокойно существуют у разных аккаунтов, а клиент может показать, к какому аккаунту относится каждое из них.

Для собственного клиента подписи собираются по следующему правилу: ключи JSON-объектов рекурсивно сортируются, JSON записывается компактно в UTF-8, поле signature исключается из подписываемого объекта. Перед ним добавляется строка onym-bsn-np-v1:<kind> и один перевод строки LF. Для запроса kind равен request, для подтверждения — acceptance. Алгоритм — Ed25519, результат передаётся в Base64. Хеш записи считается по полному каноническому объекту, включая подпись провайдера, и имеет вид sha256:<hex>.

5. Как пользователь подтверждает имя

Теперь пользователю показывается конкретное имя и предлагается его принять. Кнопка «Принять имя и опубликовать связь» создаёт SubjectAcceptance, в котором подписывается хеш именно этой записи. Так подтверждение привязано и к выбранному имени, и к сроку его действия, и к провайдеру, который его выдал.

Ниже пример того, как формируется второй запрос. Его выполняет обработчик явного подтверждения пользователя; переменные record, subject и manifest получены на предыдущем шаге.

import { ed25519 } from "@noble/curves/ed25519.js";
import { b64, utf8 } from "./bytes";
import { canonical, recordDigest } from "./naming";

const acceptanceBody = {
  acceptanceVersion: 1,
  record: recordDigest(record),
  subject,
  publish: true,
  acceptedAt: new Date().toISOString(),
  expiresAt: record.expiresAt,
};
const acceptance = {
  ...acceptanceBody,
  signature: b64(ed25519.sign(
    utf8("onym-bsn-np-v1:acceptance\n" + canonical(acceptanceBody)),
    client.identity.signingSecret,
  )),
};

const rawAccepted = await limitedJson(NAMING_URL + "v1/accept-record", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(requestProof("accept-record", {
    record: recordDigest(record),
    acceptance,
  }, client.identity)),
});

const accepted = verifyResolution(rawAccepted, subject, manifest.policy);
const active = accepted.records.find(r =>
  r.status === "active" && recordDigest(r.record) === recordDigest(record)
);
if (!active) throw new Error("Имя не активировано");

Поле publish: true разрешает провайдеру отдавать эту связь по публичному запросу. После подтверждения другой клиент сможет узнать, какое имя владелец принял для своего ключа Onym. Само предложение, которое ещё не принято, в такой выдаче не появляется. API также допускает publish: false, но текущий интерфейс подключения рассчитан на публичное разрешение имени в чатах.

В нашем клиенте весь этот шаг, вместе с сохранением настройки в зашифрованном хранилище, уже собран в await client.useName(record). В интеграции достаточно вызвать его после согласия пользователя; длинный пример выше показывает содержимое обмена с API.

6. Как имя появляется рядом с сообщением

Допустим, другой участник открыл чат со мной и включил показ проверенных имён BSN. В подтверждённом составе группы у него уже есть мой ключ подписи sending_pubkey, связанный с BLS-ключом участника. По нему клиент строит subject и обращается к провайдеру через resolve-subject. Для чтения публично принятого имени подпись запроса не требуется:

jq -n --arg subject "$SUBJECT" '{subject: $subject}' \
  | curl -fsS "$BASE/v1/resolve-subject" \
      -H 'Content-Type: application/json' --data-binary @-

Ответ содержит массив records, где у каждой строки есть запись провайдера, подтверждение владельца и текущий статус. Весь ответ тоже подписан и содержит время проверки. Получив его, клиент проверяет подписи провайдера и владельца, совпадение субъекта, хеш принятой записи, сроки действия и статус active.

В коде это можно собрать так. Переменная group здесь — уже проверенная группа, а message — сообщение, для которого клиент уже проверил отправителя.

import { unb64 } from "./bytes";
import { resolveName, NAMING_NS } from "./naming";

const member = group.member_profiles[message.sender_bls_pubkey_hex];
if (!member) throw new Error("Нет подтверждённого профиля отправителя");

const senderSubject = "onym:key:" + hex(unb64(member.sending_pubkey));
const currentManifest = await namingManifest();
const result = await resolveName(senderSubject, currentManifest.policy);
// resolveName уже проверяет подписи, принятие записи и свежесть ответа.
const named = result.records
  .filter(row => row.status === "active")
  .sort((a, b) => b.record.sequence - a.record.sequence)[0];

const displayName = named?.record.displayName ?? member.alias;
const source = named
  ? "@" + NAMING_NS + " · " + named.record.stellarAccount
  : "Локальное имя";
// Передаём displayName и source в текстовые элементы интерфейса.

В результате в чате видно «Valerij Utrosin», а рядом — источник @bsn.atlas.predhit.com и сокращённый Stellar-адрес. Это помогает различать людей с одинаковыми именами. При отсутствии действующего подтверждения клиент возвращается к локальному имени участника.

Провайдер при такой проверке получает публичные ключи, которые у него спрашивают, поэтому показ BSN-имён включается отдельно. Текущая веб-версия проверяет свою идентичность и до 19 других участников открытой группы, обновляя результат примерно раз в 30 секунд. Подписанный ответ пригоден для текущего отображения не дольше 60 секунд, и при недоступности проверки клиент убирает подтверждённое имя.

Если известен сам Stellar-аккаунт, доступен и прямой запрос resolve-name. В нём передаётся полное квалифицированное имя аккаунта:

jq -n --arg name "$ACCOUNT@bsn.atlas.predhit.com" '{name: $name}' \
  | curl -fsS "$BASE/v1/resolve-name" \
      -H 'Content-Type: application/json' --data-binary @-

Этот метод удобен для просмотра конкретной записи по аккаунту. Для отображения отправителя в нашей веб-версии используется resolve-subject, потому что ключ отправителя уже известен из группы. Приведённый выше verifyResolution тоже рассчитан на запрос по субъекту; интеграция прямого поиска по квалифицированному имени требует соответствующей проверки поля query.

7. Что происходит, если изменить имя или отключить связь

Имя меняется в теге Name Stellar-аккаунта. При следующей проверке провайдер увидит, что данные расходятся с прежней записью, и та перестанет подтверждаться. Пользователь снова запрашивает предложение и принимает новое имя. Такой же новый цикл потребуется после истечения семидневного срока записи; для получения следующего предложения у API есть метод renew-record с теми же полями запроса, что у request-issuance.

Если надо отказаться от принятого имени, в интерфейсе есть «Отозвать привязку имени». Клиент подписывает Disavowal и отправляет его через disavow-record. Для уже принятой записи вызов готовой функции выглядит так:

import { disavowName } from "./naming";

// Выполняется после выбора пользователем «Отозвать привязку имени».
await disavowName(recordDigest(record), client.identity);
// Метод отправит подписанные disavowal и запрос в v1/disavow-record.

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

Снять флажок «Показывать проверенные имена BSN» можно и без отзыва: тогда этот клиент прекращает запросы и показывает локальные имена, а опубликованная связь остаётся доступной другим. При удалении тега связи из Stellar провайдер также перестаёт подтверждать имя. Если исходные данные впоследствии восстановлены и запись ещё действует, проверка может снова пройти; явный отзыв конкретной записи окончателен.

Где это уже работает

Подключение и проверка реализованы в Onym Web. Чтобы собеседник увидел имя как проверенное, его клиенту нужна поддержка этого BSN-профиля и включённое отображение имён. В мобильных клиентах такая проверка сама по себе от подключения провайдера не появится, для неё потребуется соответствующая доработка.

Если будете подключать другой веб-клиент, учтите ещё один момент: сейчас CORS разрешён для onym.predhit.com и atlas.predhit.com. Запросы из терминала работают без Origin; для браузера на другом домене потребуется добавить его в конфигурацию провайдера. Примеры выше используют действующие методы и поля нашей реализации.

Исходники провайдера и веб-клиента опубликованы в GitHub. Там же можно посмотреть проверку подписей и подготовку XDR, а в описании HTTP-профиля собраны форматы объектов, ограничения и правила актуальности. О том, как устроены сами BSN-теги, подробнее написано в описании BSN.