docs: Add summary; update descriptions (#180)

Author: arcoraven

.github/contributing.md

@@ -14,7 +14,7 @@ For OSS contributions, we use a [Forking Workflow](https://www.atlassian.com/git
 
 To begin:
 
-1. [Create a fork](https://github.com/thirdweb-dev/web3-api/fork) of this repository to your own GitHub account.
+1. [Create a fork](https://github.com/thirdweb-dev/engine/fork) of this repository to your own GitHub account.
 
 2. [Clone your fork](https://help.github.com/articles/cloning-a-repository/) to your local device.
 

core/schema/index.ts

@@ -39,7 +39,7 @@ export const chainResponseSchema = Type.Object({
 
 export const walletAuthSchema = Type.Object({
   "x-backend-wallet-address": Type.String({
-    description: "Wallet address",
+    description: "Backend wallet address",
   }),
   "x-account-address": Type.Optional(
     Type.String({

docs/1-user-guide.md

@@ -1,4 +1,4 @@
-# thirdweb web3-api User Guide
+# thirdweb Engine User Guide
 
 ## Getting Started
 
@@ -25,7 +25,7 @@
 
 ### PostgreSQL DB
 
-A PostgreSQL DB is required to run web3-api, both the server and worker need access to it. Check [installation guide](./.github/installations.md) for more details.
+A PostgreSQL DB is required to run _Engine_, both the server and worker need access to it. Check [installation guide](./.github/installations.md) for more details.
 
 Once you have PostgreSQL DB running set the POSTGRES_CONNECTION_URL environment variable:
 

server/api/backend-wallet/create.ts

@@ -30,7 +30,8 @@ export const createWallet = async (fastify: FastifyInstance) => {
     method: "POST",
     url: "/backend-wallet/create",
     schema: {
-      description: "Create a new backend wallet",
+      summary: "Create backend wallet",
+      description: "Create a backend wallet.",
       tags: ["Backend Wallet"],
       operationId: "backendWallet_create",
       response: {

server/api/backend-wallet/getAll.ts

@@ -34,7 +34,8 @@ export async function getAll(fastify: FastifyInstance) {
     method: "GET",
     url: "/backend-wallet/get-all",
     schema: {
-      description: "Get all created EOA wallet",
+      summary: "Get all backend wallets",
+      description: "Get all backend wallets.",
       tags: ["Backend Wallet"],
       operationId: "backendWallet_getAll",
       response: {

server/api/backend-wallet/getBalance.ts

@@ -39,7 +39,8 @@ export async function getBalance(fastify: FastifyInstance) {
     method: "GET",
     url: "/backend-wallet/:chain/:wallet_address/get-balance",
     schema: {
-      description: "Get Wallet Balance",
+      summary: "Get balance",
+      description: "Get the native balance for a backend wallet.",
       tags: ["Backend Wallet"],
       operationId: "backendWallet_getBalance",
       params: requestSchema,

server/api/backend-wallet/import.ts

@@ -99,7 +99,8 @@ export const importWallet = async (fastify: FastifyInstance) => {
     method: "POST",
     url: "/backend-wallet/import",
     schema: {
-      description: "Import a wallet that has already been created",
+      summary: "Import backend wallet",
+      description: "Import an existing wallet as a backend wallet.",
       tags: ["Backend Wallet"],
       operationId: "backendWallet_import",
       body: RequestBodySchema,

server/api/chain/get.ts

@@ -15,20 +15,18 @@ const responseSchema = Type.Object({
 responseSchema.examples = [
   {
     result: {
-      result: {
-        name: "Mumbai",
-        chain: "Polygon",
-        rpc: ["https://mumbai.rpc.thirdweb.com/${THIRDWEB_API_SECRET_KEY}"],
-        nativeCurrency: {
-          name: "MATIC",
-          symbol: "MATIC",
-          decimals: 18,
-        },
-        shortName: "maticmum",
-        chainId: 80001,
-        testnet: true,
-        slug: "mumbai",
+      name: "Mumbai",
+      chain: "Polygon",
+      rpc: ["https://mumbai.rpc.thirdweb.com/${THIRDWEB_API_SECRET_KEY}"],
+      nativeCurrency: {
+        name: "MATIC",
+        symbol: "MATIC",
+        decimals: 18,
       },
+      shortName: "maticmum",
+      chainId: 80001,
+      testnet: true,
+      slug: "mumbai",
     },
   },
 ];
@@ -42,7 +40,8 @@ export async function getChainData(fastify: FastifyInstance) {
     method: "GET",
     url: "/chain/get",
     schema: {
-      description: "Get a particular chain information",
+      summary: "Get chain details",
+      description: "Get details about a chain.",
       tags: ["Chain"],
       operationId: "chain",
       querystring: chainRequestQuerystringSchema,

server/api/chain/getAll.ts

@@ -53,7 +53,8 @@ export async function getAllChainData(fastify: FastifyInstance) {
     method: "GET",
     url: "/chain/get-all",
     schema: {
-      description: "Get all chains information",
+      summary: "Get all chain details",
+      description: "Get details about all supported chains.",
       tags: ["Chain"],
       operationId: "getAllChainData",
       response: {

server/api/contract/events/getAllEvents.ts

@@ -66,8 +66,8 @@ export async function getAllEvents(fastify: FastifyInstance) {
     method: "GET",
     url: "/contract/:chain/:contract_address/events/get-all",
     schema: {
-      description:
-        "Get a list of all the events emitted from this contract during the specified time period",
+      summary: "Get all events",
+      description: "Get a list of all blockchain events for this contract.",
       tags: ["Contract-Events"],
       operationId: "getAllEvents",
       params: requestSchema,

server/api/contract/events/getEvents.ts

@@ -70,8 +70,9 @@ export async function getEvents(fastify: FastifyInstance) {
     method: "POST",
     url: "/contract/:chain/:contract_address/events/get",
     schema: {
+      summary: "Get events",
       description:
-        "Get a list of the events of a specific type emitted from this contract during the specified time period",
+        "Get a list of specific blockchain events emitted from this contract.",
       tags: ["Contract-Events"],
       operationId: "getEvents",
       params: requestSchema,

server/api/contract/extensions/account/read/getAllAdmins.ts

@@ -22,7 +22,8 @@ export const getAllAdmins = async (fastify: FastifyInstance) => {
     method: "GET",
     url: "/contract/:chain/:contract_address/account/admins/get-all",
     schema: {
-      description: "Get all admins on an account",
+      summary: "Get all admins",
+      description: "Get all admins for a smart account.",
       tags: ["Account"],
       operationId: "account:get-all-admins",
       params: contractParamSchema,

server/api/contract/extensions/account/read/getAllSessions.ts

@@ -21,7 +21,8 @@ export const getAllSessions = async (fastify: FastifyInstance) => {
     method: "GET",
     url: "/contract/:chain/:contract_address/account/sessions/get-all",
     schema: {
-      description: "Get all sessions on an account",
+      summary: "Get all session keys",
+      description: "Get all session keys for a smart account.",
       tags: ["Account"],
       operationId: "account:get-all-sessions",
       params: contractParamSchema,

server/api/contract/extensions/account/write/grantAdmin.ts

@@ -26,7 +26,8 @@ export const grantAdmin = async (fastify: FastifyInstance) => {
     method: "POST",
     url: "/contract/:chain/:contract_address/account/admins/grant",
     schema: {
-      description: "Grant a wallet admin permissions",
+      summary: "Grant admin",
+      description: "Grant a smart account's admin permission.",
       tags: ["Account"],
       operationId: "account:grant-admin",
       headers: walletAuthSchema,

server/api/contract/extensions/account/write/grantSession.ts

@@ -23,7 +23,8 @@ export const grantSession = async (fastify: FastifyInstance) => {
     method: "POST",
     url: "/contract/:chain/:contract_address/account/sessions/create",
     schema: {
-      description: "Create a new session",
+      summary: "Create session key",
+      description: "Create a session key for a smart account.",
       tags: ["Account"],
       operationId: "account:grant-session",
       params: contractParamSchema,

server/api/contract/extensions/account/write/revokeAdmin.ts

@@ -26,7 +26,8 @@ export const revokeAdmin = async (fastify: FastifyInstance) => {
     method: "POST",
     url: "/contract/:chain/:contract_address/account/admins/revoke",
     schema: {
-      description: "Revoke a wallet's admin permissions",
+      summary: "Revoke admin",
+      description: "Revoke a smart account's admin permission.",
       tags: ["Account"],
       operationId: "account:revoke-admin",
       headers: walletAuthSchema,

server/api/contract/extensions/account/write/revokeSession.ts

@@ -26,7 +26,8 @@ export const revokeSession = async (fastify: FastifyInstance) => {
     method: "POST",
     url: "/contract/:chain/:contract_address/account/sessions/revoke",
     schema: {
-      description: "Revoke a session",
+      summary: "Revoke session key",
+      description: "Revoke a session key for a smart account.",
       tags: ["Account"],
       operationId: "account:revoke-session",
       params: contractParamSchema,

server/api/contract/extensions/account/write/updateSession.ts

@@ -28,7 +28,8 @@ export const updateSession = async (fastify: FastifyInstance) => {
     method: "POST",
     url: "/contract/:chain/:contract_address/account/sessions/update",
     schema: {
-      description: "Update a session",
+      summary: "Update session key",
+      description: "Update a session key for a smart account.",
       tags: ["Account"],
       operationId: "account:update-session",
       params: contractParamSchema,

server/api/contract/extensions/accountFactory/read/getAllAccounts.ts

@@ -22,7 +22,8 @@ export const getAllAccounts = async (fastify: FastifyInstance) => {
     method: "GET",
     url: "/contract/:chain/:contract_address/account-factory/get-all-accounts",
     schema: {
-      description: "Get all the accounts on an account factory",
+      summary: "Get all smart accounts",
+      description: "Get all the smart accounts for this account factory.",
       tags: ["Account Factory"],
       operationId: "account-factory:get-all-accounts",
       params: contractParamSchema,

server/api/contract/extensions/accountFactory/read/getAssociatedAccounts.ts

@@ -30,8 +30,9 @@ export const getAssociatedAccounts = async (fastify: FastifyInstance) => {
     method: "GET",
     url: "/contract/:chain/:contract_address/account-factory/get-associated-accounts",
     schema: {
+      summary: "Get associated smart accounts",
       description:
-        "Get all the accounts on an account factory with a specified wallet as a signer",
+        "Get all the smart accounts for this account factory associated with the specific admin wallet.",
       tags: ["Account Factory"],
       operationId: "account-factory:get-associated-accounts",
       params: contractParamSchema,

server/api/contract/extensions/accountFactory/read/isAccountDeployed.ts

@@ -35,8 +35,9 @@ export const isAccountDeployed = async (fastify: FastifyInstance) => {
     method: "GET",
     url: "/contract/:chain/:contract_address/account-factory/is-account-deployed",
     schema: {
+      summary: "Check if deployed",
       description:
-        "Check if the account for a given admin address has been deployed",
+        "Check if a smart account has been deployed to the blockchain.",
       tags: ["Account Factory"],
       operationId: "account-factory:is-account-deployed",
       params: contractParamSchema,

server/api/contract/extensions/accountFactory/read/predictAccountAddress.ts

@@ -34,7 +34,8 @@ export const predictAccountAddress = async (fastify: FastifyInstance) => {
     method: "GET",
     url: "/contract/:chain/:contract_address/account-factory/predict-account-address",
     schema: {
-      description: "Get the counter-factual address of a new account",
+      summary: "Predict smart account address",
+      description: "Get the counterfactual address of a smart account.",
       tags: ["Account Factory"],
       operationId: "account-factory:predict-account-address",
       params: contractParamSchema,

server/api/contract/extensions/accountFactory/write/createAccount.ts

@@ -31,7 +31,8 @@ export const createAccount = async (fastify: FastifyInstance) => {
     method: "POST",
     url: "/contract/:chain/:contract_address/account-factory/create-account",
     schema: {
-      description: "Create a new account on the account factory",
+      summary: "Create smart account",
+      description: "Create a smart account for this account factory.",
       tags: ["Account Factory"],
       operationId: "account-factory:create-account",
       params: contractParamSchema,

server/api/contract/extensions/erc1155/read/balanceOf.ts

@@ -43,7 +43,9 @@ export async function erc1155BalanceOf(fastify: FastifyInstance) {
     method: "GET",
     url: "/contract/:chain/:contract_address/erc1155/balance-of",
     schema: {
-      description: "Check the balance Of the wallet address",
+      summary: "Get balance",
+      description:
+        "Get the balance of a specific wallet address for this ERC-1155 contract.",
       tags: ["ERC1155"],
       operationId: "erc1155_balanceOf",
       params: requestSchema,

server/api/contract/extensions/erc1155/read/get.ts

@@ -53,7 +53,8 @@ export async function erc1155Get(fastify: FastifyInstance) {
     method: "GET",
     url: "/contract/:chain/:contract_address/erc1155/get",
     schema: {
-      description: "Get the metadata of a single NFT.",
+      summary: "Get details",
+      description: "Get the details for a token in an ERC-1155 contract.",
       tags: ["ERC1155"],
       operationId: "erc1155_get",
       params: requestSchema,

server/api/contract/extensions/erc1155/read/getAll.ts

@@ -62,7 +62,8 @@ export async function erc1155GetAll(fastify: FastifyInstance) {
     method: "GET",
     url: "/contract/:chain/:contract_address/erc1155/get-all",
     schema: {
-      description: "Get all NFTs from a given contract.",
+      summary: "Get all details",
+      description: "Get details for all tokens in an ERC-1155 contract.",
       tags: ["ERC1155"],
       operationId: "erc1155_getAll",
       params: requestSchema,

server/api/contract/extensions/erc1155/read/getOwned.ts

@@ -60,8 +60,9 @@ export async function erc1155GetOwned(fastify: FastifyInstance) {
     method: "GET",
     url: "/contract/:chain/:contract_address/erc1155/get-owned",
     schema: {
+      summary: "Get owned tokens",
       description:
-        "Get all NFTs owned by a specific wallet from a given contract.",
+        "Get all tokens in an ERC-1155 contract owned by a specific wallet.",
       tags: ["ERC1155"],
       operationId: "erc1155_getOwned",
       params: requestSchema,

server/api/contract/extensions/erc1155/read/isApproved.ts

@@ -43,8 +43,9 @@ export async function erc1155IsApproved(fastify: FastifyInstance) {
     method: "GET",
     url: "/contract/:chain/:contract_address/erc1155/is-approved",
     schema: {
+      summary: "Check if approved transfers",
       description:
-        "Get whether this wallet has approved transfers from the given operator.",
+        "Check if the specific wallet has approved transfers from a specific operator wallet.",
       tags: ["ERC1155"],
       operationId: "erc1155_isApproved",
       params: requestSchema,

server/api/contract/extensions/erc1155/read/signatureGenerate.ts

@@ -40,9 +40,9 @@ export async function erc1155SignatureGenerate(fastify: FastifyInstance) {
     method: "POST",
     url: "/contract/:chain/:contract_address/erc1155/signature/generate",
     schema: {
-      description: `Generate a signature that a wallet address can use to mint the specified number of NFTs.
-        This is typically an admin operation, where the owner of the contract generates a signature that 
-        allows another wallet to mint tokens.`,
+      summary: "Generate signature",
+      description:
+        "Generate a signature granting access for another wallet to mint tokens from this ERC-721 contract. This method is typically called by the token contract owner.",
       tags: ["ERC1155"],
       operationId: "erc1155_signature_generate",
       params: requestSchema,

server/api/contract/extensions/erc1155/read/totalCount.ts

@@ -29,7 +29,9 @@ export async function erc1155TotalCount(fastify: FastifyInstance) {
     method: "GET",
     url: "/contract/:chain/:contract_address/erc1155/total-count",
     schema: {
-      description: "Get the total number of NFTs minted.",
+      summary: "Get total supply",
+      description:
+        "Get the total supply in circulation for this ERC-1155 contract.",
       tags: ["ERC1155"],
       operationId: "erc1155_totalCount",
       params: requestSchema,

server/api/contract/extensions/erc1155/read/totalSupply.ts

@@ -38,7 +38,9 @@ export async function erc1155TotalSupply(fastify: FastifyInstance) {
     method: "GET",
     url: "/contract/:chain/:contract_address/erc1155/total-supply",
     schema: {
-      description: "Get the total number of NFTs minted.",
+      summary: "Get total supply",
+      description:
+        "Get the total supply in circulation for this ERC-1155 contract.",
       tags: ["ERC1155"],
       operationId: "erc1155_totalSupply",
       params: requestSchema,

server/api/contract/extensions/erc1155/write/airdrop.ts

@@ -57,7 +57,8 @@ export async function erc1155airdrop(fastify: FastifyInstance) {
     method: "POST",
     url: "/contract/:chain/:contract_address/erc1155/airdrop",
     schema: {
-      description: "Airdrop a ERC1155 NFT to multiple wallets.",
+      summary: "Airdrop tokens",
+      description: "Airdrop ERC-1155 tokens to specific wallets.",
       tags: ["ERC1155"],
       operationId: "erc1155_airdrop",
       params: requestSchema,

server/api/contract/extensions/erc1155/write/burn.ts

@@ -40,7 +40,8 @@ export async function erc1155burn(fastify: FastifyInstance) {
     method: "POST",
     url: "/contract/:chain/:contract_address/erc1155/burn",
     schema: {
-      description: "Burn an NFT.",
+      summary: "Burn token",
+      description: "Burn ERC-1155 tokens in the caller wallet.",
       tags: ["ERC1155"],
       operationId: "erc1155_burn",
       params: requestSchema,

server/api/contract/extensions/erc1155/write/burnBatch.ts

@@ -46,7 +46,8 @@ export async function erc1155burnBatch(fastify: FastifyInstance) {
     method: "POST",
     url: "/contract/:chain/:contract_address/erc1155/burn-batch",
     schema: {
-      description: "Burn multiple NFTs.",
+      summary: "Burn tokens (batch)",
+      description: "Burn a batch of ERC-1155 tokens in the caller wallet.",
       tags: ["ERC1155"],
       operationId: "erc1155_burnBatch",
       params: requestSchema,

server/api/contract/extensions/erc1155/write/claimTo.ts

@@ -44,7 +44,8 @@ export async function erc1155claimTo(fastify: FastifyInstance) {
     method: "POST",
     url: "/contract/:chain/:contract_address/erc1155/claim-to",
     schema: {
-      description: "Claim an NFT to a specific wallet.",
+      summary: "Claim tokens to wallet",
+      description: "Claim ERC-1155 tokens to a specific wallet.",
       tags: ["ERC1155"],
       operationId: "erc1155_claimTo",
       params: requestSchema,