Адреса, папки и доступ

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

Адрес — это счёт

У адреса есть путь деривации, сеть и основной токен. Он принимает и отправляет средства, а его баланс делится на available и reserved (подробнее — в журнале). У каждого адреса есть владелец — тот, кто его создал.

• GET /api/v1/vaults/{code}/addresses — список адресов Vault'а с фильтрами: search, token (основной токен), access=shared (только доступное вам).
• GET /api/v1/vaults/{code}/addresses/{id} — детали одного адреса: баланс и последние операции.
• PATCH /api/v1/vaults/{code}/addresses/{id} — обновить адрес (например, переименовать).

Создание адреса разобрано на странице Vault — там же про сегменты и derivation path.

Папки: адреса под одной крышей

Папка — это именованный набор адресов. Она удобна, когда доступ и учёт нужно вести не по одному адресу, а по группе — например, «все адреса клиента» или «все инвойсные адреса».

• POST /api/v1/vaults/{code}/address-folders — создать папку.
• POST /api/v1/vaults/{code}/address-folders/{id}/members — добавить адрес в папку.
• GET /api/v1/vaults/{code}/address-folders/{id} — состав папки и выданные на неё гранты одним ответом.

У папки есть владелец — «менеджер» (у адреса владелец — создатель).

Доступ выдаётся ролями

Права и на адрес, и на папку задаются ролью:

• viewer — только просмотр.
• contributor — просмотр и переводы (view + transfer).

Право создавать адреса (canCreateAddress) в роль не входит и выдаётся отдельно.

Выдать доступ можно двумя способами:

• На адрес точечно — POST /api/v1/vaults/{code}/addresses/{id}/shares. Одиночная форма выдаёт один грант, пакетная (subjects[]) — сразу нескольким субъектам.
• На папку целиком — POST /api/v1/vaults/{code}/address-folders/{id}/grants. Субъект получает права на все адреса папки, включая добавленные позже — новый адрес в папке автоматически доступен всем, кому открыта папка.

Субъектом гранта может быть пользователь или группа пользователей. Грант на группу — это доступ для всех её участников; отзывается он выходом из группы, а не точечно.

Пример: открыть коллеге доступ к адресу с правом переводов.

curl -X POST "[BASE_URL]/api/v1/vaults/demo_vault/addresses/ADDRESS_ID/shares" \
  -H "Authorization: Bearer $V3_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "subjectType": "user", "subjectId": "USER_ID", "role": "contributor" }'

await fetch("[BASE_URL]/api/v1/vaults/demo_vault/addresses/ADDRESS_ID/shares", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.V3_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ subjectType: "user", subjectId: "USER_ID", role: "contributor" }),
});

requests.post(
    "[BASE_URL]/api/v1/vaults/demo_vault/addresses/ADDRESS_ID/shares",
    headers={"Authorization": f"Bearer {os.environ['V3_TOKEN']}"},
    json={"subjectType": "user", "subjectId": "USER_ID", "role": "contributor"},
)

Кто и откуда получил доступ

Когда доступ приходит из разных источников (личный грант, папка, группа пользователей), важно видеть не сами гранты, а людей и то, откуда у каждого доступ:

• GET /api/v1/vaults/{code}/addresses/{id}/participants — список людей с доступом к адресу: группы пользователей раскрыты, доступ через папку учтён, владелец отдан отдельно.

Поле via объясняет источник доступа и тем самым способ его убрать:

• direct — личный грант, отзывается точечно.
• user_group — доступ выдан группе, снимается только выходом из неё.
• доступ, пришедший от папки, отражается там же.

Смежные списки:

• GET /api/v1/vaults/{code}/shared-with-me — только прямые гранты на адрес (доступ через папку/группу сюда не попадает). Для «всё доступное мне» используйте GET /addresses?access=shared.
• GET /api/v1/vaults/{code}/shared-by-me — что вы открыли другим: и адреса, и папки.

Видимость по умолчанию изолирована

Доступ отвечает на вопрос «что можно делать», а видимость — «что вообще видно». По умолчанию обычный участник видит только свои адреса, операции и балансы; администратор — весь Vault. Права применяются ещё до агрегации, поэтому чужие данные не попадают даже в суммарные цифры.

Администратор может расширить видимость точечно:

• POST /api/v1/vaults/{code}/visibility-grants — кто (subjectType: user|group) и кого видит (scope: self|group|vault). Например, дать роли комплаенса видимость по всему Vault'у.

Что дальше