> ## Documentation Index
> Fetch the complete documentation index at: https://whalescorp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Solana смарт-контракты

# Смарт-контракт

Смарт-контракт — это программа, которая автоматически исполняет и обеспечивает выполнение заданных условий в блокчейне. Ее код хранится и выполняется прямо в сети, без посредников, по заранее определенным правилам.\
Структура контрактов [USDC](https://www.circle.com/usdc) и USDY основана на одном блокчейне, поэтому для них используется единое описание.

# Что такое USDC

[USDC](https://www.circle.com/usdc), сокращение от USD Coin, — это стейблкоин, созданный в 2018 году для поддержания стабильной стоимости за счет привязки к резервному активу. В случае USDC он обеспечен долларом США в соотношении 1:1, то есть каждый токен можно обменять на один доллар США или эквивалентный резервный актив. Благодаря этому USDC менее волатилен по сравнению с большинством других криптовалют.\
Он принадлежит и управляется [Centre](https://www.centre.io/), консорциумом, созданным [Circle](https://www.circle.com/) и [Coinbase](https://www.coinbase.com/), что обеспечивает доверие и прозрачность управления. Эти две крупные компании отвечают за развитие, выпуск и обслуживание монеты. Circle контролирует выпуск и погашение [USDC](https://www.circle.com/usdc), а Coinbase играет ключевую роль в распространении токена на различных платформах и биржах, обеспечивая его широкую доступность и использование.\
Сейчас в обращении находится примерно 28 миллиардов токенов [USDC](https://www.circle.com/usdc). Каждый токен полностью зарезервирован, то есть обеспечен долларами США или эквивалентными активами в соотношении 1:1, что и гарантирует его стабильность. Хотя сам USDC не застрахован FDIC, резервы, которые его обеспечивают, хранятся в регулируемых финансовых организациях. Кроме того, эти резервы регулярно проходят независимый аудит, чтобы подтверждать полное обеспечение USDC и давать пользователям прозрачность и безопасность.\
[USDC](https://www.circle.com/usdc) — это стейблкоин, работающий в нескольких блокчейн-сетях, таких как [Solana](https://solana.com/), [Ethereum](https://ethereum.org/), [Tron](https://tron.network/) и других. В каждой сети используется собственный адрес контракта для управления транзакциями [USDC](https://www.circle.com/usdc).\
[USDC](https://www.circle.com/usdc) в Holders доступен всем клиентам [с европейским резидентством](https://whales.enterprise.slack.com/docs/T045HLK3YLE/F09FNDP3PT7), которые прошли onboarding в Walleexer.

# Что такое USDY

[Ondo US Dollar Yield (USDY)](https://ondo.finance/usdy) — это токенизированный финансовый инструмент, который сочетает удобство использования стейблкоина с доходностью от сверхнадежных казначейских облигаций США и банковских депозитов. В первую очередь он рассчитан на инвесторов за пределами США.

1. Обеспечен краткосрочными [казначейскими облигациями США](https://www.treasurydirect.gov/) и депозитами, поэтому дает ежедневное начисление доходности, сохраняя при этом привязку к доллару США.
2. Защищен от банкротных рисков, имеет независимый надзор, избыточное обеспечение свыше 3% и ограничения на перевод токена для соблюдения регуляторных требований.
3. Используется как composable collateral в сетях [Ethereum](https://ethereum.org/), [Solana](https://solana.com/) и других блокчейнах, объединяя доходность традиционных финансов и ликвидность блокчейна.

[USDY](https://ondo.finance/usdy) соединяет традиционные финансы и децентрализованные экосистемы, токенизируя низкорисковые инвестиции в [казначейские облигации США](https://www.treasurydirect.gov/). Это позволяет инвесторам по всему миру получать доходность, около 4.25% годовых, которая обычно доступна только институциональным игрокам, и одновременно иметь круглосуточную ликвидность через блокчейн. В отличие от обычных стейблкоинов, стоимость USDY не просто привязана к доллару — она напрямую обеспечена доходными активами, что делает его гибридным продуктом, сочетающим стабильность и пассивный доход.\
[USDY](https://ondo.finance/usdy) в Holders сейчас находится в стадии тестирования, но в дальнейшем будет доступен всем клиентам с европейским резидентством, прошедшим onboarding в Walleexer.

# История

Контракт Solana был написан Holders в январе 2025 года и дал пользователям возможность использовать [USDC](https://www.circle.com/usdc) как валюту счета. Одной из задач, которую компания решила этим контрактом, было отсутствие европейской лицензии у [токена USDT](https://tether.to/en/), который на тот момент использовался как основная валюта для открытия счетов. Поскольку основным приложением на момент разработки был мобильный кошелек Tonhub, компании пришлось добавить в кошелек поддержку блокчейна Solana и тем самым сделать его мультивалютным.\
Так как главным приложением компании во время разработки контракта был мобильный кошелек [Tonhub](https://gettonhub.com/), в него нужно было встроить поддержку блокчейна Solana, что и сделало кошелек мультивалютным.\
Контракт для все более популярного токена [USDY](https://ondo.finance/usdy) был реализован в ноябре 2025 года как альтернатива [USDC](https://www.circle.com/usdc), поскольку хранение средств в этом токене позволяет пользователям не только платить им, но и получать дополнительный доход от владения.

# Как контракт работает простыми словами

1. Пользователь выбирает валюту и инициирует создание нового счета, передавая соответствующую команду контроллеру.
2. Контроллер создает контракт и передает права владения кошельку пользователя.
3. Пользователь пополняет баланс контракта.
4. При проведении транзакции контракт получает сигнал от контроллера заблокировать сумму, необходимую для выполнения операции.
5. Заблокированные суммы объединяются в batch, то есть rollup, чтобы оптимизировать затраты на gas.
6. Сформированный batch переводится на казначейский кошелек Holders.
7. При возврате средств сумма переводится с казначейского кошелька обратно на баланс пользовательского контракта.
8. Если пользователь инициирует вывод на внешний счет, контракт использует multi-signature и отправляет средства.

# Общая информация

Блокчейн: [Solana](https://solana.com/)\
Расположение: `https://github.com/whalescorp/holders-contracts/tree/main/packages/solana/programs/holders/src`\
**Язык:** [Rust](https://rust-lang.org/)\
Лицензия: [MIT](https://en.wikipedia.org/wiki/MIT_License)

# Роли контракта

## Владелец контракта (wallet authority)

Эта роль назначается пользователю Holders при деплое контракта — владельцем считается кошелек, с которого было инициировано создание контракта. Изменить владельца контракта невозможно, а при потере доступа к кошельку восстановить оставшиеся на контракте средства не получится. Единственный способ помочь клиенту, потерявшему доступ к кошельку, — посоветовать ему потратить средства с карт, привязанных к счету.

### Доступные действия:

* Установка лимитов счета
* Пополнение контракта через кошелек, то есть вызов соответствующей инструкции
* Экстренный вывод средств

### Оплата gas:

* Gas оплачивает владелец контракта, то есть сам пользователь, `Owner wallet`.

Адрес владельца контракта можно увидеть на основной странице счета в карточке `Linked to wallet`. Адрес кошелька владельца также доступен в backoffice на странице пользователя при нажатии на плитку счета.

## Controller (controller authority)

Controller — это кошелек, `highload-wallet v3` с ротационным публичным ключом, которому делегированы права управления и выполнения операций от имени владельца. Он выполняет автоматические и операционные задачи, которые неудобно или невозможно возложить непосредственно на пользователя.

### Адреса контроллера:

* [4XzRdcK1M1koygnvS51V9YfuQzyJMLWDZqJQ73Jymg59](https://solscan.io/account/4XzRdcK1M1koygnvS51V9YfuQzyJMLWDZqJQ73Jymg59) - SOL controller

### Доступные действия:

* Создание новых счетов — после создания Controller передает роль `Wallet authority` кошельку клиента
* Обработка платежей
* Обработка clearing-операций
* Закрытие счетов — может закрыть счет сразу, не дожидаясь `Graceful period`
* Синхронизация баланса контракта после прямого пополнения
* Вывод средств на внешние счета — может подписывать такие выводы со своей стороны

### Оплата gas:

* Gas за эти операции оплачивает владелец Controller со своего баланса. Эта роль принадлежит Holders, то есть gas фактически оплачивает сам сервис Holders, поэтому важно следить за балансом контроллера.

## Treasure authority

Treasure wallets — это кошельки Holders, на которые переводятся средства, [USDC](https://www.circle.com/usdc) или [TON](https://ton.org/en), после обработки clearing-операций. Это тоже смарт-контракты, но с ограниченными правами. Только `Treasure authority` может выполнять действия с treasure wallets; у этого смарт-контракта нет `Wallet authority`.

### Доступные действия:

* Обработка refund-операций и reversal-операций из treasure wallets на клиентские счета
* Вывод средств из treasure wallets, только на адреса кошельков, указанные в whitelist

### Оплата gas:

* Gas за эти операции оплачивает `Treasure authority`, то есть Holders.

## Support authority

Эта роль отвечает за запуск исправлений в случае ошибок. Сейчас предусмотрено одно такое исправление: удаление некорректного адреса пополнения, который биржи иногда отправляют на `Associated Token Account`. В результате средства уходят не по тому адресу, и роль `Support authority` позволяет вручную удалять такие ошибочные адреса.

## Route owner (в TON — Owner, также известный как Treasure owner)

Это роль с административными правами над набором контрактов. Для Wallester у Holders есть root account в сети Solana, которым владеет `Route owner`.

### Доступные функции:

* Изменение `Treasure authority`
* Изменение `Support authority`
* Изменение `Controller`
* Настройка `Graceful period`, то есть времени вывода после закрытия счета
* Обновление whitelist для выводов из treasure wallets, включая добавление и исключение адресов

### Оплата gas:

* Gas за выполнение этих операций оплачивает `Route owner`, то есть Holders.

## Upgrade authority

Роль, имеющая право обновлять код контракта. В Solana можно сразу обновить код для всех контрактов, связанных с аккаунтом.\
Согласно внутренней политике Holders, обновления не должны затрагивать состояние контракта, чтобы сохранять целостность данных, однако изменения в логике контракта допускаются.

# Основные операции и сценарии

### 1. **Развертывание (**`deploy`**)**

* Создает новый аккаунт и инициализирует параметры: `seed`, адреса и `controller`.
* Проверяет корректность `seed`, соответствие адресов, сохраняет параметры, устанавливает лимиты и состояния.
* Возвращает подтверждение успешного деплоя.

### 2. **Пополнение (**`topup`**)**

* Зачисляет средства на пользовательский баланс.
* Проверяет корректность вызывающей стороны и лимитов.
* Обновляет отображаемый баланс и отправляет подтверждение.

### 3. **Выполнение транзакции (**`execute`**)**

* Самая важная функция — позволяет переводить средства, выполнять списания и обрабатывать clearing.
* Проверяет `seed`, `seqno`, время и статус аккаунта.
* Рассчитывает текущий баланс, проверяет разовые, дневные и месячные лимиты.
* Обновляет баланс, лимиты и состояние.
* Если аккаунт помечен как закрытый, инициирует автоматический вывод оставшихся средств.

### 4. **Обновление лимитов (**`update_limits`**)**

* Позволяет владельцу менять лимиты, разовые, дневные и месячные.
* Проверяет последовательность `seqno` и корректность лимитов.
* Обновляет очередь ожидающих лимитов, `pending limits queue`.

### 5. **Закрытие аккаунта (**`close`**)**

* Инициирует запрос на закрытие аккаунта.
* После истечения `timeout` автоматически выводит оставшиеся средства и переводит аккаунт в состояние `closed`.

### 6. **Обновление кода (**`update`**)**

Обеспечивает обновление смарт-контракта. При вызове:

* проверяется корректность версии, `revision`, и подписи владельца;
* если проверки проходят, код контракта обновляется без потери состояния;
* это позволяет добавлять новые функции, исправлять ошибки и развивать систему.

### 7. **Вывод USDC на привязанный кошелек (**`withdraw_usdc`**)**

* В системе есть функции для вывода [USDC](https://www.circle.com/usdc).
* Обязательные проверки авторизации обеспечивают безопасный вывод актива в соответствии с правилами и текущим состоянием аккаунта.

### 8. **Вывод USDC на внешний аккаунт**

* Позволяет выводить средства на внешний аккаунт.
* Позволяет переводить средства между аккаунтами внутри системы.

# Gas

### Создание и обслуживание контракта

В Holders при создании контрактов в Solana используется [RentExemption](https://solana.com/docs/core/accounts) — предоплата за 2 года, которая навсегда резервирует место. Стоимость [RentExemption](https://solana.com/docs/core/accounts) в Solana зависит от размера хранилища, в байтах, и текущей ставки аллокации в сети. В среднем цена составляет примерно 0.0023 SOL на каждые 10 kB. При закрытии аккаунта можно запросить возврат этой стоимости, поскольку аллокация больше не нужна.\
Примерная цена создания такого контракта — **около 0.015 SOL, это 1.5 USD при курсе Sol/USDT \$100**.

### Gas за пополнение

Чтобы ускорять транзакции в сети Solana, подключен механизм [Priority Fee](https://solana.com/docs/core/fees) — дополнительная комиссия, повышающая вероятность подтверждения при высокой нагрузке. Это позволяет обрабатывать транзакции быстрее. Пользователь оплачивает gas только при пополнении контракта; все остальные платежи уже покрываются сервисом. Gas за пополнение аккаунта в Solana фиксирован и составляет **0.000005 SOL, это 0.00005 USD при курсе Sol/USDT \$100**.

# Особенности реализации

### 1. Структура состояния и сериализация данных

Контракт использует внутренние методы `load_data()` и `store_data()` для сериализации и десериализации состояния. Все важные параметры, балансы, лимиты, статус и таймауты, хранятся в структурированном виде в памяти блока. Важно: корректное использование этих методов критично для целостности данных.

### 2. Управление лимитами через `pending_limits_queue`

Лимиты операций, разовые, дневные и месячные, реализованы через `pending_limits_queue`. Это позволяет обновлять лимиты асинхронно, одновременно проверяя последовательность `seqno`.\
Обновление лимитов происходит только через вызовы `update_limits`, с проверкой корректности `seqno` и допустимости изменений.

### 3. Механизм закрытия аккаунта

Закрытие аккаунта реализовано в два этапа:\
**RequestCloseA:** пользователь вызывает запрос на закрытие, аккаунт переходит в состояние `closure requested`, после чего задается `timeout`.\
**Automatic withdrawal:** после истечения `timeout` все оставшиеся средства выводятся автоматическим вызовом функции `close`, а аккаунт переводится в состояние `closed`. Это обеспечивает безопасность и автоматизацию процедуры закрытия.

### 4. Проверка и авторизация

Все операции требуют авторизации — либо владельца, `owner`, через подпись, либо `controller`. Важно соблюдать правильный порядок вызова методов и проверять подписи, чтобы избежать несанкционированных действий.

### 5. Работа с балансами и резервированием

Баланс внутри контракта управляется с помощью переменных `deposited`, `transferred`, `withdrawn`. Перед любыми операциями выполняется резервирование, `raw_reserve()`, чтобы гарантировать корректный учет и избежать переполнения или нехватки средств.

### 6. Обновление кода (upgrade)

Обновления выполняются через метод `update`, который проверяет `revision` и подпись владельца. После успешной проверки код контракта заменяется без сброса состояния и данных.

### 7. Взаимодействие с внешней инфраструктурой

Функции `do_send_message()` и `do_send_token_message()` используются для проведения операций и отправки транзакций. Все транзакции требуют достаточного объема gas и корректной подписи. При ошибках транзакции отклоняются и вызывается соответствующая ошибка.

### 8. Обработка ошибок

Контракт содержит множество проверок и ошибок, например для нарушения лимитов, некорректных `seed`, таймаутов или неверных подписей. Чтобы избежать ошибок исполнения, важно соблюдать правила вызова.

### 9. Обеспечение безопасности

Контракт использует проверку подписей, `has_one`, а также корректное управление `seeds` и `bump` для защиты от несанкционированных действий. Участники должны внимательно контролировать приватные ключи и соблюдать процедуры вызова.

# Структура данных и хранение

### Основные поля хранилища (`state`):

* **Время и последовательность**:
  * `ctx_seqno`: порядковый номер транзакции.
  * `ctx_last_state_at`: время последнего обновления состояния.
  * `ctx_deadline`: таймауты закрытия.
* **Показатели баланса**:
  * `ctx_deposited_a`, `ctx_deposited_b`: суммы депозитов.
  * `ctx_transferred_a`, `ctx_transferred_b`: переводы между аккаунтами.
  * `ctx_withdrawn_a`, `ctx_withdrawn_b`: суммы выведенных средств.
* **Статус и состояние**:
  * `ctx_state`: состояние аккаунта, `open`, `closed`, `closure requested`.
  * `ctx_seed`: уникальный `seed` для сообщений.
  * `ctx_tz_offset`, `ctx_close_timeout`: настройки таймзоны и таймаута.
* **Лимиты**:
  * В `ctx_limits`: ограничения операций, сохраненные лимиты, расходы, дедлайны и очередь ожидающих лимитов.

### Адреса и ключи:

* `ctx_address_a`, `ctx_address_b`: адреса owner и treasure.
* `ctx_controller`: роль controller.
* `ctx_token_mint`: `mint` для USDC.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.