НОВОЕ: кольца конфиденциальности Solana уже доступны в основной сети
Фреймы Solana: выпуск cNFT в Farcaster
Блог/Разработка

Фреймы Solana: выпуск cNFT в Farcaster

Developer Experience Engineer0xIchigo в X0xIchigo в LinkedIn0xIchigo на GitHub
Чтение: 12 мин

О чем эта статья?

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

В этой статье мы рассмотрим Farcaster и недавно появившуюся поддержку Solana. Вы узнаете, что такое Farcaster и фреймы, а также как подтвердить адрес Solana. Затем мы кратко расскажем, как с помощью Helius Mint API создать фрейм, который выпускает cNFT на подтвержденный адрес Solana пользователя. Для прохождения руководства предполагается базовый опыт работы с TypeScript и Next.js.

Что такое Farcaster?

Farcaster — это достаточно децентрализованная социальная сеть, которая использует сеть Ethereum. Она предлагает общедоступную платформу, похожую на популярные социальные сети вроде Twitter и Reddit. Пользователи могут создавать профили, публиковать записи, известные как касты, и подписываться на других пользователей. Отличительная черта Farcaster — акцент на владении и переносимости: пользователи сами владеют своими учетными записями и связями с другими людьми. Они могут переходить между разными приложениями, сохраняя цифровую идентичность и социальный граф.

Что такое фреймы?

Фреймы позволяют разработчикам превращать любой каст в интерактивное приложение. Расширяя стандарт OpenGraph, они превращают статические встраиваемые элементы в динамичные интерактивные интерфейсы. Благодаря этому пользователи могут создавать опросы, ленты в реальном времени и интерактивные галереи в любом клиенте Farcaster, включая Warpcaster. По своей сути фрейм — это набор тегов <meta>, возвращаемых вместе с <head> HTML-страницы. Приложения Farcaster отображают страницу как фрейм, если она содержит все обязательные свойства фрейма. Эти свойства перечислены в спецификации фреймов. Например, начальный фрейм должен:

  • Возвращать допустимый фрейм в разделе HTML <head>
  • Возвращать допустимый HTML <body> на случай, если пользователь откроет фрейм в браузере
  • Не содержать динамический контент в начальном фрейме, поскольку клиенты Farcaster кэшируют его
  • Не содержать тег fc:frame:state

Подтверждение адреса Solana в Farcaster

Недавно Farcaster добавил поддержку адресов Solana. Теперь разработчики могут создавать фреймы, которые взаимодействуют с кошельком Solana пользователя. Менее чем за 24 часа после запуска поддержки более 9328 уникальных FID Farcaster подтвердили адрес Solana.

Чтобы подтвердить адрес Solana, пользователю нужно:

  • Перейти в Настройки
  • Открыть раздел Подтвержденные адреса и нажать кнопку «Подтвердить адрес»
  • Подключить кошелек Solana и подписать сообщение, чтобы подтвердить владение им

Обратите внимание, что сейчас поддерживается только кошелек Phantom.

Руководство: создание фрейма для выпуска cNFT

В этой статье мы создадим фрейм, с помощью которого пользователи с подтвержденным адресом Solana смогут выпустить сжатый NFT (cNFT). Для инициализации проекта мы используем frames.js — шаблон Next.js для создания и отладки фреймов. Чтобы получать информацию о пользователе Farcaster при его взаимодействии с фреймом, мы воспользуемся OnchainKit от Coinbase, а именно Frame Kit. Затем передадим эти данные в Helius Mint API, чтобы выпустить следующий cNFT в кошелек Solana пользователя:

Настройка фрейма

Чтобы создать фрейм с помощью frame.js, достаточно клонировать стартовый шаблон. Выполните следующую команду, заменив <name> названием новой папки, в которую хотите клонировать шаблон:

Код
npx degit github:framesjs/frames.js/examples/framesjs-starter#main <name>

Я решил назвать каталог helius-frame, поэтому заменил <name> на <helius-frame>. Затем перейдите в новый каталог (например, cd helius-frame) и установите необходимые зависимости командой yarn install. После завершения загрузки выполните yarn dev, чтобы запустить сервер разработки. Откройте http://localhost:3000 в браузере. Вы увидите следующее:

