У меня есть 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.