Перейти к основному содержимому

Wallet Owner API v3

Owner API — это интерфейс, через который программное обеспечение управляет кошельком: создаёт его, читает балансы, собирает и финализирует переводы, проверяет доказательства. Для большинства интеграций это основная поверхность взаимодействия.

  • Эндпоинт: http://127.0.0.1:3420/v3/owner, запускается с помощью epic-wallet owner_api
  • Протокол: JSON-RPC 2.0 поверх HTTP POST
  • Учётные данные: token, возвращаемый open_wallet, который принимает пароль кошелька
  • Шифрование: ECDH-хендшейк оборачивает каждый вызов после первого

Передавайте token внутри конверта в каждом методе, который его объявляет. Держите порт на loopback. См. доступ к owner на кошельке.

Методы по назначению​

Могут тратить средства​

Can spend funds Эти семь методов собирают, завершают или отменяют переводы.

МетодНазначение
init_send_tx()Выбрать входы и собрать первый раунд слейта (slate)
tx_lock_outputs()Зарезервировать выбранные входы. Обязательно в последовательности ручной отправки. Принимает token, slate, participant_id и addr_to
finalize_tx()Завершить агрегированную подпись
post_tx()Транслировать в сеть
issue_invoice_tx()Создать платёжный запрос
process_invoice_tx()Профинансировать чужой платёжный запрос
cancel_tx()Отменить перевод и освободить зарезервированные выходы

Деструктивные​

Destructive Удаляет локальные данные кошелька.

МетодЭффект
delete_wallet()Удаляет кошелёк

Раскрывают секрет​

get_mnemonic() возвращает фразу восстановления.

Изменяют состояние кошелька​

change_password() повторно шифрует сид. scan() перестраивает состояние выходов.

Только чтение​

Read only Безопасно для всего, что вы разрешили бы читать ваш баланс.

accounts(), retrieve_outputs(), retrieve_txs(), retrieve_summary_info(), node_height(), get_stored_tx(), get_public_address(), get_public_proof_address(), get_updater_messages().

Жизненный цикл кошелька​

create_config(), create_wallet(), open_wallet(), close_wallet(), get_top_level_directory(), set_top_level_directory(), create_account_path(), set_active_account().

open_wallet возвращает токен, который требуется каждому другому вызову.

Доказательства​

retrieve_payment_proof(), verify_payment_proof(), proof_address_from_onion_v3(), verify_slate_messages(). См. доказательства платежей.

Конфигурация и фоновые обновления​

set_tor_config(), set_epicbox_config(), start_updater(), stop_updater().

Транспорт​

init_secure_api().

Зашифрованное рукопожатие​

Каждый вызов после init_secure_api передаётся внутри зашифрованного конверта. Параметры фиксированы и объявлены в api/src/owner_rpc_s.rs:1453: AES-256 в режиме GCM, 12-байтовый nonce, 16-байтовый тег, добавляемый к шифртексту, и пустые дополнительные аутентифицированные данные.

  1. Сгенерируйте пару ключей secp256k1 в своём клиенте.
  2. Вызовите init_secure_api, передав сжатый публичный ключ в виде hex в ecdh_pubkey. Кошелёк возвращает свой ключ в том же формате.
  3. Умножьте публичную точку кошелька на ваш приватный скаляр и возьмите 32-байтовую x-координату. Это и есть ключ AES-256 (api/src/owner_rpc_s.rs:2433).
  4. Сериализуйте нужный вызов как полный объект JSON-RPC запроса. Этот внутренний запрос и является тем, что шифруется, и именно в нём находятся token и параметры метода.
  5. Зашифруйте его со свежим 12-байтовым nonce и закодируйте шифртекст с добавленным тегом в base64.
  6. Опубликуйте метод encrypted_request_v3 с двумя параметрами: nonce в виде hex и body_enc в виде строки base64. Конверт не содержит других полей (api/src/types.rs:59).
  7. Ответ — это encrypted_response_v3, несущий собственные nonce и body_enc. Расшифруйте тем же ключом, чтобы получить внутренний JSON-RPC ответ, который в свою очередь содержит конверт Ok или Err.
  8. open_wallet — первый вызов, который следует отправить через конверт. Он возвращает токен, который принимает каждый другой метод.
{"jsonrpc": "2.0", "id": 1, "method": "encrypted_request_v3", "params": {"nonce": "ef32...", "body_enc": "e0bcd..."}}

