ArteMm.baka `へ´

как мы (не) вынесли sui quest 3 на миллион аккаунтов

2023-11-17T08:16:04.069Z

привет, я artemm.baka, а эта статья про нашу недельную историю о sui квесте, которая началась в конце октября. время прочтения 5 минут. gl hf.

Навигация по статье:

1. начало

2. билдинг и реверс-инжиниринг

3. минт квест пассов и первые проблемы

4. переобувка sui и следующая проблема

5. итоги и ошибки

1. начало

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

однако мой коллега с ds_private яна мефе не забыл и предложил реверсить игрушку, а точнее мега кривой лаунчер worlds beyound.

для тех кто не знает что за worlds beyound и почему именно он? если кратко, во время quest 3 было много "даппок", обязательно нужно было сделать 3 из них и набрать суммарно 2500 поинтов.

супер дапки

мы взяли две гемблинг аппки (suilette и desuiflip) + сам wb. многие в комьюнити также софтили run legends. и там же кстати админы раньше всего заметили читеров. мы же решили эту игру скипнуть.

2. билдинг и реверс-инжиниринг

спустя еще два дня собрались мы втроем: я, яна и кису с dd dao, чтобы разделить обязанности и сделать все побыстрее. я занялся играми в wb и минтом квест пасса. яна делал казино аппки. а кису регу на лаунчер wb. и естественно все втроем занимались РеВеРс-ИнЖиНиРиНгОм.

в лаунчере было несколько игр, как офлайн, так и онлайн. проксифаером чекнули запросы во всех, везде +- одни и те же запросы, а в хедерах jwt токен и signature. с первым проблем нет. кстати их refresh токен после обновления не обнулялся, что забавно. гениальные кодеры на админах.

а вот со вторым проблемы возникли и мы полезли копаться в коде лаунчера с помощью dnSpy, а потом через dotPeek. хотя они и не сильно отличаются, но второй оказался лучше в декомпиляции. короче, спасибо за детство, JetBrains.

так выглядела функция генерации сигнатуры на C#, которую мы нашли, короче просто HMACSHA256.

private static string GenerateHash(string content)
{
  using (MemoryStream inputStream = new MemoryStream(Encoding.ASCII.GetBytes(content)))
  {
    byte[] hash = new HMACSHA256(Encoding.ASCII.GetBytes("S0lBZsuidaidropIQ1ZCQUhEBw==")).ComputeHash((Stream) inputStream);
    StringBuilder stringBuilder = new StringBuilder(hash.Length * 2);
    foreach (byte num in hash)
      stringBuilder.AppendFormat("{0:x2}", (object) num);
    return stringBuilder.ToString();
  }
}

а так выглядит теперь на typescript.

const HMAC = 'S0lBZsuidaidropIQ1ZCQUhEBw==';

function generateHash(data: object): string {
  return CryptoJS.HmacSHA256(JSON.stringify(data), HMAC).toString();
}

что за S0lBZsuidaidropIQ1ZCQUhEBw== думаю понятно (ключ).

но что за дата? в поисках ответа на этот вопрос я полез в ассемблер (IDA Pro), провел там пару часов, научился прикольным штукам и весело `へ´ провел время. но ответ оказался намного проще.

спустя время до нас все же дошло, что контент/дата для нужных нам запросов берется из даты этих самых запросов. спасибо C# коду и unity uploadHandler.

кстати, все онлайн игры работали через встроенный вебсокет менеджер в unity, следовательно, девы ничего не контролировали, но мы решили сделать офлайн игры для "уменьшения рисков", хотя они и давали поменьше поинтов чем онлайн.

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

3. минт квест пассов и первые проблемы

пока друзья доделывают регу и гемблинг, я делаю газлесс (спонсорский как на сайте) минт квест пассов.

сделать газ минт - легко, как и в любом move блокчейне (просто .moveCall и все). сделать спонсорский минт (без газа) - чуточку сложнее. но на самом деле нужно было просто немного посидеть подумать и почитать sui доку.

со спонсорским минтом 1 аккаунт выходил 0.1$ (за прокси) + ~0.2$ в sui на другие активности = ~0.3$. с каждого акка получаем 25 sui, итого x50-x100.

4 ноября наш софт на 2к строк готов, но нас обгоняет другой софтер и регает 140к+ акков в wb - обычные юзеры это замечают, а позже и сами админы.

клейм поинтов на сайте wb перестает работать, а потом и обязательный линк sui кошелька. раньше, конечно, тоже все супер ужасно работало, но сейчас же фулл упало. плюс админы пишут, что будут перераспределять поинты.

)

до сих неизвестно как они будут брить, с учетом того, что админы не смогли сделать ничего нормально. ни бекенд (про RESTful вообще молчу, у них код 200 это ошибка, о чем речь), ни фронтенд.

кстати, вот так в wb выглядит пейлоад для регистрации.

{
  username: 'username',
  email: 'email',
  name: 'name',
  password: 'password',
  confirmPassword: 'password',
  dateOfBirth: 'dateOfBirth'
}

confirmPassword - интересное и совсем не ненужное поле. и таких приколов у них очень много.

предполагаю, будет бритва либо по самым банальным критериям, либо фулл несправедливые баны даже не сибилов.

4. переобувка sui и следующая проблема

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

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

но через несколько дней sui анонсят, что больше квест пассов не будет, "минтите наши другие (платные) нфт". премного благодарю, sui team.

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

и чуть позже суи еще убирает лимиты по рефам у "настоящих пользователей". интересно зачем, да?

лучшие

5. итоги и ошибки

что мы имеем? гениальных девов в sui играх с серверами за 5€ на contabo. wb лаунчер, который собирает бесконечность данных с твоего пк и кривым бекендом "работающем" в 1 из 100 случаев. и, конечно же, прекрасную команду sui.

наши ошибки:

поздно начали, но на то была уважительная причина (просто оправдание)
можно было ускорить разработку не делая лишние действия (то есть без перфекционизма)
минт квест пассов, регу и линк в wb стоило сделать первыми или делегировать кому-то еще

да мы не сделали миллион аккаунтов, но получили интересный опыт и пару синяков под глазами.

да немного кликбейт уж прости

спасибо, что читал, люблю! ❤️

Три всадника апокалипсиса: создание NFT коллекций на Aptos, Sui и Solana

2022-09-17T16:07:14.000Z

Всем привет! С вами ArteMm aka Скамушка ツ

В этой статье мы создадим простые NFT коллекции на Aptos, Sui и Solana. Но стоит понимать, что первые два блокчейна ещё активно разрабатываются и следовательно этот туториал интересен только для ознакомления, т. к. некоторые вещи могут в любой момент поменяться.

Навигация по статье:

1. Aptos

1.1. Подготовка
1.2. Инициализация клиентов
1.3. Создание локальных аккаунтов
1.4. Создание блокчейн аккаунтов
1.5. Создание коллекции
1.6. Создание токена
1.7. Чтение метаданных токена и коллекции
1.8. Чтение баланса токенов
1.9. Предложение и получение токена
1.10. Безопасная односторонняя передача токена

2. Sui

2.1. Подготовка
2.2. Реализация с помощью Sui CLI
2.3. Реализация с помощью смарт-контракта

3. Solana

3.1. Подготовка
3.2. Настройка проекта
3.3. Создание конфига и публикация CM2
3.4. Минт NFT

4. Справочник

1. Aptos

1.1. Подготовка

Убедитесь, что у вас установлен Node.js (>=16.10) и включен Corepack.

corepack enable

Установите зависимости.

yarn add aptos dotenv && yarn add ts-node typescript @types/node -D

1.2. Инициализация клиентов

На первом этапе в примере инициализируются API и faucet (кран) клиенты.

Клиент API взаимодействует с REST API
Клиент faucet взаимодействует с сервисом devnet Faucet для создания и пополнения аккаунтов.

Создайте файл index.ts и добавьте импорты:

import dotenv from 'dotenv';

import {
  AptosClient, AptosAccount, FaucetClient, TokenClient,
} from 'aptos';
import { NODE_URL, FAUCET_URL } from './common';

dotenv.config();

А потом:

(async () => {
  const client = new AptosClient(NODE_URL);
  const faucetClient = new FaucetClient(NODE_URL, FAUCET_URL);

  const tokenClient = new TokenClient(client);

Используя клиент API, мы можем создать TokenClient, который мы используем для общих операций с токенами, таких как создание коллекций и токенов, их передача, получение и т. д.

  const alice = new AptosAccount();
  const bob = new AptosAccount();

В common.ts инициализируйте значения URL:

export const NODE_URL = process.env.APTOS_NODE_URL || 'https://fullnode.devnet.aptoslabs.com';
export const FAUCET_URL = process.env.APTOS_FAUCET_URL || 'https://faucet.devnet.aptoslabs.com';

По умолчанию URL-адреса обеих служб указывают на службы Aptos devnet. Однако их можно настроить с помощью следующих переменных окружения: APTOS_NODE_URL, APTOS_FAUCET_URL.

1.3. Создание локальных аккаунтов

Следующим шагом будет создание двух аккаунтов локально. Аккаунты представляют собой как on-chain, так и off-chain состояние. Оффчейн состояние состоит из адреса и пары открытого и закрытого ключей, используемых для аутентификации владельца. Этот шаг демонстрирует, как создать это оффчейн состояние (продолжаем в index.ts).

  const alice = new AptosAccount();
  const bob = new AptosAccount();

1.4. Создание блокчейн аккаунтов

В Aptos каждый аккаунт должен иметь ончейн представление, чтобы поддерживать получение токенов и монет, а также взаимодействие с другими dApps. Аккаунт представляет собой средство для хранения активов, поэтому он должен быть явно создан. В данном примере кран используется для создания аккаунтов Алисы и Боба. Финансируется только Алиса:

  await faucetClient.fundAccount(alice.address(), 20_000);
  await faucetClient.fundAccount(bob.address(), 20_000);

1.5. Создание коллекции

Теперь начинается процесс создания токенов. Во-первых, создатель должен создать коллекцию для хранения токенов. Коллекция может содержать ноль, один или много различных токенов. Коллекция не ограничивает атрибуты токенов, так как это всего лишь контейнер.

Ваше приложение будет вызывать createCollection:

  const collectionName = "Alice's";
  const tokenName = "Alice's first token";
  const tokenPropertyVersion = 0;

  const txnHash1 = await tokenClient.createCollection(
    alice,
    collectionName,
    "Alice's simple collection",
    'https://alice.com',
  );
  await client.waitForTransaction(txnHash1, { checkSuccess: true });

Сигнатура метода createCollection. Он возвращает хэш транзакции:

async createCollection(
  account: AptosAccount,
  name: string,
  description: string,
  uri: string,
  maxAmount: BCS.AnyNumber = MAX_U64_BIG_INT,
): Promise<string> {

1.6. Создание токена

Ваше приложение будет вызывать createToken:

  const txnHash2 = await tokenClient.createToken(
    alice,
    collectionName,
    tokenName,
    "Alice's simple token",
    1,
    'https://aptos.dev/img/nyan.jpeg',
  );
  await client.waitForTransaction(txnHash2, { checkSuccess: true });

Сигнатура метода createToken. Он возвращает хэш транзакции:

async createToken(
  account: AptosAccount,
  collectionName: string,
  name: string,
  description: string,
  supply: number,
  uri: string,
  max: BCS.AnyNumber = MAX_U64_BIG_INT,
  royalty_payee_address: MaybeHexString = account.address(),
  royalty_points_denominator: number = 0,
  royalty_points_numerator: number = 0,
  property_keys: Array<string> = [],
  property_values: Array<string> = [],
  property_types: Array<string> = [],
): Promise<string> {

1.7. Чтение метаданных токена и коллекции

Метаданные коллекции и токена хранятся на аккаунте создателя в его Collections в таблице. SDKs предоставляют удобные обертки для запросов к этим конкретным таблицам.

Чтобы прочитать метаданные коллекции:

  const collectionData = await tokenClient.getCollectionData(alice.address(), collectionName);
  console.log(`Alice's collection: ${JSON.stringify(collectionData, null, 4)}`);

Чтобы прочитать метаданные токена:

  const tokenData = await tokenClient.getTokenData(alice.address(), collectionName, tokenName);
  console.log(`Alice's token data: ${JSON.stringify(tokenData, null, 4)}`);

Вот как getTokenData запрашивает метаданные токена:

async getTokenData(
  creator: MaybeHexString,
  collectionName: string,
  tokenName: string,
): Promise<TokenTypes.TokenData> {
  const creatorHex = creator instanceof HexString ? creator.hex() : creator;
  const collection: { type: Gen.MoveStructTag; data: any } = await this.aptosClient.getAccountResource(
    creatorHex,
    "0x3::token::Collections",
  );
  const { handle } = collection.data.token_data;
  const tokenDataId = {
    creator: creatorHex,
    collection: collectionName,
    name: tokenName,
  };

  const getTokenTableItemRequest: Gen.TableItemRequest = {
    key_type: "0x3::token::TokenDataId",
    value_type: "0x3::token::TokenData",
    key: tokenDataId,
  };

  // Мы знаем, что ответом будет структура, содержащая TokenData, отсюда и неявное приведение.
  return this.aptosClient.getTableItem(handle, getTokenTableItemRequest);
}

1.8. Чтение баланса токенов

Каждый токен в Aptos является отдельным активом, активы, принадлежащие пользователю, хранятся в его TokenStore. Чтобы получить баланс:

  const aliceBalance1 = await tokenClient.getToken(
    alice.address(),
    collectionName,
    tokenName,
    `${tokenPropertyVersion}`,
  );
  console.log(`Alice's token balance: ${aliceBalance1.amount}`);

1.9. Предложение и получение токена

Многие пользователи получили нежелательные токены, которые могут вызвать как минимальный дискомфорт, так и серьезные последствия. Aptos дает право каждому владельцу аккаунта решать, принимать или не принимать односторонние переводы. По умолчанию односторонние переводы не поддерживаются. Таким образом, Aptos обеспечивает основу для предложения и клейма токенов.

Чтобы предложить (отправить) токен:

  const txnHash3 = await tokenClient.offerToken(
    alice,
    bob.address(),
    alice.address(),
    collectionName,
    tokenName,
    1,
    tokenPropertyVersion,
  );
  await client.waitForTransaction(txnHash3, { checkSuccess: true });

Чтобы получить токен:

  const txnHash4 = await tokenClient.claimToken(
    bob,
    alice.address(),
    alice.address(),
    collectionName,
    tokenName,
    tokenPropertyVersion,
  );
  await client.waitForTransaction(txnHash4, { checkSuccess: true });

1.10. Безопасная односторонняя передача токена

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

  const txnHash5 = await tokenClient.directTransferToken(
    bob,
    alice,
    alice.address(),
    collectionName,
    tokenName,
    1,
    tokenPropertyVersion,
  );
  await client.waitForTransaction(txnHash5, { checkSuccess: true });
})();

Теперь пробуем запустить:

npx ts-node index

Получаем вывод:

Alice's collection: {
    "description": "Alice's simple collection",
    "maximum": "18446744073709551615",
    "mutability_config": {
        "description": false,
        "maximum": false,
        "uri": false
    },
    "name": "Alice's",
    "supply": "1",
    "uri": "https://alice.com"
}
Alice's token data: {
    "default_properties": {
        "map": {
            "data": []
        }
    },
    "description": "Alice's simple token",
    "largest_property_version": "0",
    "maximum": "18446744073709551615",
    "mutability_config": {
        "description": false,
        "maximum": false,
        "properties": false,
        "royalty": false,
        "uri": false
    },
    "name": "Alice's first token",
    "royalty": {
        "payee_address": "0x3bb244826f49ac293aff101564c462c8e2046912dc8f581db655e2dbb5bffee6",
        "royalty_points_denominator": "0",
        "royalty_points_numerator": "0"
    },
    "supply": "1",
    "uri": "https://aptos.dev/img/nyan.jpeg"
}
Alice's token balance: 1

Готово! Достаточно просто. Полный код примера можно найти на GitHub. А тут можно увидеть оригинал туториала.

2. Sui

В Sui всё представляет из себя NFT — объекты уникальны, не взаимозаменяемы и принадлежат друг другу. Так что технически достаточно простой публикации. Я решил разобрать два способа создания NFT: простой с помощью Sui CLI и более гибкий с помощью смарт-контракта на языке Move.

2.1. Подготовка

Установите Sui и Git.

2.2. Реализация с помощью Sui CLI

Вы можете создать NFT-подобный объект на Sui, используя следующую команду:

sui client create-example-nft

Вы увидите вывод, похожий на:

Successfully created an ExampleNFT:

----- Move Object (0x524f9fae3ca4554e01354415daf58a05e5bf26ac[1]) -----
Owner: Account Address ( 0xb02b5e57fe3572f94ad5ac2a17392bfb3261f7a0 )
Version: 1
Storage Rebate: 25
Previous Transaction: 98HbDxEwEUknQiJzyWM8AiYIM479BEKuGwxrZOGtAwk=
----- Data -----
type: 0x2::devnet_nft::DevNetNFT
description: An NFT created by the Sui Command Line Tool
id: 0x524f9fae3ca4554e01354415daf58a05e5bf26ac[1]
name: Example NFT
url: ipfs://bafkreibngqhl3gaa7daob4i2vccziay2jjlp435cf66vhono7nrvww53ty

А вот так выглядит контракт DevNetNFT:

module sui::devnet_nft {
    use sui::url::{Self, Url};
    use std::string;
    use sui::object::{Self, ID, UID};
    use sui::event;
    use sui::transfer;
    use sui::tx_context::{Self, TxContext};

    /// Example NFT, который может заминтить кто угодно
    struct DevNetNFT has key, store {
        id: UID,
        /// Имя токена
        name: string::String,
        /// Описание токена
        description: string::String,
        /// URL токена
        url: Url,
        // Можно добавить кастомные аттрибуты
    }

    struct MintNFTEvent has copy, drop {
        // Идентификатор объекта NFT
        object_id: ID,
        // Создатель NFT
        creator: address,
        // Название NFT
        name: string::String,
    }

    /// Создать новый devnet_nft
    public entry fun mint(
        name: vector<u8>,
        description: vector<u8>,
        url: vector<u8>,
        ctx: &mut TxContext
    ) {
        let nft = DevNetNFT {
            id: object::new(ctx),
            name: string::utf8(name),
            description: string::utf8(description),
            url: url::new_unsafe_from_bytes(url)
        };
        let sender = tx_context::sender(ctx);
        event::emit(MintNFTEvent {
            object_id: object::uid_to_inner(&nft.id),
            creator: sender,
            name: nft.name,
        });
        transfer::transfer(nft, sender);
    }

    /// Обновить `description` у `nft` на `new_description`
    public entry fun update_description(
        nft: &mut DevNetNFT,
        new_description: vector<u8>,
        _: &mut TxContext
    ) {
        nft.description = string::utf8(new_description)
    }

    /// Навсегда удалить `nft`
    public entry fun burn(nft: DevNetNFT, _: &mut TxContext) {
        let DevNetNFT { id, name: _, description: _, url: _ } = nft;
        object::delete(id)
    }

    /// Получить NFT's `name`
    public fun name(nft: &DevNetNFT): &string::String {
        &nft.name
    }

    /// Получить NFT's `description`
    public fun description(nft: &DevNetNFT): &string::String {
        &nft.description
    }

    /// Получить NFT's `url`
    public fun url(nft: &DevNetNFT): &Url {
        &nft.url
    }
}

2.3. Реализация с помощью смарт-контракта

Теперь же создадим простую и очень проблемную коллекцию. За основу я взял контракт DevNetNFT и пример коллекции. Также упомяну, что мои знания в языке Move нулевые, спасало только то, что это Rust-подобный язык.

Сначала создайте пустой пакет Move:

sui move new my_nfts

Клонируйте репозиторий Sui:

git clone https://github.com/MystenLabs/sui.git

Обновите [dependencies] в файле Move.toml вот так:

[package]
name = "my_nfts"
version = "0.0.1"

[dependencies]
Sui = { local = "../sui/crates/sui-framework" }

[addresses]
my_nfts = "0x0"

А теперь создайте файл collection.move:

touch my_nfts/sources/collection.move

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

module my_nfts::collection {
    use sui::url::{Self, Url};
    use std::string;
    use sui::object::{Self, ID, UID};
    use sui::event;
    use sui::transfer;
    use sui::typed_id::{Self, TypedID};
    use sui::tx_context::{Self, TxContext};
    use sui::vec_set::{Self, VecSet};

    /// Example NFT, который может заминтить кто угодно
    struct MyNFT has key, store {
        id: UID,
        /// Имя токена
        name: string::String,
        /// Описание токена
        description: string::String,
        /// URL токена
        url: Url,
    }

    // ===== События =====

    struct MintNFTEvent has copy, drop {
        // Идентификатор объекта NFT
        object_id: ID,
        // Создатель NFT
        creator: address,
        // Название NFT
        name: string::String,
    }

    // ===== Public view функции =====

    /// Получить NFT's `name`
    public fun name(nft: &MyNFT): &string::String {
        &nft.name
    }

    /// Получить NFT's `description`
    public fun description(nft: &MyNFT): &string::String {
        &nft.description
    }

    /// Получить NFT's `url`
    public fun url(nft: &MyNFT): &Url {
        &nft.url
    }