Нажав ссылку Debug, мы перейдем на страницу http://localhost:3000/debug:

Это удобно, поскольку мы можем тестировать фрейм локально без развертывания. Например, можно войти в систему для проверки кнопок, имитировать действия других пользователей и создавать фиктивное состояние хаба. В Warpcaster также есть отличный инструмент Frame Validator для проверки фреймов. Далее мы будем использовать Frame Validator исключительно из личных предпочтений. 

Затем выполните yarn install, чтобы установить необходимые зависимости шаблона. Также выполните yarn install @coinbase/onchainkit, чтобы установить OnchainKit.

Изменим структуру папок проекта следующим образом:

  • Удалите папку examples. Примеры помогают разобраться в создании фреймов, но для нашей задачи они не нужны. Удаление этой папки уменьшит объем проекта. Тем не менее настоятельно рекомендую изучить примеры, чтобы узнать об альтернативных способах создания распространенных фреймов
  • Создайте папку api в каталоге app. Этот шаг соответствует соглашениям Next.js для маршрутов API и четко разделяет фронтенд и бэкенд приложения. Затем переместите папку frames вместе с ее содержимым — route.ts — в новую папку api.
  • Создайте папку utils в каталоге app. В ней создайте файл mint.ts — здесь будет находиться логика выпуска cNFT

Теперь можно приступить к созданию фрейма!

Редактирование фрейма

layout.tsx

Начнем с файла layout.tsx. Удалите все его содержимое и замените следующим кодом:

Код
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    
      {children}
    
  );
}

Компонент RootLayout использует минималистичный подход и оборачивает все приложение в единую структуру макета. Он гибок и подходит для повторного использования. Разработчики могут взять этот минималистичный макет за основу и при необходимости создавать и настраивать собственные фреймы.

Обратите внимание: после изменения файла layout.tsx возникнут проблемы с локальным отладчиком. Редактировать layout.tsx необязательно. Мы делаем это, чтобы задать метаданные приложения в page.tsx. В качестве обходного решения метаданные можно добавить в этот файл. 

page.tsx

Удалите содержимое page.tsx и замените его следующим кодом:

Код
import type { Metadata } from "next";
import { getFrameMetadata } from "@coinbase/onchainkit";

const baseURL = "https://helius-frame.vercel.app/";

const frameMetadata = getFrameMetadata({
  image: {
    src: `${baseURL}/default.jpg`,
    aspectRatio: "1:1",
  },
  buttons: [
    {
      label: "Click to mint a cNFT on Solana!",
      action: "post",
    },
  ],
  postUrl: `${baseURL}api/frames`,
});

export const metadata: Metadata = {
  title: "Mint a cNFT on Solana",
  description: "Mint a cNFT to your verified Solana address using the Helius Mint API",
  openGraph: {
    title: "Mint a cNFT on Solana",
    description: "Mint a cNFT to your verified Solana address using the Helius Mint API",
    images: ["https://helius-frame.vercel.app/default.jpg"],
  },
  other: {
    ...frameMetadata,
  },
};

export default function Page() {
  return (
    
      Mint a cNFT on Farcaster using the Helius Mint API
      
        Built by 0xIchigo
      
      
        GitHub Repo
      
    
  );
}

Приведенный выше код настраивает начальный фрейм, который будет доступен по URL на веб-сервере. В моем случае начальный фрейм размещен на Vercel по адресу https://helius-frame.vercel.app/. Позже в этом руководстве мы рассмотрим развертывание с помощью Vercel.  

Сначала мы импортируем тип Metadata из Next.js для типизации экспорта metadata в этом файле. Также импортируем getFrameMetadata из @coinbase/onchainkit. Затем определяем базовый URL приложения, чтобы избежать повторения кода.

