Self-Custody Use Case (XLM)

Данный гайд иллюстрирует создание секретов, синхронизацию адресов, получение баланса и отправку транзакции из клиентского приложения-кошелька в рамках сценария Self-Custody с использованием Spatium Signer Service.

Инициализация

Для взаимодействия со Spatium Signer Client необходимо предоставить следующие данные:

auth - сессия авторизации (AuthorizationSession)
storage - (StorageDirver) отвечающий за хранение клиентского секрета

import { MemoryStorageDriver, SpatiumCrypto } from '@spatium/sdk';
import { AuthorizationSession, ServiceStorage, SignerClient } from '@spatium/signer-client';

export const createSignerClient = (auth: AuthorizationSession) => {
    const storage = new ServiceStorage('https://cloud.spatium.net/storage/v1', auth);

    const cache = new MemoryStorageDriver()
    const crypto = new SpatiumCrypto(cache, storage)

    return new SignerClient('https://cloud.spatium.net/signer/v1', auth, crypto, 10 * 1000);  
};

Важно! В данном примере в качестве хранилища используется ServiceStorage, который размещает оба секрета на стороне Spatium. Использование данного формата подразумевает, что кошелек является кастодиальным. Не рекомендуется к использованию в продакшене.

Генерация секрета

Для пользования распределенным кошельком необходимо создать постоянную пару из клиентского и серверного секретов и обеспечить их надежное хранение. На стороне Spatium Signer Service управление секретом происходит автоматически, а на стороне клиента разработчик должен имплементировать стабильный StorageDirver самостоятельно. В обоих случаях секрет привязывается к идентификатору секрета (secretId) и после создания доступен по нему. У одного пользователя может быть любое количество секретов, однако так как нужно обеспечить их сохранность и возможность восстановления, рекомендуется использовать один секрет на пользователя.

Для резервного копирования секретов на случай утраты содержимого StorageDirver рекомендуется использовать функционал экспорта и импорта.

export const ensureSecret = async (signerClient: SignerClient, secretId: string) => {
  if (await signerClient.crypto.checkSecret(secretId)) {
    return;
  }

  try {
    // Ожидаем установки соедения 
    await signerClient.connect(10 * 1000);

    await signerClient.generateDistributedSecret(secretId);
  } finally {
    await signerClient.disconnect();
  }
};

Важно! На данном этапе разработки SDK рекомендуется использовать подобный подход при обращении к сервису, т.е. с подключением непосредственно перед взаимодействием и отключением после. Это позволит избежать распространенных сетевых ошибок пока они не будут полностью устранены.

Синхронизация адресов валют

Адрес валюты необходим для получения ассетов и запроса информации о балансе, поэтому рекомендуется сразу синхронизировать его при создании кошелька.

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

Каждая новая процедура синхронизации привязывается к уникальному идентификатору и ее результаты записываются в предоставленный StorageDirver, что дает возможность (имея сохраненный syncSessionId) синхронизировать ключ один раз и затем пользоваться результатами постоянно. Однако утрата данных синхронизации не несет долгосрочных последствий, так как ничего не мешает провести синхронизацию еще раз и получить при этом тот же самый публичный ключ и, соответственно, адреса.

Для процедуры синхронизации необходимы следующие данные:

secretId - идентификатор секрета, служащего энтропией данного кошелька. На момент синхронизации секреты должны быть уже сгенерированы;
syncSessionId - идентификатор сессии синхронизации. В случае совпадения предыдущая сессия с таким идентификатором будет перезаписана;
curve - эллиптическая кривая. Для всех xlm это ed25519;
derivationCoin - параметр HD деривации ключа, непосредственно влияет на результат генерации адреса. Уникальные значения приводят к генерации уникальных ключей. Рекомендуется использовать фиксированное значение для конкретной криптосистемы, а варьировать значение ключа следующим параметром;
derivationAccount - параметр HD деривации ключа, непосредственно влияет на результат генерации адреса. Уникальные значения приводят к генерации уникальных ключей.

import { syncDistributedEddsaKey, getEddsaPublicKey } from '@spatium/sdk';

export const ensureEddsaPublicKey = async (signerClient: SignerClient, secretId: string, syncSessionId: string, derivationCoin: number, derivationAccount: number): Promise<string> => {
  const publicKey = await getEddsaPublicKey(signerClient, secretId, syncSessionId).catch(() => null);
  if (publicKey) {
    return publicKey;
  }

  try {
    // Ожидаем установки соедения 
    await signerClient.connect(10 * 1000);

    const distributedEddsaKey = await syncDistributedEddsaKey(signerClient, secretId, syncSessionId, 'secp256k1', derivationCoin, derivationAccount);
    return distributedEddsaKey
  } finally {
    await signerClient.disconnect();
  }
};