    // ===== Entrypoints (точки входа) =====

    /// Создать новый my_nft (этот ентри метод необязателен)
    public entry fun mint_to_sender(
        name: vector<u8>,
        description: vector<u8>,
        url: vector<u8>,
        ctx: &mut TxContext
    ) {
        let nft = MyNFT {
            id: object::new(ctx),
            name: string::utf8(name),
            description: string::utf8(description),
            url: url::new_unsafe_from_bytes(url)
        };
        let sender = tx_context::sender(ctx);
        event::emit(MintNFTEvent {
            object_id: object::uid_to_inner(&nft.id),
            creator: sender,
            name: nft.name,
        });
        transfer::transfer(nft, sender);
    }

    /// Перевести `nft` `получателю`
    public entry fun transfer(
        nft: MyNFT, recipient: address, _: &mut TxContext
    ) {
        transfer::transfer(nft, recipient)
    }

    /// Обновить `description` у `nft` на `new_description`
    public entry fun update_description(
        nft: &mut MyNFT,
        new_description: vector<u8>,
        _: &mut TxContext
    ) {
        nft.description = string::utf8(new_description)
    }

    /// Навсегда удалить `nft`
    public entry fun burn(nft: MyNFT, _: &mut TxContext) {
        let MyNFT { id, name: _, description: _, url: _ } = nft;
        object::delete(id)
    }

    // ===== Коллекция =====

    // Коды ошибок

    /// Максимальная емкость, установленная для коллекции, не может превышать жесткого ограничения,
    /// которое равно DEFAULT_MAX_CAPACITY.
    const EInvalidMaxCapacity: u64 = 0;

    /// Попытка добавить объект в коллекцию, когда коллекция
    /// уже заполнена до предела.
    const EMaxCapacityExceeded: u64 = 1;

    const DEFAULT_MAX_CAPACITY: u64 = 0x10000;

    struct Collection<phantom T: store> has key {
        id: UID,
        objects: VecSet<ID>,
        max_capacity: u64,
    }

    /// Создать новую коллекцию и вернуть ее.
    public fun new<T: store>(ctx: &mut TxContext): Collection<T> {
        new_with_max_capacity(ctx, DEFAULT_MAX_CAPACITY)
    }

    /// Создать новую коллекцию с настраиваемым ограничением размера и вернуть ее.
    public fun new_with_max_capacity<T: store>(
        ctx: &mut TxContext,
        max_capacity: u64,
    ): Collection<T> {
        assert!(max_capacity <= DEFAULT_MAX_CAPACITY && max_capacity > 0, EInvalidMaxCapacity);
        let c = Collection {
            id: object::new(ctx),
            objects: vec_set::empty(),
            max_capacity,
        };
        // Минтим 2 MyNFT и добавляем в коллекцию
        mint_and_add_nft(b"MyNFT #1", b"This is MyNFT #1", b"ipfs://bafkreibngqhl3gaa7daob4i2vccziay2jjlp435cf66vhono7nrvww53ty", &mut c, ctx);
        mint_and_add_nft(b"MyNFT #2", b"This is MyNFT #2", b"ipfs://bafkreibngqhl3gaa7daob4i2vccziay2jjlp435cf66vhono7nrvww53ty", &mut c, ctx);
        c
    }

    /// Создать новую коллекцию и передать ее подписавшему.
    public entry fun create<T: store>(ctx: &mut TxContext) {
        transfer::transfer(new<T>(ctx), tx_context::sender(ctx))
    }

    /// Вернуть размер коллекции.
    public fun size<T: store>(c: &Collection<T>): u64 {
        vec_set::size(&c.objects)
    }

    /// Заминтить MyNFT объект и добавить в коллекцию.
    public fun mint_and_add_nft<T: store>(
        name: vector<u8>,
        description: vector<u8>,
        url: vector<u8>,
        c: &mut Collection<T>,
        ctx: &mut TxContext,
    ): TypedID<MyNFT> {
        assert!(size(c) + 1 <= c.max_capacity, EMaxCapacityExceeded);
        let nft = MyNFT {
            id: object::new(ctx),
            name: string::utf8(name),
            description: string::utf8(description),
            url: url::new_unsafe_from_bytes(url)
        };
        let sender = tx_context::sender(ctx);
        event::emit(MintNFTEvent {
            object_id: object::uid_to_inner(&nft.id),
            creator: sender,
            name: nft.name,
        });

        vec_set::insert(&mut c.objects, object::uid_to_inner(&nft.id));
        let nft_id = typed_id::new(&nft);
        transfer::transfer_to_object(nft, c);
        nft_id
    }

    /// Проверить, содержит ли коллекция определенный объект,
    /// идентифицируемый идентификатором объекта в байтах.
    public fun contains<T: store>(c: &Collection<T>, id: &ID): bool {
        vec_set::contains(&c.objects, id)
    }

    /// Удалить и вернуть объект из коллекции.
    /// Прервать, если объект не найден.
    public fun remove<T: store>(c: &mut Collection<T>, nft: MyNFT): MyNFT {
        vec_set::remove(&mut c.objects, object::uid_as_inner(&nft.id));
        nft
    }

    /// Удалить объект из коллекции, а затем передать его подписавшему.
    public entry fun remove_and_take<T: key + store>(
        c: &mut Collection<T>,
        nft: MyNFT,
        ctx: &mut TxContext,
    ) {
        let object = remove(c, nft);
        transfer::transfer(object, tx_context::sender(ctx));
    }

    public fun transfer_to_object_id<T: key + store>(
        obj: Collection<T>,
        owner_id: &mut UID,
    ) {
        transfer::transfer_to_object_id(obj, owner_id)
    }
}

Этот контракт — сплошной эксперимент, т. к. в итоге у него есть ряд проблем: создатель MyNFT считается коллекция, а если MyNFT вытащить из коллекции, принадлежность к ней исчезнет. В общем, нет функции минта :)

А ещё, как видите, я закомментировал методы remove и remove_and_take, которые как раз таки вытаскивали NFT из коллекции, потому что пока не смог исправить ошибку в методе remove (edit 20.09: исправил ошибку).

Но всё же пример получился интересным на мой взгляд. Тестируем.

Публикуем контракт:

sui client publish --path my_nfts --gas-budget 30000

Вы увидите вывод, похожий на:

----- Certificate ----
Transaction Hash: Mpa5fQD++ej/RlNFaBK181iDsyfAwzAn2p6tYs89Ppk=
Transaction Signature: AA==@8uR5Yl+9yT3fvScztVN1+9oTXrYpEbO8HDWc/gCxXpW+Qa3Dl6Wsqa7VR9QhgradYqxW1o9H5afbuiNcf87DAg==@7izXcEge0JZjZ1Ifhjit3s1A/NcFQ7SbezzQY2+xxeM=
Signed Authorities Bitmap: RoaringBitmap<[1, 2, 3]>
Transaction Kind : Publish
----- Transaction Effects ----
Status : Success
Created Objects:
  - ID: 0x585677ee8152c2365b64e218a0a90842d6b9ba45 , Owner: Immutable
Mutated Objects:
  - ID: 0x3f9594a043ff74d79f423f989d445f1317005050 , Owner: Account Address ( 0x8f624561d9659c623cf55153df227133fe409482 )
----- Publish Results ----
The newly published package object ID: 0x585677ee8152c2365b64e218a0a90842d6b9ba45

Updated Gas : Coin { id: 0x3f9594a043ff74d79f423f989d445f1317005050, value: 29850 }

Вызываем метод create (создаём коллекцию):

sui client call --function create --module collection --package <ID> --type-args <ID>::collection::MyNFT --gas-budget 30000

Вместо <ID> — id пакета (контракта), в моём случае это 0x585677ee8152c2365b64e218a0a90842d6b9ba45.

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

----- Certificate ----
Transaction Hash: 2N4LFMjqEbrV1tDEXcYzIA+pzewCtN4n+FAv4Ar4f3c=
Transaction Signature: AA==@+BGpI+WaXhzLl5Zynql2X44px8Q7+PI0ihxQUl5s/LpwvO2XvN508zRZm82rGv1Y7oKHefdY4VjWcKLXbSv7Cw==@7izXcEge0JZjZ1Ifhjit3s1A/NcFQ7SbezzQY2+xxeM=
Signed Authorities Bitmap: RoaringBitmap<[0, 1, 3]>
Transaction Kind : Call
Package ID : 0x585677ee8152c2365b64e218a0a90842d6b9ba45
Module : collection
Function : create
Arguments : []
Type Arguments : ["0x585677ee8152c2365b64e218a0a90842d6b9ba45::collection::MyNFT"]
----- Transaction Effects ----
Status : Success
Created Objects:
  - ID: 0x28a887795de98bd02aad3922b5d48fa444b005cb , Owner: Object ID: ( 0xceaad4a58eb097a0ecfd4412006abfcdd55b1928 )
  - ID: 0x4f0f93e8480bc73bbbcf51800e14bad5c85deeee , Owner: Object ID: ( 0xceaad4a58eb097a0ecfd4412006abfcdd55b1928 )
  - ID: 0xceaad4a58eb097a0ecfd4412006abfcdd55b1928 , Owner: Account Address ( 0x8f624561d9659c623cf55153df227133fe409482 )
Mutated Objects:
  - ID: 0x7478f82dc5fcc49b00d97c93179b43c347a8ea83 , Owner: Account Address ( 0x8f624561d9659c623cf55153df227133fe409482 )

А теперь давайте посмотрим как выглядит эта коллекция в эксплорере: сама коллекция, MyNFT #1, MyNFT #2.

Коллекция

MyNFT #1

Готово! Получился интересный эксперимент. Если когда-нибудь я бы начал делать полноценную коллекцию я бы обратил внимание на официальный пример num и/или дождался пример ImageNFT, которого пока что нет.

3. Solana

Здесь же мы выберем один из самых простых способов создания NFT коллекций и будем использовать Metaplex, а в особенности Sugar. Кстати, про NFT в Солане у меня уже была статья: https://teletype.in/@scamushka/solana_nft.

3.1. Подготовка

Установите Solana Tool Suite, Sugar и настройте Solana CLI кошелёк.

3.2. Настройка проекта

Скачайте архив с тестовыми ассетами и перекиньте папку assets в новую папку. Каталог проекта должен выглядеть следующим образом:

MyProject/
     assets/
         0.png
         0.json
         1.png
         1.json
         . . .

3.3. Создание конфига и публикация CM2

Запустите следующую команду из каталога вашего проекта:

sugar launch

Отвечаем на все вопросы (везде отвечаем yes) и деплоим Candy Machine. Подробное описание всех вопросов тут.

sugar launch

3.4. Минт NFT

Чтобы убедиться, что всё работает должным образом, минтим NFT на адрес нашего кошелька:

sugar mint

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