После этого вызываем getFrameMetadata, чтобы настроить метаданные начального фрейма. Эти метаданные включают:

  • Изображение (то есть src), которое служит визуальным элементом фрейма и имеет соотношение сторон 1:1
  • Кнопку с надписью «Нажмите, чтобы выпустить cNFT в Solana!». При нажатии она отправляет POST-запрос на указанный postUrl (то есть ${baseURL}api/frames). Это действие запускает процесс выпуска

Затем мы экспортируем объект metadata, который содержит заголовок и описание страницы, метаданные OpenGraph (то есть openGraph), а также ранее определенный frameMetadata, развернутый в свойство other.

Наконец, page определяет и экспортирует компонент страницы по умолчанию. Мы возвращаем простой h1 с предложением выпустить cNFT. Это необходимо, поскольку Farcaster требует возвращать какой-либо HTML. Основное взаимодействие происходит через фреймы, а не непосредственно на сайте. Однако если пользователь перейдет на сайт, там все равно должно что-то отображаться. 

mint.ts 

Вставьте следующий код в mint.ts:

Код
const url = `Get a URL at dev.helius.xyz`;

export const mintCompressedNFT = async (address: string) => {
    const response = await fetch(url, {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
        },
        body: JSON.stringify({
            jsonrpc: "2.0",
            id: "frames-sol-mint",
            method: "mintCompressedNft",
            params: {
                name: "Solana Soldier",
                symbol: "HELIUS",
                owner: address,
                description: "A decentralized warrior backed by Solana's most loved RPC Nodes, APIs, Webhooks, and Developer Tooling",
                attributes: [
                    {
                        trait_type: "RPCs",
                        value: "Fast",
                    },
                    {
                        trait_type: "Company",
                        value: "Helius"
                    },
                ],
                imageUrl: "https://shdw-drive.genesysgo.net/HmvVwYAy7cxWECLbu2cjWBSHysVoriTqgdugyePVg3rY/cnftmint.jpg",
                externalUrl: "https://www.helius.dev/",
                sellerFeeBasisPoints: 6900,
            },
        }),
    });

    const data = await response.json();
    console.log(`data: ${JSON.stringify(data, null, 2)}`);

    if (!response.ok) {
        throw new Error(`The response was not okay - ${response.status}`);
    }

    if (!data.result || !data.result.assetId) {
        throw new Error(`The response did not include the expected data.result.assetId field`);
    }

    return data.result;
};

Вспомогательная функция mintCompressedNFT играет ключевую роль в приложении: она выпускает заранее заданный cNFT на указанный адрес. С помощью Helius Mint API мы создаем простую, многократно используемую асинхронную функцию, которая инкапсулирует процесс выпуска cNFT. Нам потребуется URL Helius General RPC, заданный как url. Если у вас его еще нет, откройте панель управления Helius и бесплатно создайте URL RPC для url.

Обратите внимание, что в моем репозитории используется URL SecureRPC. Не допускайте утечки ключа API и рассмотрите возможность запуска прокси-сервера. Полное описание схемы запроса доступно здесь.

Также обратите внимание, что я заранее загрузил изображение для cNFT в ShdwDrive. На момент написания статьи Farcaster еще не поддерживал транзакции полностью. Helius Mint API загружает офчейн-метаданные в Arweave, если указан подписант.

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

route.ts 

Вставьте следующий код в api/frames/route.ts:

Код
import { NextRequest, NextResponse} from "next/server";
import { getFrameMessage, getFrameHtmlResponse } from "@coinbase/onchainkit/frame";
import { mintCompressedNFT } from "../../utils/mint";

const baseURL = "https://helius-frame.vercel.app/";