Для получения из публичного ключа адреса в конкретном блокчейне рекомендуется использовать Blockchain Connector Service.

import axios from 'axios';
import { randomBytes, uuid } from '@spatium/sdk';

type XlmGetAddressRequest = {
  network?: 'livenet' | 'testnet';
  publicKey: string;
  prefix?: boolean;
};
type XlmGetAddressResponse = {
  requestId: string;
  data: { address: string };
}

export const xlmGetAddress = async (
  auth: AuthorizationSession,
  { network, publicKey, prefix }: XlmGetAddressRequest,
): Promise<XlmGetAddressResponse['data']> => {
  const token = await auth.getPermissionToken();

  const response = await axios.post(
    `https://cloud.spatium.net/blockchain-connector-xlm/v1/api/get-address/xlm`,
    {
      publicKey,
      network,
      prefix,
    },
    {
      headers: {
        'request-id': uuid(randomBytes),
        'authorization': `Bearer ${token}`,
      },
    },
  ).then((result) => result.data);

  return response.data;
};

Важно! Для того, чтобы при утрате данных в StorageDirver можно было однозначно восстановить все адреса со всеми средствами пользователя, нужно обеспечить бэкап клиентского секрета и внешнее хранение параметров генерации адресов, а именно:

secretId - данные генерации, также нужно хранить вместе с бэкапом секрета

curve - данные генерации

derivationCoin - данные генерации

derivationAccount - данные генерации

Получение информации об адресе

Имея синхронизированный адрес (или любой другой) можно обратиться к Address Info Service для получения развернутой информации об адресе, включая баланс в различных ассетах и историю транзакций.

import axios from 'axios';
import { randomBytes, uuid } from '@spatium/sdk';

type XlmGetAddressRequest = {
  network?: 'livenet' | 'testnet';
  address: string;
};
type XlmGetAddressResponse = {
  requestId: string;
  data: AddressInfo;
};

export const xlmGetAddressInfo = async (
  auth: AuthorizationSession,
  { network, address }: XlmGetAddressRequest,
): Promise<XlmGetAddressResponse['data']> => {
  const token = await auth.getPermissionToken();

  const result = await axios.get(
    `https://cloud.spatium.net/address-info-xlm-service/v1/api/xlm`,
    {
      params: { network, address },
      headers: {
        'request-id': uuid(randomBytes),
        'authorization': `Bearer ${token}`,
      },
    },
  ).then((result) => result.data);

  return result.data;
};

Подпись транзакции

Подпись транзакции включает в себя несколько этапов:

Оценка комиссии транзакции;
Формирование хэша транзакции;
Подпись хэша транзакции;
Формирование подписанной транзакции;
Отправка транзакции в блокчейн.

Из всех этих этапов только подпись хэша транзакции выполняется при помощи SDK, остальное предоставляется через API Blockchain Connector Service.

Информация о комиссии

Для указания максимального размера комиссии при формировании транзакции полезно ориентироваться на статистику текущих комиссий сети

Примечание

Существуют различные стратегии формирования максимальной комиссии, однако стоит учитывать, что транзакция с невысокой максимальной комиссией не будет обработана при нагрузке на сеть, поэтому мы ориентируем пользователей на значение статистической максимальной комиссии с добавлением небольшого запаса - текущей минимальной комиссии за операцию (feeCharged.max + lastLedgerBaseFee), при этом оставляя возможность указать любое значение комиссии вручную. Больше информации о получении комисии сети можно найти тут

import axios from 'axios';
import { randomBytes, uuid } from '@spatium/sdk';

type XlmGetFeeStatRequest = {
  network?: 'livenet' | 'testnet';
};

type XlmGetFeeStatResponse = {
  requestId: string;
  data: { 
    lastLedgerBaseFee: string;
    feeCharged: {
      min: string,
      max: string,
    } 
  };
};

export const xlmGetFeeStat = async (
  auth: AuthorizationSession,
  { network }: XlmGetFeeStatRequest
): Promise<XlmGetFeeStatResponse['data']> => {
  const token = await auth.getPermissionToken();

  const response = await axios.get(
    `https://cloud.spatium.net/blockchain-connector-xlm/v1/api/prepare-transaction/fee-stat/xlm`,
    {
      params: { network },
      headers: {
        'request-id': uuid(randomBytes),
        'authorization': `Bearer ${token}`,
      },
    },
  ).then((result) => result.data);

  return response.data;
};