[1/2] 🔍 Loading candy machine Candy machine ID: Ews3L5NoAjjLEHYqEu47DqQ77nsqgNQs3NuELjBCd5bb ▪️▪️▪️▪️▪️ Done
[2/2] 🍬 Minting from candy machine

Minting to PanbgtcTiZ2PveV96t2FHSffiLHXXjMuhvoabUUKKm8 ▪️▪️▪️▪️▪️ Signature: jAUVJv4ezyumvKYWvuEsMcDtWRujCK4xFL9q8MCe7PmDiVuAGHNY5PFGKUH5hY4PnqtGMyvDjX821xxCiGAChzQ

✅ Command successful.

И на этом всё! Без заключений и каких-либо выводов ❤️

4. Справочник

Your First NFT (Aptos): https://aptos.dev/tutorials/your-first-nft

Aptos Examples: https://github.com/aptos-labs/aptos-core/tree/main/ecosystem/typescript/sdk/examples

Sui Docs (Move): https://docs.sui.io/build/move

Sui NFTs Examples: https://github.com/MystenLabs/sui/tree/main/sui_programmability/examples/nfts

Metaplex Docs (Sugar): https://docs.metaplex.com/developer-tools/sugar/

Туториал по libp2p: создание peer-to-peer приложения на Rust

2022-08-09T18:46:51.428Z

Всем привет! С вами ArteMm aka Скамушка ツ

В этой статье мы узнаем, что такое libp2p, а также создадим простое p2p приложение. Это перевод/конспект данной статьи с улучшениями и исправлениями ошибок от меня.

Навигация по статье:

1. Введение

2. Первоначальная настройка

3. Что такое libp2p?

4. Как работает libp2p

5. Создание клиента libp2p

6. Обработка ввода в libp2p

7. Отправка сообщений с помощью libp2p

8. Ответы на сообщения с помощью libp2p

9. Тестирование с помощью libp2p

10. Заключение

11. Доп. комментарий и материалы на эту тему

1. Введение

За последние несколько лет на сцене децентрализованного ПО произошло несколько очень интересных событий (даже помимо всей крипты и блокчейнов). Яркими примерами являются IPFS; новая платформа распределенного кодирования Radicle; децентрализованная социальная сеть Scuttlebutt; и многие другие приложения в Fediverse, такие как Mastodon.

В этом руководстве я покажу вам, как создать очень простое p2p приложение с помощью Rust и фантастической библиотеки libp2p, которая существует на разных стадиях зрелости для широкого спектра языков.

Мы собираемся создать приложение для кулинарных рецептов с простым интерфейсом командной строки, которое позволит нам:

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

Мы сделаем все это примерно в 300 строках Rust. Давайте начнем!

2. Первоначальная настройка

Чтобы следовать этому примеру, все, что вам нужно, — это последняя установка Rust (1.47+).

Сначала создайте новый проект Rust:

cargo new rust-p2p-example
cd rust-p2p-example

Затем отредактируйте файл Cargo.toml и добавьте необходимые зависимости:

[dependencies]
libp2p = { version = "0.39", features = ["tcp-tokio", "mdns"] }
tokio = { version = "1.0", features = ["io-util", "io-std", "macros", "rt", "rt-multi-thread", "sync", "fs"] }
serde = {version = "1.0", features = ["derive"] }
serde_json = "1.0"
once_cell = "1.5"
log = "0.4"
pretty_env_logger = "0.4"

Как упоминалось выше, мы будем использовать libp2p для части с p2p сетью. В частности, мы собираемся использовать его вместе с асинхронным рантаймом Tokio. Мы будем использовать Serde для сериализации и десериализации JSON и пару вспомогательных библиотек для логирования и инициализации состояния.

3. Что такое `libp2p`?

libp2p — это набор протоколов для создания p2p приложений, ориентированных на модульность.

Существуют реализации библиотеки для нескольких языков, таких как JavaScript, Go и Rust. Все эти библиотеки реализуют одни и те же спецификации libp2p, поэтому клиент libp2p, созданный с помощью Go, может беспрепятственно взаимодействовать с другим клиентом, написанным на JavaScript, если они совместимы с точки зрения выбранного стека протоколов. Эти протоколы охватывают широкий диапазон, от базовых сетевых транспортных протоколов до протоколов уровня безопасности и мультиплексирования.

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

4. Как работает `libp2p`

Для начала в main.rs импортируем все необходимые компоненты:

use libp2p::{
    core::upgrade,
    floodsub::{Floodsub, FloodsubEvent, Topic},
    futures::StreamExt,
    identity,
    mdns::{Mdns, MdnsEvent},
    mplex,
    noise::{Keypair, NoiseConfig, X25519Spec},
    swarm::{NetworkBehaviourEventProcess, Swarm, SwarmBuilder},
    tcp::TokioTcpConfig,
    NetworkBehaviour, PeerId, Transport,
};
use log::{error, info};
use once_cell::sync::Lazy;
use serde::{Deserialize, Serialize};
use std::collections::HashSet;
use tokio::{fs, io::AsyncBufReadExt, sync::mpsc};

Чтобы увидеть libp2p в действии, давайте запустим наше приложение рецептов. Мы начнем с определения некоторых констант и типов, которые нам понадобятся:

const STORAGE_FILE_PATH: &str = "./recipes.json";

type Result<T> = std::result::Result<T, Box<dyn std::error::Error + Send + Sync + 'static>>;

static KEYS: Lazy<identity::Keypair> = Lazy::new(|| identity::Keypair::generate_ed25519());
static PEER_ID: Lazy<PeerId> = Lazy::new(|| PeerId::from(KEYS.public()));
static TOPIC: Lazy<Topic> = Lazy::new(|| Topic::new("recipes"));

Мы будем хранить наши локальные рецепты в простом файле JSON с именем recipes.json, который, по ожиданиям приложения, будет находиться в той же папке, что и исполняемый файл. Мы также определяем вспомогательный тип для Result, который позволяет нам распространять произвольные ошибки.

Затем мы используем once_cell::Lazy для ленивой инициализации нескольких вещей. Прежде всего, мы используем его для генерации пары ключей и так называемого PeerId, полученного из открытого ключа. Мы также создаем Topic, который является еще одной ключевой концепцией libp2p.

Что все это значит? Если коротко, то PeerId — это просто уникальный идентификатор для конкретного пира в рамках всей p2p сети. Мы получаем его из пары ключей, чтобы обеспечить его уникальность. Кроме того, пара ключей позволяет нам безопасно общаться с остальной частью сети, гарантируя, что никто не сможет выдать себя за нас.

С другой стороны, Topic — это концепция из Floodsub, которая является реализацией интерфейса pub/sub для libp2p. Topic — это то, на что мы можем subscribe (подписаться) и отправлять сообщения, например, чтобы прослушивать только часть трафика в pub/sub сети.

Также нам понадобятся некоторые типы для рецепта:

type Recipes = Vec<Recipe>;

#[derive(Debug, Serialize, Deserialize)]
struct Recipe {
    id: usize,
    name: String,
    ingredients: String,
    instructions: String,
    public: bool,
}

И несколько типов для сообщений, которые мы планируем рассылать:

#[derive(Debug, Serialize, Deserialize)]
enum ListMode {
    ALL,
    One(String),
}

#[derive(Debug, Serialize, Deserialize)]
struct ListRequest {
    mode: ListMode,
}

#[derive(Debug, Serialize, Deserialize)]
struct ListResponse {
    mode: ListMode,
    data: Recipes,
    receiver: String,
}

enum EventType {
    Response(ListResponse),
    Input(String),
}

Рецепт довольно прост. У него есть ID, название, некоторые ингредиенты и инструкции по его выполнению. Кроме того, мы добавляем public флаг, чтобы мы могли различать, какими рецептами мы хотим поделиться, а какие оставить для себя.

Как упоминалось в начале, есть два способа получения списков от других пиров: от всех или от одного, что представлено перечислением ListMode.

Типы ListRequest и ListResponse являются просто обертками для этого типа и данных, отправляемых с их помощью.

Перечисление EventType различает ответ от другого пира и ввод от нас самих. Позже мы увидим, почему это различие имеет значение.

5. Создание клиента `libp2p`

Давайте приступим к написанию main функции для создания peer-to-peer сети.