export async function POST(req: NextRequest): Promise {
    const body = await req.json();

    // Validate the frame message and extract the user ID
    const { isValid, message } = await getFrameMessage(body, {
        neynarApiKey: "NEYNAR_ONCHAIN_KIT",
    });

    console.log(JSON.stringify(message, null, 2));

    // Make sure they're following us before they can mint the cNFT
    if (isValid && !message.following) {
        return new NextResponse(getFrameHtmlResponse({
            image: {
                src: `${baseURL}/error.jpg`,
                aspectRatio: "1:1",
            },
            buttons: [
                {
                  label: "You need to be following to mint! Click to retry",
                  action: "post",
                },
            ],
            postUrl: `${baseURL}api/frames`,
        }));
    // Make sure they have a verified Solana address
    } else if (isValid && message.interactor.verified_addresses.sol_addresses) {
        const solanaAddresses = message.interactor.verified_addresses.sol_addresses;
        console.log(`SOLANA ADDRESSES: ${solanaAddresses}`);

        if (solanaAddresses.length !== 0) {
            try {
                console.log(`MINTING to ${solanaAddresses[0]}`);
                // We take the first address address, in case there's more than one
                const mintResult = await mintCompressedNFT(solanaAddresses[0]!);
              
                return new NextResponse(getFrameHtmlResponse({
                    image: {
                        src: `${baseURL}/success.jpg`,
                        aspectRatio: "1:1",
                    },
                    buttons: [
                        {
                            label: "Success! View your cNFT on XRAY",
                            action: "link",
                            target: `https://xray.helius.xyz/token/${mintResult.assetId}?network=mainnet`
                        },
                    ],
                }));
            } catch (e: any) {
                console.log(`Minting failed: ${e}`);
                return new NextResponse(getFrameHtmlResponse({
                    image: {
                        src: `${baseURL}/error.jpg`,
                        aspectRatio: "1:1",
                    },
                    buttons: [
                        {
                          label: "Minting failed. Click to retry",
                          action: "post",
                        },
                    ],
                    postUrl: `${baseURL}api/frames`,
                }));
            }
        } else {
            console.log(`No Solana address found`);
            return new NextResponse(getFrameHtmlResponse({
                image: {
                    src: `${baseURL}/error.jpg`,
                    aspectRatio: "1:1",
                },
                buttons: [
                    {
                      label: "No Solana address found. Click to retry",
                      action: "post",
                    },
                ],
                postUrl: `${baseURL}api/frames`
            }));
        }
    } else {
        return new NextResponse(getFrameHtmlResponse({
            image: {
                src: `${baseURL}/error.jpg`,
                aspectRatio: "1:1",
            },
            buttons: [
                {
                  label: "Invalid frame message. Click to retry",
                  action: "post",
                },
            ],
            postUrl: `${baseURL}api/frames`,
        }));
    }
}

Этот файл представляет собой маршрут API Next.js, который обрабатывает все POST-запросы фрейма. Сначала файл импортирует NextRequest и NextResponse из next/server для обработки входящих запросов и отправки ответов. Мы также импортируем getFrameMessage и getFrameHtmlResponse из @coinbase/onchainkit/frame, чтобы проверять сообщения фрейма и формировать HTML-ответы для взаимодействий с ним. Кроме того, импортируем вспомогательную функцию mintCompressedNFT.

baseURL определен для сокращения повторяющегося кода. Он используется для построения путей к ресурсам и конечным точкам API.

Файл экспортирует функцию POST, которая анализирует тело входящего запроса и извлекает сообщение фрейма. С помощью getFrameMessage мы проверяем допустимость входящего взаимодействия с фреймом и полезной нагрузки сообщения. Для этого передаем тело запроса в формате JSON и стандартный ключ API Neynar (то есть “NEYNAR_ONCHAIN_KIT”). Neynar — платформа для разработчиков, упрощающая разработку для Farcaster. getFrameMessage возвращает Promise, который разрешается в FrameValidationResponse. Он определяется следующим образом:

Код
export type FrameValidationResponse =
  | { isValid: true; message: FrameValidationData }
  | { isValid: false; message: undefined };

Таким образом, если взаимодействие с фреймом допустимо, функция возвращает сообщение типа FrameValidationData. Он определяется следующим образом:

Код
export interface FrameValidationData {
  button: number; // Number of the button clicked
  following: boolean; // Indicates if the viewer clicking the frame follows the cast author
  input: string; // Text input from the viewer typing in the frame
  interactor: {
    fid: number; // Viewer Farcaster ID
    custody_address: string; // Viewer custody address
    verified_accounts: string[]; // Viewer account addresses
    verified_addresses: {
      eth_addresses: string[] | null;
      sol_addresses: string[] | null;
    };
  };
  liked: boolean; // Indicates if the viewer clicking the frame liked the cast
  raw: NeynarFrameValidationInternalModel;
  recasted: boolean; // Indicates if the viewer clicking the frame recasted the cast
  valid: boolean; // Indicates if the frame is valid
}