Формирование хэша для подписи

Имея все предварительные данные, можно формировать хэш для подписи.

В XLM получение хэша отличачется в зависимости от типа транзакции:

Отправка валюты
Добавление трастлайна
Принятие claimableBalance

Формирование хэша для подписи транзакции отправки валюты

Важно

В соответствии с логикой работы сети Stellar нельзя отправить валюту на несуществующий в сети аккаунт (необходимо сначала создать этот аккаунт). Данный эндпоинт автоматически определяет наличие аккаунта в сети и и при необходимости создает его, предупреждения об отсутствии аккаунта в сети не будет! Подробнее про формирование хэша для подписи транзакции отправки валюты можно узнать тут.

import axios from 'axios';
import { randomBytes, uuid } from '@spatium/sdk';

type XlmGetHashTransferRequest = {
  network?: 'livenet' | 'testnet';
  publicKey: string;
  to: string,
  amount: string,
  asset?: object;
  fee: string;
  memo?: string;
 };

type XlmGetHashTransferResponse = {
  requestId: string;
  data: {
    unsignedMessage: string;
    hash: string;
  }
};

export const xlmGetHashTransfer = async (
  auth: AuthorizationSession,
  { network, publicKey, to, amount, asset, fee, memo }: XlmGetHashTransferRequest,
): Promise<XlmGetHashTransferResponse['data']> => {
  const token = await auth.getPermissionToken();

  const response = await axios.post(
    'https://cloud.spatium.net/blockchain-connector-xlm/v1/api/transaction/get-hash/xlm/transfer',
    {
      network,
      publicKey,
      to,
      amount,
      asset,
      fee,
      memo,
    },
    {
      headers: {
        'request-id': uuid(randomBytes),
        'authorization': `Bearer ${token}`,
      },
    },
  ).then((result) => result.data);

  return response.data;
};

Формирование хэша для подписи транзакции добавления трастлайна

import axios from 'axios';
import { randomBytes, uuid } from '@spatium/sdk';

type XlmGetHashAddTrustlineRequest = {
  network?: 'livenet' | 'testnet';
  publicKey: string;
  to: string,
  amount?: string,
  asset: string;
  fee: string;
  memo?: string;
 };

type XlmGetHashAddTrustlineResponse = {
  requestId: string;
  data: {
    unsignedMessage: string;
    hash: string;
  }
};

export const xlmGetHashAddTrustline = async (
  auth: AuthorizationSession,
  { network, publicKey, to, amount, asset, fee, memo }: XlmGetHashAddTrustlineRequest,
): Promise<XlmGetHashAddTrustlineResponse['data']> => {
  const token = await auth.getPermissionToken();

  const response = await axios.post(
    'https://cloud.spatium.net/blockchain-connector-xlm/v1/api/transaction/get-hash/xlm/add-trustline',
    {
      network,
      publicKey,
      to,
      amount,
      asset,
      fee,
      memo,
    },
    {
      headers: {
        'request-id': uuid(randomBytes),
        'authorization': `Bearer ${token}`,
      },
    },
  ).then((result) => result.data);

  return response.data;
};

Формирование хэша для подписи транзакции принятия claimableBalance

import axios from 'axios';
import { randomBytes, uuid } from '@spatium/sdk';

type XlmGetHashClaimRequest = {
  network?: 'livenet' | 'testnet';
  publicKey: string;
  claimableBalanceId: string,
  fee: string;
  memo?: string;
 };

type XlmGetHashClaimResponse = {
  requestId: string;
  data: {
    unsignedMessage: string;
    hash: string;
  }
};

export const xlmGetHashClaim = async (
  auth: AuthorizationSession,
  { network, publicKey, claimableBalanceId, fee, memo }: XlmGetHashClaimRequest,
): Promise<XlmGetHashClaimResponse['data']> => {
  const token = await auth.getPermissionToken();

  const response = await axios.post(
    'https://cloud.spatium.net/blockchain-connector-xlm/v1/api/transaction/get-hash/xlm/claim',
    {
      network,
      publicKey,
      claimableBalanceId,
      fee,
      memo,
    },
    {
      headers: {
        'request-id': uuid(randomBytes),
        'authorization': `Bearer ${token}`,
      },
    },
  ).then((result) => result.data);

  return response.data;
};