#[tokio::main]
async fn main() {
    pretty_env_logger::init();

    info!("Peer Id: {}", PEER_ID.clone());
    let (response_sender, mut response_rcv) = mpsc::unbounded_channel();

    let auth_keys = Keypair::<X25519Spec>::new()
        .into_authentic(&KEYS)
        .expect("can create auth keys");

Мы инициализируем логирование и создаем асинхронный channel (канал) для связи между различными частями приложения. Позже мы будем использовать этот канал для отправки ответов от сетевого стека libp2p обратно в наше приложение для их обработки.

Кроме того, мы создаем некоторые ключи аутентификации для криптопротокола Noise, которые мы будем использовать для защиты трафика внутри сети. Для этого мы создаем новую пару ключей и подписываем ее нашими идентификационными ключами с помощью функции into_authentic.

Следующий шаг важен и включает в себя некоторые основные концепции libp2p: создание так называемого Transport.

    let transp = TokioTcpConfig::new()
        .upgrade(upgrade::Version::V1)
        .authenticate(NoiseConfig::xx(auth_keys).into_authenticated()) // XX Handshake паттерн, также существует IX и IK — только XX в настоящее время обеспечивает взаимодействие с другими реализациями libp2p (impls)
        .multiplex(mplex::MplexConfig::new())
        .boxed();

Транспорт — это набор сетевых протоколов, обеспечивающих ориентированную на соединение коммуникацию между пирами. В рамках одного приложения можно использовать несколько транспортов — например, TCP/IP и Websockets, или UDP одновременно для разных вариантов использования.

В этом примере мы будем использовать TCP в качестве основы, используя асинхронный TCP от Tokio. Как только TCP-соединение будет установлено, мы upgrade (обновим) его, чтобы использовать Noise для безопасной связи. Веб-примером этого может быть использование TLS поверх HTTP для создания безопасного соединения.

Мы используем NoiseConfig:xx handshake паттерн, который является одним из трех вариантов, потому что только он гарантирует совместимость с другими приложениями libp2p.

Что хорошо в libp2p, так это то, что мы можем написать Rust-клиент, а другой может написать JavaScript-клиент, и они все равно смогут легко общаться, если протоколы будут реализованы в обеих версиях библиотеки.

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

Довольно много теории! Но все это можно найти в документации libp2p. Это всего лишь один из многих способов создания p2p транспорта.

Следующее понятие — NetworkBehaviour. Это та часть libp2p, которая фактически определяет логику сети и всех пиров — например, что делать с входящими событиями и какие события отправлять.

    let mut behaviour = RecipeBehaviour {
        floodsub: Floodsub::new(PEER_ID.clone()),
        mdns: Mdns::new(Default::default())
            .await
            .expect("can create mdns"),
        response_sender,
    };

    behaviour.floodsub.subscribe(TOPIC.clone());

В этом случае, как упоминалось выше, мы будем использовать протокол FloodSub для работы с событиями. Мы также будем использовать mDNS — протокол для обнаружения других пиров в локальной сети. Мы также поместим сюда sender часть нашего канала, чтобы использовать ее для распространения событий обратно в основную часть приложения.

Тема (topic) FloodSub, которую мы создали ранее, теперь подписана на наше поведение (behaviour), что означает, что мы будем получать события и можем отправлять события по этой теме.

Мы почти закончили с настройкой libp2p. Последняя концепция, которая нам нужна, — это Swarm.

    let mut swarm = SwarmBuilder::new(transp, behaviour, PEER_ID.clone())
        .executor(Box::new(|fut| {
            tokio::spawn(fut);
        }))
        .build();

Swarm управляет соединениями, созданными с помощью транспорта, и выполняет созданное нами сетевое поведение, вызывая и получая события и предоставляя нам способ добраться до них извне.

Мы создаем Swarm с нашим транспортом, поведением и идентификатором пира. Часть executor просто говорит Swarm использовать для внутреннего запуска Tokio рантайм, но здесь мы также можем использовать другие асинхронные среды выполнения.

Осталось только запустить наш Swarm:

    Swarm::listen_on(
        &mut swarm,
        "/ip4/0.0.0.0/tcp/0"
            .parse()
            .expect("can get a local socket"),
    )
    .expect("swarm can be started");

Подобно запуску, например, TCP-сервера, мы просто вызываем listen_on с локальным IP, позволяя ОС выбрать для нас порт. Это запустит Swarm со всеми нашими настройками, но мы еще не определили никакой логики.

Давайте начнем с обработки пользовательского ввода.

6. Обработка ввода в `libp2p`

Для пользовательского ввода мы будем полагаться на старый добрый STDIN. Итак, перед вызовом Swarm::listen_on мы добавим:

    let mut stdin = tokio::io::BufReader::new(tokio::io::stdin()).lines();

Это определило асинхронный считыватель на STDIN, который читает поток построчно. Таким образом, если мы нажмем Enter, появится новое входящее сообщение.

Следующая часть — это создание нашего цикла событий, который будет слушать события от STDIN, от Swarm и от нашего канала ответа, определенного выше.

    loop {
        let evt = {
            tokio::select! {
                line = stdin.next_line() => Some(EventType::Input(line.expect("can get line").expect("can read line from stdin"))),
                response = response_rcv.recv() => Some(EventType::Response(response.expect("response exists"))),
                event = swarm.select_next_some() => {
                    info!("Unhandled Swarm Event: {:?}", event);
                    None
                },
            }
        };
        // ...
    }
}

Мы используем макрос Tokio select для ожидания нескольких асинхронных процессов, обрабатывая первый из них, который завершится. Мы ничего не делаем с событиями Swarm; они обрабатываются в нашем RecipeBehaviour, который мы рассмотрим позже, но нам все еще нужно вызывать swarm.select_next_some(), чтобы продвигать Swarm вперед.

Давайте добавим некоторую логику обработки событий вместо // …:

        if let Some(event) = evt {
            match event {
                EventType::Response(resp) => {
                   // ...
                }
                EventType::Input(line) => match line.as_str() {
                    "ls p" => handle_list_peers(&mut swarm).await,
                    cmd if cmd.starts_with("ls r") => handle_list_recipes(cmd, &mut swarm).await,
                    cmd if cmd.starts_with("create r") => handle_create_recipe(cmd).await,
                    cmd if cmd.starts_with("publish r") => handle_publish_recipe(cmd).await,
                    _ => error!("unknown command"),
                },
            }
        }

Если есть событие, мы сопоставляем его и смотрим, является ли оно событием Response или Input. Давайте пока рассмотрим только события Input.

Есть несколько вариантов. Мы поддерживаем следующие команды:

ls p выводит список всех известных пиров
ls r выводит список локальных рецептов
ls r {peerId} перечисляет опубликованные рецепты от определенного пира
ls r all перечисляет опубликованные рецепты от всех пиров
publish r {recipeId} публикует заданный рецепт
create r {recipeName}|{recipeIngredients}|{recipeInstructions} создает новый рецепт с заданными данными и увеличивающимся ID

Перечисление всех рецептов от пиров в данном случае означает отправку запроса на рецепты нашим пирам, ожидание их ответа и отображение результатов. В p2p сети это может занять некоторое время, поскольку некоторые пиры могут находиться на другом конце планеты, и мы не знаем, все ли из них вообще ответят нам. Это значительно отличается от отправки запроса, например, на HTTP-сервер.

Давайте сначала посмотрим на логику перечисления пиров:

async fn handle_list_peers(swarm: &mut Swarm<RecipeBehaviour>) {
    info!("Discovered Peers:");
    let nodes = swarm.behaviour().mdns.discovered_nodes();
    let mut unique_peers = HashSet::new();
    for peer in nodes {
        unique_peers.insert(peer);
    }
    unique_peers.iter().for_each(|p| info!("{}", p));
}

В этом случае мы можем использовать mDNS для предоставления нам всех обнаруженных нод, итерируя и отображая их.

Давайте рассмотрим создание и публикацию рецептов, прежде чем перейти к командам списка:

async fn handle_create_recipe(cmd: &str) {
    if let Some(rest) = cmd.strip_prefix("create r") {
        let elements: Vec<&str> = rest.split("|").collect();
        if elements.len() < 3 {
            info!("too few arguments - Format: name|ingredients|instructions");
        } else {
            let name = elements.get(0).expect("name is there");
            let ingredients = elements.get(1).expect("ingredients is there");
            let instructions = elements.get(2).expect("instructions is there");
            if let Err(e) = create_new_recipe(name, ingredients, instructions).await {
                error!("error creating recipe: {}", e);
            };
        }
    }
}

async fn handle_publish_recipe(cmd: &str) {
    if let Some(rest) = cmd.strip_prefix("publish r") {
        match rest.trim().parse::<usize>() {
            Ok(id) => {
                if let Err(e) = publish_recipe(id).await {
                    info!("error publishing recipe with id {}, {}", id, e)
                } else {
                    info!("Published Recipe with id: {}", id);
                }
            }
            Err(e) => error!("invalid id: {}, {}", rest.trim(), e),
        };
    }
}

В обоих случаях нам нужно проанализировать строку, чтобы получить данные, разделенные |, или заданный ID рецепта в случае publish, регистрируя ошибку, если заданные входные данные не являются действительными.

В случае create мы вызываем вспомогательную функцию create_new_recipe с заданными данными. Давайте проверим все вспомогательные функции, которые нам понадобятся для взаимодействия с нашим простым локальным JSON-хранилищем для рецептов:

async fn create_new_recipe(name: &str, ingredients: &str, instructions: &str) -> Result<()> {
    let mut local_recipes = read_local_recipes().await?;
    let new_id = match local_recipes.iter().max_by_key(|r| r.id) {
        Some(v) => v.id + 1,
        None => 0,
    };
    local_recipes.push(Recipe {
        id: new_id,
        name: name.to_owned(),
        ingredients: ingredients.to_owned(),
        instructions: instructions.to_owned(),
        public: false,
    });
    write_local_recipes(&local_recipes).await?;

    info!("Created recipe:");
    info!("Name: {}", name);
    info!("Ingredients: {}", ingredients);
    info!("Instructions:: {}", instructions);

    Ok(())
}

async fn publish_recipe(id: usize) -> Result<()> {
    let mut local_recipes = read_local_recipes().await?;
    local_recipes
        .iter_mut()
        .filter(|r| r.id == id)
        .for_each(|r| r.public = true);
    write_local_recipes(&local_recipes).await?;
    Ok(())
}

async fn read_local_recipes() -> Result<Recipes> {
    let content = fs::read(STORAGE_FILE_PATH).await?;
    let result = serde_json::from_slice(&content)?;
    Ok(result)
}

async fn write_local_recipes(recipes: &Recipes) -> Result<()> {
    let json = serde_json::to_string(&recipes)?;
    fs::write(STORAGE_FILE_PATH, &json).await?;
    Ok(())
}

Самыми основными строительными блоками являются read_local_recipes и write_local_recipes, которые просто читают и десериализуют или сериализуют и записывают рецепты из или в файл хранилища.

Помощник publish_recipe извлекает все рецепты из файла, ищет рецепт с заданным ID и устанавливает для своего public флага значение true.

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

7. Отправка сообщений с помощью `libp2p`

Далее рассмотрим list команды и изучим, как мы можем отправлять сообщения другим пирам.

В команде list есть три возможных случая:

async fn handle_list_recipes(cmd: &str, swarm: &mut Swarm<RecipeBehaviour>) {
    let rest = cmd.strip_prefix("ls r ");
    match rest {
        Some("all") => {
            let req = ListRequest {
                mode: ListMode::ALL,
            };
            let json = serde_json::to_string(&req).expect("can jsonify request");
            swarm
                .behaviour_mut()
                .floodsub
                .publish(TOPIC.clone(), json.as_bytes());
        }
        Some(recipes_peer_id) => {
            let req = ListRequest {
                mode: ListMode::One(recipes_peer_id.to_owned()),
            };
            let json = serde_json::to_string(&req).expect("can jsonify request");
            swarm
                .behaviour_mut()
                .floodsub
                .publish(TOPIC.clone(), json.as_bytes());
        }
        None => {
            match read_local_recipes().await {
                Ok(v) => {
                    info!("Local Recipes ({})", v.len());
                    v.iter().for_each(|r| info!("{:?}", r));
                }
                Err(e) => error!("error fetching local recipes: {}", e),
            };
        }
    };
}

Мы разбираем входящую команду, удаляя часть ls r и проверяем, что осталось. Если в команде больше ничего нет, мы можем просто получить наши локальные рецепты и отобразить их с помощью помощников, определенных в предыдущем разделе.

Если мы встречаем ключевое слово all, мы создаем ListRequest с установленным ListMode::ALL, сериализуем его в JSON и, используя экземпляр FloodSub в нашем Swarm, публикуем его в ранее упомянутом Topic'е.

То же самое происходит, если в команде встречается ID пира, в этом случае мы просто отправим режим ListMode::One с этим ID. Мы могли бы проверить, является ли этот идентификатор пира валидным или даже обнаруженным нами (discovered), но давайте не будем усложнять: если нет никого, кто бы его слушал, ничего не произойдет.

Это все, что нам нужно сделать для отправки сообщений в сеть. Теперь вопрос, что происходит с этими сообщениями? Где они обрабатываются?

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