Это особенно важно, поскольку сообщение содержит полезные данные: Farcaster ID пользователя, наличие подтвержденных адресов Ethereum или Solana и информацию о том, поставил ли пользователь отметку «Нравится» касту. В этом руководстве мы хотим проверить, подписан ли пользователь, который пытается выпустить cNFT, на мой профиль. Если да, мы разрешим ему выпуск. Также нужно убедиться, что у пользователя есть подтвержденный адрес Solana, на который можно выпустить cNFT.

Сначала мы проверяем допустимость взаимодействия и подписку пользователя на мою учетную запись. Если проверка не пройдена, пользователь увидит сообщение об ошибке и кнопку для повторной попытки. Затем проверяем наличие подтвержденного адреса Solana. Если найден один или несколько адресов, запускаем процесс выпуска. Мы берем первый подтвержденный адрес Solana и передаем его в mintCompressedNFT. В случае успеха возвращаем изображение, сообщающее об успешной операции, и ссылку для просмотра cNFT в Orb. При сбое записываем ошибку в журнал и предлагаем пользователю повторить попытку. Если подтвержденные адреса Solana не найдены, возвращаем сообщение об отсутствии подтвержденного адреса Solana и предлагаем повторить попытку. Наконец, если сообщение фрейма недопустимо, сообщаем об ошибке фрейма и также предлагаем повторить попытку.

Код использует getFrameHtmlResponse для формирования HTML-ответов с учетом конкретных результатов выпуска или проверок. В частности, он задает изображения, соотношения сторон и кнопки для определенных взаимодействий с пользователем.

Публикация в рабочей среде

Теперь создайте новый репозиторий GitHub и отправьте в него код. Чтобы отправить код на GitHub, выполните в командной строке следующие команды:

Код
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/<username>/<new repo name>.git
git branch -M main
git push -u origin main

После отправки кода на GitHub необходимо развернуть приложение. Vercel легко интегрируется с GitHub и упрощает весь процесс развертывания, поэтому воспользуемся этой платформой. Для этого:

  • Войдите в учетную запись на сайте Vercel. Если у вас нет учетной записи, создайте ее. Бесплатного и достаточно щедрого тарифа Hobby хватит для наших целей
  • После входа откройте панель управления и нажмите кнопку New Project. Vercel предложит импортировать проект из GitHub. Выберите репозиторий, созданный на предыдущем шаге
  • Vercel автоматически определит используемый фреймворк и предложит настройки сборки. Vercel создан разработчиками Next.js и обеспечивает его первоклассную поддержку, поэтому сложная настройка не потребуется
  • Настроив проект, нажмите кнопку Deploy. Vercel автоматически запустит процесс развертывания, соберет проект и разместит его по уникальному URL Vercel. 
  • После развертывания Vercel предоставит уникальный URL для доступа к работающему приложению. Мой проект доступен по адресу https://helius-frame.vercel.app/ — это название репозитория GitHub с окончанием .vercel.app. В настройках проекта Vercel также можно подключить собственный домен

Готово! Выполнив эти шаги, мы отправили фрейм Farcaster на GitHub и разместили его на Vercel. Проверить работу фрейма можно с помощью упомянутых выше инструментов тестирования, например валидатора фреймов. Осталось только опубликовать каст с URL фрейма!

Заключение

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

Спасибо, что дочитали до конца, анон! Если вы хотите присоединиться к Farcaster, воспользуйтесь этой ссылкой-приглашением!

Укажите свой адрес электронной почты ниже, чтобы не пропускать новости Solana. Хотите узнать больше? Читайте свежие статьи в блоге Helius и продолжайте знакомство с Solana уже сегодня.

Дополнительные ресурсы

Подпишитесь на Helius

Следите за новостями разработки на Solana и получайте уведомления о наших публикациях

Увеличенное изображение