SMPC подпись хэша

import { signEddsaMessage } from '@spatium/sdk';
import { randomBytes, uuid } from '@spatium/sdk';

export const signEddsa = async (signerClient: SignerClient, secretId: string, syncSessionId: string, message: string): Promise<EddsaSignature> => {
  const signSessionId = uuid(randomBytes);

  try {
    // Ожидаем установки соедения 
    await signerClient.connect(10 * 1000);

    return await signerClient.signEddsaMessage(secretId, syncSessionId, signSessionId, message);
  } finally {
    await signerClient.disconnect();
  }
};

Формирование подписанной транзакции

Подпись нужно прикрепить к транзакции, тем самым получив данные, готовые к отправке в блокчейн.

import axios from 'axios';
import { randomBytes, uuid } from '@spatium/sdk';

type XlmAttachSignatureRequest = {
  network?: 'livenet' | 'testnet';
  publicKey: string;
  unsignedMessage: string;
  signature: EddsaSignature,
};

type XlmAttachSignatureResponse = {
  requestId: string;
  data: { txdata: string };
};

export const xlmAttachSignature = async (
  auth: AuthorizationSession,
  { network, publicKey, unsignedMessage, signature }: XlmAttachSignatureRequest,
): Promise<XlmAttachSignatureResponse['data']> => {

  const response = await axios.post(
    `https://cloud.spatium.net/blockchain-connector-xlm/v1/api/transaction/attach-signature/xlm`,
    {
      network,
      publicKey,
      unsignedMessage,
      signature,
    },
    {
      headers: {
        'request-id': uuid(randomBytes),
        'authorization': `Bearer ${token}`,
      },
    },
  ).then((result) => result.data);

  return response.data;
};

Отправка транзакции в сеть

За отправку транзакции в блокчейн также отвечает Blockchain Connector Service

import axios from 'axios';
import { randomBytes, uuid } from '@spatium/sdk';

type XlmSendTXRequest = {
  txdata: string;
};
type XlmSendTXResponse = {
  requestId: string;
  data: { txid: string };
};

export const xlmSendTX = async (
  auth: AuthorizationSession,
  { txdata }: XlmSendTXRequest,
): Promise<XlmSendTXResponse['data']> => {
  const token = await auth.getPermissionToken();

  const response = await axios.post(
    `https://cloud.spatium.net/blockchain-connector-xlm/v1/api/transaction/send/xlm`,
    {
      txdata,
    },
    {
      headers: {
        'request-id': uuid(randomBytes),
        'authorization': `Bearer ${token}`,
      },
    }
  ).then((result) => result.data);

  return response.data;
};

Полная процедура

import { AuthorizationSession, SignerClient } from '@spatium/signer-client';
import { randomBytes, uuid } from '@spatium/sdk';

const auth = new AuthorizationSession('https://cloud.spatium.net/authorization/v1', uuid(randomBytes), ['read', 'secret']);

// получение security токенов
const { data: { securityToken } } = await axios.post('https://cloud.spatium.net/authorization/v1/api/security-factor/credentials', {
    username: 'username', password: 'password',
  }, {
    headers: {
      'request-id': uuid(randomBytes),
    },
  }).then(({ data }) => data);

await auth.establish([securityToken]);

const etcLikeSignTransaction = async (auth: AuthorizationSession, signerClient: SignerClient, secretId: string, syncSessionId: string, publicKey: string, to: string, amount: string) => {

  const { address } = await xlmGetAddress(auth, { publicKey })

  const { feeCharged } = await xlmGetFeeStat(auth, {});
  const fee = feeCharged.max;

  // получение хэша транзакции отправки валюты
  const { hash, unsignedMessage } = await xlmGetHashTransfer(auth, { publicKey, to, amount, fee });

    // получение хэша транзакции добавления трастлайна
  const { hash, unsignedMessage } = await xlmGetHashAddTrustline(auth, { publicKey, asset, fee });

  // получение хэша транзакции получения claimableBalance
  const { hash, unsignedMessage } = await xlmGetHashClaim(auth, { publicKey, claimableBalanceId, fee });

  const signature = await signEddsa(signerClient, secretId, syncSessionId, hash);

  const { txdata } = await xlmAttachSignature(auth, { publicKey, unsignedMessage, signature });

  const { txid } = await xlmSendTX(auth, { txdata });

  return txid;
}