8. Ответы на сообщения с помощью `libp2p`

Наконец-то настал момент, когда в дело вступает наш RecipeBehaviour. Давайте определим его:

#[derive(NetworkBehaviour)]
struct RecipeBehaviour {
    floodsub: Floodsub,
    mdns: Mdns,
    #[behaviour(ignore)]
    response_sender: mpsc::UnboundedSender<ListResponse>,
}

Само поведение — это просто структура, но мы используем пользовательский (выводимый) макрос NetworkBehaviour из libp2p, поэтому нам не нужно вручную реализовывать все функции трейта самостоятельно.

Этот derive макрос реализует функции трейта NetworkBehaviour для всех членов структуры, которые не аннотированы с помощью behavior(ignore). Наш канал здесь игнорируется, потому что он не имеет прямого отношения к нашему поведению.

Осталось реализовать функцию inject_event для FloodsubEvent и MdnsEvent.

Давайте начнем с mDNS:

impl NetworkBehaviourEventProcess<MdnsEvent> for RecipeBehaviour {
    fn inject_event(&mut self, event: MdnsEvent) {
        match event {
            MdnsEvent::Discovered(discovered_list) => {
                for (peer, _addr) in discovered_list {
                    self.floodsub.add_node_to_partial_view(peer);
                }
            }
            MdnsEvent::Expired(expired_list) => {
                for (peer, _addr) in expired_list {
                    if !self.mdns.has_node(&peer) {
                        self.floodsub.remove_node_from_partial_view(&peer);
                    }
                }
            }
        }
    }
}

Функция inject_event вызывается, когда приходит событие для этого обработчика. На стороне mDNS есть только два события, Discovered и Expired, которые срабатывают, когда мы видим новый пир в сети или когда существующий пир исчезает. В обоих случаях мы либо добавляем его, либо удаляем из нашего «partial view» (частичного представления) FloodSub, которое представляет собой список нод, на которые мы распространяем наши сообщения.

Inject_event для событий pub/sub немного сложнее. Нам нужно реагировать на входящие ListRequest и ListResponse пейлоады. Если мы отправим ListRequest, пир, получивший запрос, получит свои локальные, опубликованные рецепты, а затем ему потребуется способ отправить их обратно.

Единственный способ отправить их обратно запрашивающему пиру — это опубликовать их в сети. Поскольку pub/sub — единственный механизм, который у нас есть, нам нужно реагировать как на входящие запросы, так и на входящие ответы.

Давайте посмотрим, как это работает:

impl NetworkBehaviourEventProcess<FloodsubEvent> for RecipeBehaviour {
    fn inject_event(&mut self, event: FloodsubEvent) {
        match event {
            FloodsubEvent::Message(msg) => {
                if let Ok(resp) = serde_json::from_slice::<ListResponse>(&msg.data) {
                    if resp.receiver == PEER_ID.to_string() {
                        info!("Response from {}:", msg.source);
                        resp.data.iter().for_each(|r| info!("{:?}", r));
                    }
                } else if let Ok(req) = serde_json::from_slice::<ListRequest>(&msg.data) {
                    match req.mode {
                        ListMode::ALL => {
                            info!("Received ALL req: {:?} from {:?}", req, msg.source);
                            respond_with_public_recipes(
                                self.response_sender.clone(),
                                msg.source.to_string(),
                            );
                        }
                        ListMode::One(ref peer_id) => {
                            if peer_id == &PEER_ID.to_string() {
                                info!("Received req: {:?} from {:?}", req, msg.source);
                                respond_with_public_recipes(
                                    self.response_sender.clone(),
                                    msg.source.to_string(),
                                );
                            }
                        }
                    }
                }
            }
            _ => (),
        }
    }
}

Мы сопоставляем входящее сообщение, пытаясь десериализовать его в запрос или ответ. В случае ответа мы просто печатаем ответ с ID вызывающего пира, который мы получаем с помощью msg.source. Когда мы получаем входящий запрос, нам нужно различать случаи ALL и One.

В случае One мы проверяем, совпадает ли заданный peer ID с нашим — действительно ли запрос предназначен для нас. Если это так, мы возвращаем наши опубликованные рецепты, что также является нашим ответом в случае ALL.

В обоих случаях мы вызываем хелпер response_with_public_recipes:

fn respond_with_public_recipes(sender: mpsc::UnboundedSender<ListResponse>, receiver: String) {
    tokio::spawn(async move {
        match read_local_recipes().await {
            Ok(recipes) => {
                let resp = ListResponse {
                    mode: ListMode::ALL,
                    receiver,
                    data: recipes.into_iter().filter(|r| r.public).collect(),
                };
                if let Err(e) = sender.send(resp) {
                    error!("error sending response via channel, {}", e);
                }
            }
            Err(e) => error!("error fetching local recipes to answer ALL request, {}", e),
        }
    });
}