examples/python/epic_wallet.py реализует эту последовательность, включая второй разворот расшифрованного тела. Клиент приведён полностью в разделе подключение и чтение.

Чтение выходов и транзакций​

retrieve_outputs и retrieve_txs принимают limit, offset и sort_order.

InitTxArgs​

Управляет выбором входов и структурой транзакции.

ПолеТипЗначение
src_acct_namestring, optionalАккаунт-источник. Null использует активный аккаунт
amountu64Сумма в freemen. 1 EPIC равен 100000000
minimum_confirmationsu64Подтверждения, необходимые для того, чтобы выход стал доступен к трате
max_outputsu32Максимальное количество выбираемых входов
num_change_outputsu32Количество создаваемых выходов сдачи
selection_strategy_is_use_allboolTrue объединяет все доступные выходы; false выбирает минимум
messagestring, optionalСообщение, зафиксированное в слейте
target_slate_versionu16, optionalВерсия слейта для вывода, 2 или 3
ttl_blocksu64, optionalСрок действия в блоках. По умолчанию не задан
payment_proof_recipient_addressstring, optionalЗапрашивает доказательство платежа
estimate_onlybool, optionalВычислить комиссию без резервирования
send_argsobject, optionalНазначение и транспорт для выполнения всего обмена в одном вызове

Дополнительное поведение:

selection_strategy_is_use_all имеет последствия для приватности. Значение true объединяет ваши выходы в одну транзакцию, что связывает их между собой для любого, кто анализирует цепочку. Значение false сохраняет их раздельными ценой увеличения UTXO-множества в дальнейшем.

Доказательство платежа требует slate V3. payment_proof_recipient_address помещает поля доказательства в слейт (slate), и только V3 их содержит. Доставка через epicbox конвертирует слейт в V2, поэтому перевод, отправленный таким способом, завершается без доказательства. Сначала выберите транспорт: выбирайте транспорт соответственно.

ttl_blocks не освобождает выходы по истечении срока. См. выходы и блокировка.

src_acct_name задаёт исходный аккаунт для одного вызова. Метка, которую accounts не возвращает, разрешается в активный аккаунт (libwallet/src/api_impl/owner.rs:383). См. аккаунты.

send_args выполняет обмен внутри вызова. Он доставляет слейт, затем финализирует и публикует, если это было запрошено, поэтому вызов блокируется на всё время, пока отвечает контрагент.

При send_args.method, установленном в epicbox, вызов возвращает слейт первого раунда, как только он опубликован на релей и входы заблокированы (api/src/owner.rs:761). finalize и post_tx применяются к путям http и keybase. На пути epicbox собственная подписка кошелька финализирует и публикует транзакцию, когда приходит ответ контрагента, — именно там и происходит ожидание мемпула.

Комиссии​

Комиссия зависит от формы транзакции, а не от спроса в сети:

fee = max(4 × outputs + kernels − inputs, 1) × 0.001 EPIC

Типичный перевод с двумя входами (inputs), двумя выходами (outputs) и одним ядром (kernel) стоит 700,000 freemen, то есть 0.007 EPIC. Поскольку базовая комиссия кошельком не задаётся, рынка комиссий для торгов не существует.

Версия 2​

Более ранний незашифрованный Owner API с 17 методами обслуживается тем же слушателем по адресу /v2/owner. Его методы не требуют токена. Новые разработки следует ориентировать на v3, а слушатель должен находиться на loopback.

Полный справочник методов​

Сессия и аккаунты

Десять методов. Рукопожатие, токен и метки аккаунтов.

Чтение состояния

Восемь методов. Балансы, выходы, история, адреса.

Построение переводов

Семь методов. Те, что перемещают средства.

Доказательства платежа

Четыре метода и транспорт, который их отбрасывает.

Секреты и обслуживание

Четыре метода. Фраза восстановления, пароль, удаление и сканирование.

Конфигурация и обновление

Четыре метода. Настройки релея и фоновое обновление.

Источник​

Далее​

Интерактивные транзакции

Что делают методы отправки и почему их несколько.

Интеграция с биржей

Проектирование системы депозитов и вывода средств на основе этого API.