diff --git a/README.md b/README.md index 18d492b..520153e 100644 --- a/README.md +++ b/README.md @@ -1,51 +1,200 @@ # Solana Actions and Blockchain Links (Blinks) +[![NPM Downloads](https://img.shields.io/npm/dm/@solana/actions.svg)](https://www.npmjs.com/package/@solana/actions) + [Read the docs to get started](https://solana.com/docs/advanced/actions) -Watch this video tutorial on -[How to Build Solana Actions](https://youtu.be/kCht01Ycif0) +Install the `@solana/actions` SDK into your application: -Find -[more resources for Solana Actions and blinks](https://solana.com/solutions/actions) +```bash +npm add @solana/actions +``` -Find example code snippets on how to build several different Solana Actions: +- **NPM Package**: [@solana/actions](https://www.npmjs.com/package/@solana/actions) +- **Typedocs Documentation**: [Explore the full API documentation](https://solana-developers.github.io/solana-actions/) -- [Deployed sample code snippets](https://solana-actions.vercel.app/) -- [Source code for code snippets](https://github.com/solana-developers/solana-actions/tree/main/examples/next-js) +--- -Install the `@solana/actions` SDK into your application: +## Table of Contents -```shell -npm add @solana/actions -``` +1. [Developer Resources](#developer-resources) +2. [What are Solana Actions?](#what-are-solana-actions) +3. [What are Blockchain Links (Blinks)?](#what-are-blockchain-links-blinks) +4. [Core Functions of the SDK](#core-functions-of-the-sdk) + - [Creating Action Headers](#1-creating-action-headers) + - [Creating a Typed `actions.json` Payload](#2-creating-a-typed-actionsjson-payload) + - [Handling GET Requests](#3-handling-get-requests) + - [Processing POST Responses](#4-processing-post-responses) +5. [License](#license) + +--- + +## Developer Resources -- `@solana/actions` SDK on NPM: - - https://www.npmjs.com/package/@solana/actions -- Typedocs for the `@solana/actions` SDK: - - https://solana-developers.github.io/solana-actions/ +- **Video Tutorial**: [How to Build Solana Actions](https://youtu.be/kCht01Ycif0) +- **More Resources**: [Solana Actions and Blinks Overview](https://solana.com/solutions/actions) +- **Example Code**: + - [Deployed sample code snippets](https://solana-actions.vercel.app/) + - [Source code for code snippets](https://github.com/solana-developers/solana-actions/tree/main/examples/next-js) + +--- ## What are Solana Actions? -[Solana Actions](https://solana.com/docs/advanced/actions#actions) are -specification-compliant APIs that return transactions on the Solana blockchain -to be previewed, signed, and sent across a number of various contexts, including -QR codes, buttons + widgets, and websites across the internet. Actions make it -simple for developers to integrate the things you can do throughout the Solana -ecosystem right into your environment, allowing you to perform blockchain -transactions without needing to navigate away to a different app or webpage. - -## What are blockchain links (blinks)? - -[Blockchain links](https://solana.com/docs/advanced/actions#blinks) – or blinks -– turn any Solana Action into a shareable, metadata-rich link. Blinks allow -Action-aware clients (browser extension wallets, bots) to display additional -capabilities for the user. On a website, a blink might immediately trigger a -transaction preview in a wallet without going to a decentralized app; in -Discord, a bot might expand the blink into an interactive set of buttons. This -pushes the ability to interact on-chain to any web surface capable of displaying -a URL. +[Solana Actions](https://solana.com/docs/advanced/actions#actions) are specification-compliant APIs that return transactions on the Solana blockchain to be previewed, signed, and sent across a number of various contexts, including: + +- QR codes +- Buttons and widgets +- Websites + +Actions make it simple for developers to integrate Solana blockchain transactions into their environments, enabling users to perform actions without navigating to another app or webpage. + +--- + +## What are Blockchain Links (Blinks)? + +[Blockchain links](https://solana.com/docs/advanced/actions#blinks), or **blinks**, are metadata-rich URLs that turn any Solana Action into a shareable link. Blinks enable: + +- **Enhanced Interactions**: Trigger transaction previews directly in wallets or bots. +- **Cross-Platform Functionality**: Enable actions across websites, Discord bots, and browser extension wallets. + +--- + +## Core Functions of the SDK + +### 1. Creating Action Headers + +The `createActionHeaders` function generates standardized headers for Action APIs: + +```typescript +import { createActionHeaders } from "@solana/actions"; + +// Basic headers +const basicHeaders = createActionHeaders(); + +// Headers with chain ID and version +const customHeaders = createActionHeaders({ + chainId: "mainnet-beta", + actionVersion: "1", + headers: { + "Custom-Header": "value", + }, +}); + +// Headers structure +console.log(customHeaders); +/* +{ + 'X-Blockchain-Ids': 'solana:mainnet-beta', + 'X-Action-Version': '1', + 'Custom-Header': 'value', + // ...CORS headers +} +*/ +``` + +--- + +### 2. Creating a Typed `actions.json` Payload + +Define your Action's metadata and interface: + +```typescript +import { ActionGetResponse } from "@solana/actions"; + +const actionsConfig: ActionGetResponse = { + type: "action", + title: "Token", + icon: "https://example.com/icon.png", + description: "Transfer tokens between wallets", + label: "Transfer", + links: { + actions: [ + { + label: "Send Tokens", + href: "/api/transfer?amount={amount}&token={tokenMint}", + parameters: [ + { + name: "amount", + label: "Amount to send", + required: true, + type: "number", + }, + { + name: "tokenMint", + label: "Token Address", + required: true, + type: "string", + }, + ], + }, + ], + }, +}; +``` + +--- + +### 3. Handling GET Requests + +Create typed GET request handlers for your Actions: + +```typescript +import { ActionGetResponse } from "@solana/actions"; + +export async function GET(req: Request) { + // Extract and validate query parameters + const { searchParams } = new URL(req.url); + const amount = searchParams.get("amount"); + const tokenMint = searchParams.get("tokenMint"); + + const response: ActionGetResponse = { + type: "action", + title: `Transfer ${amount} Tokens`, + description: `Send ${amount} tokens to another wallet`, + label: "Confirm Transfer", + // Additional metadata... + }; + + return new Response(JSON.stringify(response), { + headers: createActionHeaders(), + }); +} +``` + +--- + +### 4. Processing POST Responses + +Handle transaction creation and responses: + +```typescript +import { ActionPostResponse, createPostResponse } from "@solana/actions"; + +export async function POST(req: Request) { + // Create and sign your transaction + const transaction = await createTransferTransaction(/* ... */); + + // Generate typed response with signed transaction + const response = await createPostResponse({ + fields: { + transaction, + // Optional: Add more response fields + meta: { + label: "Transfer Complete", + message: "Tokens transferred successfully" + } + } + }); + + return new Response(JSON.stringify(response), { + headers: createActionHeaders() + }); +} +``` + +--- ## License -The Solana Actions JavaScript SDK is open source and available under the Apache -License, Version 2.0. See the [LICENSE](./LICENSE) file for more info. +The Solana Actions JavaScript SDK is open source and available under the Apache License, Version 2.0. See the [LICENSE](./LICENSE) file for more information. \ No newline at end of file diff --git a/packages/solana-actions/README.md b/packages/solana-actions/README.md index 786879e..520153e 100644 --- a/packages/solana-actions/README.md +++ b/packages/solana-actions/README.md @@ -1,53 +1,200 @@ # Solana Actions and Blockchain Links (Blinks) +[![NPM Downloads](https://img.shields.io/npm/dm/@solana/actions.svg)](https://www.npmjs.com/package/@solana/actions) + [Read the docs to get started](https://solana.com/docs/advanced/actions) Install the `@solana/actions` SDK into your application: -```shell +```bash npm add @solana/actions ``` -- `@solana/actions` SDK on NPM: - - https://www.npmjs.com/package/@solana/actions -- Typedocs for the `@solana/actions` SDK: - - https://solana-developers.github.io/solana-actions/ +- **NPM Package**: [@solana/actions](https://www.npmjs.com/package/@solana/actions) +- **Typedocs Documentation**: [Explore the full API documentation](https://solana-developers.github.io/solana-actions/) + +--- + +## Table of Contents -## Developer resources +1. [Developer Resources](#developer-resources) +2. [What are Solana Actions?](#what-are-solana-actions) +3. [What are Blockchain Links (Blinks)?](#what-are-blockchain-links-blinks) +4. [Core Functions of the SDK](#core-functions-of-the-sdk) + - [Creating Action Headers](#1-creating-action-headers) + - [Creating a Typed `actions.json` Payload](#2-creating-a-typed-actionsjson-payload) + - [Handling GET Requests](#3-handling-get-requests) + - [Processing POST Responses](#4-processing-post-responses) +5. [License](#license) -Watch this video tutorial on -[How to Build Solana Actions](https://youtu.be/kCht01Ycif0) +--- -Find -[more resources for Solana Actions and blinks](https://solana.com/solutions/actions) +## Developer Resources -Find example code snippets on how to build several different Solana Actions: +- **Video Tutorial**: [How to Build Solana Actions](https://youtu.be/kCht01Ycif0) +- **More Resources**: [Solana Actions and Blinks Overview](https://solana.com/solutions/actions) +- **Example Code**: + - [Deployed sample code snippets](https://solana-actions.vercel.app/) + - [Source code for code snippets](https://github.com/solana-developers/solana-actions/tree/main/examples/next-js) -- [Deployed sample code snippets](https://solana-actions.vercel.app/) -- [Source code for code snippets](https://github.com/solana-developers/solana-actions/tree/main/examples/next-js) +--- ## What are Solana Actions? -[Solana Actions](https://solana.com/docs/advanced/actions#actions) are -specification-compliant APIs that return transactions on the Solana blockchain -to be previewed, signed, and sent across a number of various contexts, including -QR codes, buttons + widgets, and websites across the internet. Actions make it -simple for developers to integrate the things you can do throughout the Solana -ecosystem right into your environment, allowing you to perform blockchain -transactions without needing to navigate away to a different app or webpage. - -## What are blockchain links (blinks)? - -[Blockchain links](https://solana.com/docs/advanced/actions#blinks) – or blinks -– turn any Solana Action into a shareable, metadata-rich link. Blinks allow -Action-aware clients (browser extension wallets, bots) to display additional -capabilities for the user. On a website, a blink might immediately trigger a -transaction preview in a wallet without going to a decentralized app; in -Discord, a bot might expand the blink into an interactive set of buttons. This -pushes the ability to interact on-chain to any web surface capable of displaying -a URL. +[Solana Actions](https://solana.com/docs/advanced/actions#actions) are specification-compliant APIs that return transactions on the Solana blockchain to be previewed, signed, and sent across a number of various contexts, including: + +- QR codes +- Buttons and widgets +- Websites + +Actions make it simple for developers to integrate Solana blockchain transactions into their environments, enabling users to perform actions without navigating to another app or webpage. + +--- + +## What are Blockchain Links (Blinks)? + +[Blockchain links](https://solana.com/docs/advanced/actions#blinks), or **blinks**, are metadata-rich URLs that turn any Solana Action into a shareable link. Blinks enable: + +- **Enhanced Interactions**: Trigger transaction previews directly in wallets or bots. +- **Cross-Platform Functionality**: Enable actions across websites, Discord bots, and browser extension wallets. + +--- + +## Core Functions of the SDK + +### 1. Creating Action Headers + +The `createActionHeaders` function generates standardized headers for Action APIs: + +```typescript +import { createActionHeaders } from "@solana/actions"; + +// Basic headers +const basicHeaders = createActionHeaders(); + +// Headers with chain ID and version +const customHeaders = createActionHeaders({ + chainId: "mainnet-beta", + actionVersion: "1", + headers: { + "Custom-Header": "value", + }, +}); + +// Headers structure +console.log(customHeaders); +/* +{ + 'X-Blockchain-Ids': 'solana:mainnet-beta', + 'X-Action-Version': '1', + 'Custom-Header': 'value', + // ...CORS headers +} +*/ +``` + +--- + +### 2. Creating a Typed `actions.json` Payload + +Define your Action's metadata and interface: + +```typescript +import { ActionGetResponse } from "@solana/actions"; + +const actionsConfig: ActionGetResponse = { + type: "action", + title: "Token", + icon: "https://example.com/icon.png", + description: "Transfer tokens between wallets", + label: "Transfer", + links: { + actions: [ + { + label: "Send Tokens", + href: "/api/transfer?amount={amount}&token={tokenMint}", + parameters: [ + { + name: "amount", + label: "Amount to send", + required: true, + type: "number", + }, + { + name: "tokenMint", + label: "Token Address", + required: true, + type: "string", + }, + ], + }, + ], + }, +}; +``` + +--- + +### 3. Handling GET Requests + +Create typed GET request handlers for your Actions: + +```typescript +import { ActionGetResponse } from "@solana/actions"; + +export async function GET(req: Request) { + // Extract and validate query parameters + const { searchParams } = new URL(req.url); + const amount = searchParams.get("amount"); + const tokenMint = searchParams.get("tokenMint"); + + const response: ActionGetResponse = { + type: "action", + title: `Transfer ${amount} Tokens`, + description: `Send ${amount} tokens to another wallet`, + label: "Confirm Transfer", + // Additional metadata... + }; + + return new Response(JSON.stringify(response), { + headers: createActionHeaders(), + }); +} +``` + +--- + +### 4. Processing POST Responses + +Handle transaction creation and responses: + +```typescript +import { ActionPostResponse, createPostResponse } from "@solana/actions"; + +export async function POST(req: Request) { + // Create and sign your transaction + const transaction = await createTransferTransaction(/* ... */); + + // Generate typed response with signed transaction + const response = await createPostResponse({ + fields: { + transaction, + // Optional: Add more response fields + meta: { + label: "Transfer Complete", + message: "Tokens transferred successfully" + } + } + }); + + return new Response(JSON.stringify(response), { + headers: createActionHeaders() + }); +} +``` + +--- ## License -The Solana Actions JavaScript SDK is open source and available under the Apache -License, Version 2.0. See the [LICENSE](./LICENSE) file for more info. +The Solana Actions JavaScript SDK is open source and available under the Apache License, Version 2.0. See the [LICENSE](./LICENSE) file for more information. \ No newline at end of file