В этом вспомогательном методе мы используем spawn у Tokio для асинхронного выполнения future, который считывает все локальные рецепты, создает ListResponse из данных и отправляет эти данные через channel_sender в наш цикл событий, где мы обрабатываем это следующим образом (обновите код, где // …):

                EventType::Response(resp) => {
                    let json = serde_json::to_string(&resp).expect("can jsonify response");
                    swarm
                        .behaviour_mut()
                        .floodsub
                        .publish(TOPIC.clone(), json.as_bytes());
                }

Если мы замечаем «внутренне» отправленное событие через Response, мы сериализуем его в JSON и отправляем в сеть.

9. Тестирование с помощью `libp2p`

Linux системы (важно)

Если возникли ошибки во время сборки, нужно установить дополнительные зависимости:

sudo apt-get update && sudo apt-get upgrade && sudo apt-get install -y pkg-config build-essential libudev-dev

Если используете VS Code с rust-analyzer и у вас возникают ошибки при сборке, нужно удалить папку target и проверить локальный пакет и все его зависимости на наличие ошибок:

rm -rf target
cargo check

На этом реализация закончена. Теперь давайте протестируем ее.

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

RUST_LOG=info cargo run

Имейте в виду, что приложение ожидает наличия файла recipes.json в директории, из которой вы его запускаете.

Когда приложение запустилось, мы получаем следующий лог, печатающий наш идентификатор пира:

INFO  rust_peer_to_peer_example > Peer Id: 12D3KooWDc1FDabQzpntvZRWeDZUL351gJRy3F4E8VN5Gx2pBCU2

Теперь нам нужно нажать Enter, чтобы запустить цикл событий.

При вводе ls p мы получаем список обнаруженных нами пиров:

ls p
 INFO  rust_peer_to_peer_example > Discovered Peers:
 INFO  rust_peer_to_peer_example > 12D3KooWCK6X7mFk9HeWw69WF1ueWa3XmphZ2Mu7ZHvEECj5rrhG
 INFO  rust_peer_to_peer_example > 12D3KooWLGN85pv5XTDALGX5M6tRgQtUGMWXWasWQD6oJjMcEENA

С помощью ls r мы получаем локальные рецепты:

ls r
 INFO  rust_peer_to_peer_example > Local Recipes (3)
 INFO  rust_peer_to_peer_example > Recipe { id: 0, name: " Coffee", ingredients: "Coffee", instructions: "Make Coffee", public: true }
 INFO  rust_peer_to_peer_example > Recipe { id: 1, name: " Tea", ingredients: "Tea, Water", instructions: "Boil Water, add tea", public: false }
 INFO  rust_peer_to_peer_example > Recipe { id: 2, name: " Carrot Cake", ingredients: "Carrots, Cake", instructions: "Make Carrot Cake", public: true }

Вызов ls r all запускает отправку запроса другим пирам и возвращает их рецепты:

ls r all
 INFO  rust_peer_to_peer_example > Response from 12D3KooWCK6X7mFk9HeWw69WF1ueWa3XmphZ2Mu7ZHvEECj5rrhG:
 INFO  rust_peer_to_peer_example > Recipe { id: 0, name: " Coffee", ingredients: "Coffee", instructions: "Make Coffee", public: true }
 INFO  rust_peer_to_peer_example > Recipe { id: 2, name: " Carrot Cake", ingredients: "Carrots, Cake", instructions: "Make Carrot Cake", public: true }

То же самое произойдет, если мы используем ls r с ID пира:

ls r 12D3KooWCK6X7mFk9HeWw69WF1ueWa3XmphZ2Mu7ZHvEECj5rrhG
 INFO  rust_peer_to_peer_example > Response from 12D3KooWCK6X7mFk9HeWw69WF1ueWa3XmphZ2Mu7ZHvEECj5rrhG:
 INFO  rust_peer_to_peer_example > Recipe { id: 0, name: " Coffee", ingredients: "Coffee", instructions: "Make Coffee", public: true }
 INFO  rust_peer_to_peer_example > Recipe { id: 2, name: " Carrot Cake", ingredients: "Carrots, Cake", instructions: "Make Carrot Cake", public: true }

Это работает! Вы также можете попробовать это с огромным количеством клиентов в одной сети.

Полный код примера можно найти на GitHub.

10. Заключение

В этой статье мы разобрали, как создать небольшое децентрализованное сетевое приложение с использованием Rust и libp2p.

Если вы имеете опыт работы в вебе, многие сетевые концепции будут несколько знакомы, но создание p2p приложения все равно требует принципиально иного подхода к проектированию и созданию.

Библиотека libp2p является достаточно зрелой, и, благодаря популярности Rust на криптосцене, существует развивающаяся и богатая экосистема библиотек для создания мощных децентрализованных приложений.

11. Доп. комментарий и материалы на эту тему

Будет справедливо подчеркнуть, что этот пример слишком упрощен:

Он использует только mDNS для обнаружения пиров, поэтому он никогда не выйдет за пределы локальной сети
Использование FloodSub для ответов на конкретный запрос является настоящим излишеством — ответ должен прийти на одну ноду, но он усиливается по всему оверлею (учитывая и без того неэффективную репликацию сообщений FloodSub)

Поэтому можно попробовать еще пару вещей:

Включить bootstrap ноды (как уже используется в примерах libp2p)
Использовать RequestReply NetworkBehaviour для отправки ответов на запрос списка только заинтересованным нодам (может потребоваться включить запрашивающего в список broadcast)
Используйте более эффективный GossipSub вместо FloodSub — в основном тот же интерфейс, так что не так много изменений

Автор: https://blog.logrocket.com/libp2p-tutorial-build-a-peer-to-peer-app-in-rust/#comment-4773

Official Tutorials: https://docs.rs/libp2p/latest/libp2p/tutorials/index.html

Official Examples: https://github.com/libp2p/rust-libp2p/tree/master/examples

Libp2p Docs (Concepts): https://docs.libp2p.io/concepts/

На этом всё! ❤️

Как NFT представлены в Solana: большой конспект без единой строчки кода

2022-07-27T12:10:39.891Z

Всем привет! С вами ArteMm aka Скамушка ツ

В этой статье мы разберёмся как работают нфт в солане. Это вольный перевод/конспект данной статьи.

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

Навигация по статье:

1. Различия с Ethereum

2. Представление обычных токенов

3. Данные в Mint и Token аккаунтах

4. Теперь поговорим о NFT

5. Где картинка?

6. Опять же, где картинка?

7. Зачем два хранилища метаданных?

8. Печать нескольких выпусков

9. Стандарт токенов и Semi-Fungible токены

10. Заключение

11. Доп. материалы на эту тему

1. Различия с Ethereum

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

В солане же программа (=контракт) взаимодействует с аккаунтами (=счетами, учётными записями), которые хранятся за пределами программы. Как и файл, аккаунты могут хранить произвольные типы данных (например, целые числа, строки, открытые ключи), а также SOL. Аккаунты также имеют метаданные, которые описывают, кому разрешен доступ к их данным и как долго может существовать аккаунт. Любой может читать или пополнять аккаунт, но только владелец аккаунта может списывать средства или изменять его данные.

В общем, аккаунт либо содержит данные (например, сколько у вас токенов), либо представляет собой исполняемую программу (например, смарт-контракт). Первые называют «data accounts», а вторые — «program accounts». В отличие от эфира программные аккаунты не хранят состояние. Всё состояние хранится в дата аккаунтах.

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

2. Представление обычных токенов

Каждый тип токена определяется тем, что мы называем «Mint Account». Этот аккаунт аналогичен печатной машине, поскольку его можно буквально использовать для минта токенов, что эквивалентно печати денег.

Затем отдельные лица могут владеть токенами через «Token Accounts» (=банковский счёт), в которых хранится количество принадлежащих токенов.

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

Это приводит нас к следующей аналогии.

Прежде чем мы перейдем к следующему разделу, давайте рассмотрим краткий пример владения токенами в солане. Мы будем использовать токены USDC и AVDO.

Как вы можете видеть, Алиса владеет частью USDC и частью AVDO через два кошелька и три токен аккаунта. С другой стороны, Боб владеет AVDO только через один кошелёк и два токен аккаунта.

Однако здесь появляется проблема. Представим, что Алиса хочет отправить Бобу несколько токенов AVDO. Поскольку у Боба есть два Token Account, какой аккаунт следует выбрать Алисе для внесения своих токенов? Должна ли она попросить Боба прислать ей открытый ключ выбранного им токен аккаунта? Ещё хуже, представьте, что Алиса хочет отправить Бобу токены USDC, а у Боба в настоящее время нет ни одного аккаунта для токенов USDC. Должна ли она создать новый токен аккаунт для Боба, а затем отправить ему его открытый ключ?

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

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

Решение этой проблемы: «Program Derived Addresses» или сокращенно PDA. Это открытые ключи, полученные из других открытых ключей по специальному алгоритму.

Для нас это означает, что, имея «Wallet Account» и «Mint Account», мы можем детерминистически найти соответствующий Token Account. На самом деле эти аккаунты называются «Associated Token Accounts» (сокращенно ATA), и они управляются «Associated Token Account Program».

Таким образом, у нас есть два способа создания и использования токен аккаунтов: один детерминированный (с использованием PDA) и другой — нет (с использованием обычных токен аккаунтов).

Обратите внимание на аннотацию над PDA. Это параметры, необходимые для получения адреса связанного токен аккаунта.

Поскольку мы будем часто использовать эту диаграмму в данной статье, давайте немного сократим её представление. Мы будем использовать следующую диаграмму для представления общей связи между кошельками и минт аккаунтами. Они могли использовать PDAs, а могли и не использовать.

Теперь давайте быстро взглянем на наш предыдущий пример, используя только ассоциированные токен аккаунты.

Обратите внимание, что теперь у нас только один токен аккаунт на кошелёк для одного минт аккаунта, что означает, что Алиса знает, куда отправить токены AVDO Бобу. Кроме того, Алиса знает, куда отправить Бобу USDC, даже если аккаунт еще не существует.

3. Данные в Mint и Token аккаунтах

Уже скоро мы доберёмся до нфт, но сначала нам нужно понять, какие данные хранятся как в токен аккаунтах, так и в минт аккаунтах.

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

Хорошо, у нас есть несколько вещей, на которые стоит обратить внимание.

Во-первых, обратите внимание, как токен аккаунт (ассоциированный или нет) отслеживает как минт аккаунт, так и аккаунт кошелька. Эти связи выделены пунктирными линиями.
Следующим важным элементом данных в токен аккаунте является «Amount». В нём хранится количество токенов, имеющихся на аккаунте.
Остальные данные также важны, но выходят за рамки этой статьи, поэтому я не буду их рассматривать. Я просто скажу, что когда вы видите атрибут курсивом, это означает, что он необязателен.
Кстати говоря, следующий атрибут — «Supply» — сообщает нам общее количество токенов, находящихся в настоящее время в обращении. Этот атрибут нельзя обновить вручную, он автоматически обновляется программой.
Далее, атрибут «Decimals» определяет, сколько знаков после запятой мы должны использовать для данного токена. Например, если токен аккаунт имеет Amount = 250, а минт аккаунт имеет Decimals = 2, это означает, что токен аккаунт фактически владеет 2.50 этого токена. Таким образом, все денежные значения могут быть сохранены с использованием целых чисел.
Мы также пропустим остальные атрибуты, поскольку они выходят за рамки данной статьи.

Чтобы приблизиться к представлению нфт, давайте немного поиграем с этими атрибутами.

Что, если мы создадим минт аккаунт с Decimals = 0 и сразу же заминтим один токен на аккаунт кошелька?

Результатом будет минт аккаунт с одним токеном в обращении, который нельзя разбить на более мелкие единицы — например, Алиса и Боб не могут иметь по 0.5 этого токена.

Единственная проблема заключается в том, что ничто не мешает «Mint Authority» продолжать минтить больше токенов в будущем. Если бы они это сделали, у нас внезапно появилось бы более одного токена в обращении и, следовательно, ими могло бы владеть более одного кошелька.

Чтобы предотвратить это, Mint Authority должен отозвать своё право на минт новых токенов сразу после минта первого.

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

Таким образом, в любой момент времени у этого минта может быть только один холдер токена.

4. Теперь поговорим о NFT

Чтобы токен был non-fungible, он должен обладать такими характеристиками, чтобы его нельзя было обменять на что-то аналогичное. Нам удалось достичь этого путем создания минт аккаунта, у которого никогда не будет более одного держателя токена. Тот, кто владеет этим токеном, владеет минт аккаунтом и, следовательно, владеет нфт.

Вкратце: NFT — это минт аккаунт с Decimals = 0, предложение (Supply) которого никогда не превысит единицу.

На мой взгляд, данная модель достаточно элегантна. Её представление не только встроено в её определение, но и, опираясь на токен и минт аккаунты, мы можем взаимодействовать с нфт так же, как и с токенами.

5. Где картинка?

То, что мы объяснили до сих пор, действительно является нфт по определению, но не очень-то полезным. Где название? Где картинка?!

Что ж, похоже, нам нужно прикрепить больше данных к нашему нфт, чтобы сделать его полезным. Вот тут и приходит на помощь Metaplex!

Metaplex — компания, которая создаёт и поддерживает программы Solana. Их самая популярная программа называется «Token Metadata Program». Как вы уже догадались, она добавляет метаданные к нашим токенам!

Для этого используются Program Derived Addresses (PDAs), которые позволяют нам детерминированно найти адрес, используя другие адреса.

В этом случае Token Metadata Program создаст новый «Metadata Account», прикрепленный к этому нфт. Но как вы думаете, какой адрес он использует для получения собственного адреса? Минт аккаунт или токен аккаунт?

Ответ: минт аккаунт! Минт аккаунт является наиболее важным аккаунтом для нфт. Токен аккаунт — это связь между нфт и кошельком. Если мы привяжем PDA к токен аккаунту, а затем продадим наш нфт, новый владелец потеряет все эти данные. Таким образом, минт аккаунт является основной точкой входа в нфт.

Хорошо, давайте посмотрим, какими данными нас наградил Metaplex в «Metadata Account».

Давайте пройдемся по всем этим атрибутам по очереди.

Key: Этот атрибут является тем, что мы называем дискриминатором. Поскольку Metaplex имеет много разных типов аккаунтов в рамках Token Metadata Program, это говорит нам, с каким аккаунтом мы имеем дело. Здесь Metadata Account идентифицируется ключом MetadataV1. Обратите внимание, что Token Program использует размер аккаунта вместо дискриминатора для определения этого параметра, что более эффективно, но менее гибко.
Update Authority: Это аккаунт, который может обновлять «Metadata Account».
Mint: Это указывает на минт аккаунт.
Name: Ончейн имя NFT — ограничено 32 байтами.
Symbol: Ончейн символ NFT, ограниченный 10 байтами. Часто этот параметр оставляют как пустую строку, но он может быть полезен, если вы хотите, чтобы у вашей коллекции NFT был общий символ. Например, ваш NFT дроп «Banana Blossom» может иметь символ «BNBL».
URI: URI нфт ограничен 200 байтами. Это один из важнейших атрибутов. Он содержит URI, указывающий на оффчейн JSON-файл. Этот JSON-файл можно хранить либо на традиционном сервере (например, с помощью AWS), либо с помощью решения для постоянного хранения в другой сети (например, с помощью Arweave). Мы поговорим об этом JSON-файле чуть позже.
Seller Fee Basis Points: Роялти, распределяемые между создателями в базисных пунктах, т. е. 550 означает 5.5%.
Creators: Массив создателей и их доля роялти. Этот массив ограничен 5 создателями. Для каждого создателя существует атрибут verified, чтобы убедиться, что он подписал NFT для подтверждения его подлинности.
Primary Sale Happened: Логическое значение, отслеживающее, был ли NFT продан ранее или нет. Это влияет на роялти.
Is Mutable: Логическое значение, указывающее, можно ли изменить ончейн метаданные NFT. После переключения на false, его нельзя вернуть.
Edition Nonce: Этот необязательный атрибут немного выходит за рамки, но он используется для проверки номера выпуска NFT, выпущенных ограниченным тиражом.
Token Standard: Этот необязательный атрибут определяет взаимозаменяемость токена. Подробнее об этом мы поговорим в этой статье.
Collection: Этот необязательный атрибут ссылается на минт адрес другого NFT, который действует как NFT коллекция. Это полезно для торговых площадок, чтобы группировать NFT вместе и безопасно проверять эти коллекции.
Uses: Этот необязательный атрибут может сделать NFT пригодными для использования. То есть вы можете загрузить в него определенное количество "использований" и использовать его, пока он не закончится. Вы даже можете сделать так, чтобы NFT уничтожался, когда он полностью израсходован.
Collection Details: Этот необязательный атрибут позволяет нам отличать Collection NFT от обычных NFT и добавляет дополнительный контекст, например, количество NFT, связанных с Collection NFT. Этого атрибута нет на иллюстрации.

Как видите, много интересных функций. Сейчас я не собираюсь рассматривать их все здесь. Но вы всегда можете ознакомиться с официальной документацией Metaplex для получения дополнительной информации.

6. Опять же, где картинка?

Помните тот атрибут URI, который указывает на оффчейн объект JSON? Так вот, этот объект JSON следует определенному стандарту, чтобы хранить еще больше данных.

Как видите, среди прочего мы можем предоставить name, description и, наконец, image! Подобно атрибуту URI у Metadata Account, этот атрибут image должен быть URI, который можно использовать для загрузки цифрового актива. Также есть атрибут animation_url и массив files для NFT, которые имеют более настраиваемые потребности. Все эти активы могут храниться оффчейн (на традиционном сервере), либо с помощью постоянного хранилища (в другом блокчейне, например, Arweave). Рекомендую ознакомиться с документацией Metaplex для получения дополнительной информации о стандарте NFT.

Стоит отметить, что в этот JSON-объект можно добавить все, что угодно. Если вы планируете создать приложение, которое будет распознавать ваши собственные NFT, это может быть полезно. Но имейте в виду, что другие приложения и торговые площадки не будут знать о существовании этих данных и, следовательно, не будут их использовать.

7. Зачем два хранилища метаданных?

Вам может быть интересно, зачем нам два места для хранения данных вашего NFT? Разве мы не можем просто хранить все в Metadata Account?

Есть несколько проблем с этим.

Во-первых, хранение данных ончейн стоит денег. При разработке аккаунтов, используемых тысячами людей, вы должны помнить о цене, в которую обойдется их создание.
Во-вторых, ончейн данные гораздо менее гибкие. После создания аккаунта с использованием определенной структуры его нельзя легко изменить. Поэтому, если бы нам пришлось хранить все ончейн, мы бы значительно ограничили количество данных, которые можно прикрепить к NFT.

В результате нам необходимо грамотно и безопасно разделить данные на две категории: on-chain и off-chain. Например, массив Creators — ончейн, потому что нам нужен надежный способ узнать, действительно ли NFT был предложен и подписан данным исполнителем. Атрибут Is Mutable — ончейн, потому что нам нужно гарантировать, что после того, как он будет изменен на false, его нельзя будет вернуть обратно.

В итоге, Token Metadata Program может создать гарантии и ожидания для on-chain данных, но не может делать этого для off-chain данных.

Однако это не обязательно означает, что оффчейн JSON-файл небезопасен и ему нельзя доверять. Блокчейны постоянного хранения, такие как Arweave, обычно используются для хранения как цифровых активов, так и метаданных JSON, которые на них ссылаются, обеспечивая неизменность оффчейн данных. Кроме того, NFT можно сделать неизменяемыми, гарантируя, что атрибут URI у Metadata Account никогда не будет указывать на другое место. Это самая безопасная конфигурация NFT, поскольку гарантируется, что ее нельзя будет изменить.

Также обратите внимание, что некоторым проектам NFT может потребоваться, чтобы их данные были изменяемыми таким образом, чтобы это было выгодно владельцам NFT. Например, если вы планируете создать NFT детеныша обезьяны, который постепенно превращается во взрослую обезьяну, вам нужно, чтобы метаданные JSON хранились на сервере, который вы контролируете, чтобы делать эти постепенные изменения. В следующий раз, когда владельцы NFT откроют свои кошельки, они увидят другое изображение, но скорее обрадуются, чем возмутятся. Я хочу сказать, что до тех пор, пока вы доверяете создателям ваших NFT, что гарантируется флагом Verified в ончейн атрибуте Creators, изменяемые оффчейн данные могут быть подлинными. Но, конечно же, не забывайте о DYOR.

8. Печать нескольких выпусков

По больше части мы уже понимаем, как представлены нфт в солане. Но не до конца. Существует еще один важный аккаунт, предлагаемый Token Metadata Program, полученный из минт аккаунта (с помощью PDA).

Фактически, аккаунт, находящийся внутри этого PDA, может быть одного из двух различных типов. Это может быть либо «Master Edition», либо «Edition».

«Master Edition», также известный как «Original Edition», — это NFT, которое может быть продублировано его владельцем определенное количество раз, определяемое атрибутом «Max Supply».

«Edition», также известный как «Print Edition», — это NFT, которое было продублировано с «Master Edition». Всякий раз, когда создается новый «Edition», он отслеживает свой родительский «Master Edition» и его номер издания. Он также увеличивает supply своего родительского «Master Edition». Как только саплай достигает максимального саплая, больше NFT не могут быть напечатаны таким образом. Обратите внимание, что «Max Supply» у «Master Edition» может быть null, что означает, что из него можно распечатать неограниченное количество NFT.

Также обратите внимание, что еще один — менее известный — PDA аккаунт под названием «Edition Marker» существует в «Edition» NFT, для обеспечения отсутствия дублирования между номерами изданий данного «Master Edition».

Одним из вариантов использования этой функции является предоставление художникам возможности продавать более одной копии своих работ. Например, они могут выпустить 100 ограниченных выпусков своего 1/1 NFT, и каждый из них будет отслеживать номер своего издания ончейн.

Стоит отметить, что печать нескольких выпусков NFT совершенно необязательна, и большинство NFT устанавливают для своего «Max Supply» значение 0, чтобы предотвратить его использование.

Хотя печать изданий является основной задачей «Master Editions» и «Editions», они отвечают не только за это.

Если вы помните, ранее мы говорили, что для того, чтобы «Mint Account» был NFT, нужно:

Иметь Decimals = 0.
Заминтить ровно один токен на аккаунт кошелька.
Отозвать право на минт дополнительных токенов через атрибут «Mint Authority».

Что ж, Token Metadata Program использует Edition PDA, чтобы гарантировать эти свойства. При создании PDA Edition аккаунта (будь то «Master Edition» или «Edition») он проверит, что минт аккаунт имеет Decimals = 0 и Supply = 1. Если какое-либо из этих условий не выполняется, аккаунт не будет создан. Если это удается, то он передает «Mint Authority» этому новому Edition PDA, гарантируя, что ни один кошелек никогда не сможет заминтить дополнительные токены. Это означает, что сам факт существования аккаунта «Master Edition» или «Edition» в минт аккаунте является доказательством его невзаимозаменяемости.

Вот почему счета «Master Edition» и «Edition» важны в Solana NFTs и заслуживают упоминания в этой статье.

Вот небольшое обновление нашей диаграммы NFT. Как вы можете видеть, «Mint Authority» больше не null, а указывает на Edition PDA, который может контролироваться только Token Metadata Program с открытым исходным кодом и аудитом.

9. Стандарт токенов и Semi-Fungible токены

Эта статья была бы неполной, если бы я не упомянул, что Token Metadata Program также поддерживает то, что мы называем «Semi-Fungible Tokens» (полувзаимозаменяемые токены) или сокращенно SFT.

SFT в основном такие же, как NFT, но без невзаимозаменяемых гарантий, о которых мы говорили ранее.

«Но почему?», спросите вы, «я думал, что все дело в невзаимозаменяемости?».

Ну, для NFT — да, но, если подумать, основная цель «Metadata Account» — добавление данных к токенам. Почему мы должны ограничивать эту функцию только невзаимозаменяемыми токенами?

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

Другим вариантом использования этого будет создание игрового актива в виде токена с Decimals = 0. Например, вы можете создать токен для ресурса «Wood» в своей игре. Поскольку игроки должны иметь возможность владеть и торговать более чем одним деревом, нет особого смысла создавать один NFT для каждого отдельного куска дерева в вашей игре. Вот почему создание взаимозаменяемых игровых ресурсов при сохранении преимуществ от ончейн данных является очень ценным.

Таким образом, Token Metadata Program позволяет нам создавать Metadata Accounts для минт аккаунтов, которые являются взаимозаменяемыми. Именно поэтому ответственность за гарантию отсутствия взаимозаменяемости лежит на Edition PDA.

Чтобы облегчить нам жизнь, аккаунт метаданных отслеживает, «насколько взаимозаменяем» токен, с помощью атрибута «Token Standard». Это может быть одно из следующих значений.

`NonFungible`

Если стандарт токена NonFungible, мы знаем, что имеем дело с NFT. Этот стандарт применяется тогда и только тогда, когда для этого минта был создан аккаунт «Master Edition» или «Edition».

Это означает, что у нас есть следующие гарантии:

Supply = 1.
Decimals = 0.
Аккаунт существует под Edition PDA.
Mint Authority было передано Edition PDA.

`FungibleAsset`

Если стандарт токена — FungibleAsset, мы знаем, что имеем дело с недесятичным SFT. Например, наш пример ресурса «Wood» будет обозначен как FungibleAsset.

Это означает, что у нас есть следующие гарантии:

Decimals = 0.
Под Edition PDA не существует аккаунта.

`Fungible`

Если стандарт токена — Fungible, мы знаем, что имеем дело с десятичным SFT. Например, токен Avocado или токен USDC подходят под эту категорию.

Это означает, что у нас есть следующие гарантии:

Decimals > 0 (строго больше 0).
Под Edition PDA не существует аккаунта.

Стоит отметить, что стандарт оффчейн JSON метаданных варьируется в зависимости от «Token Standard», о котором мы только что говорили. Вы можете найти определение JSON стардарта для каждого типа токена ниже.

10. Заключение

Теперь мы не только имеем полное представление о том, как выглядят NFT и SFT в Solana, но и понимаем, почему вещи устроены так, как они есть, и как они сравниваются с другими привычными нам моделями.

Эта статья была бы неполной без заключительной диаграммы, резюмирующей то, что мы здесь узнали.

И чтобы сделать эту диаграмму еще более полезной для разработчиков, давайте также добавим смещение и размер каждого атрибута аккаунта в байтах. Я буду использовать тильду ~ для переменных размеров аккаунта.

На этом всё! ❤️

11. Доп. материалы на эту тему

Solana’s Token Program, Explained: https://pencilflip.medium.com/solanas-token-program-explained-de0ddce29714

Understanding Program Derived Addresses: https://www.brianfriel.xyz/understanding-program-derived-addresses/

Metaplex Docs (Token Metadata): https://docs.metaplex.com/programs/token-metadata/

Solana Docs (Programming Model): https://docs.solana.com/developing/programming-model/overview

Solana Cookbook (Core Concepts): https://solanacookbook.com/core-concepts/accounts.html

Solana Wiki (Account Model): https://solana.wiki/zh-cn/docs/account-model/#account-storage