added formula docs and OpenAPI v3.1 JSON

src/formulas/formulas/account/bank.ts

@@ -1,6 +1,16 @@
 import { AccountFormula } from '@/types'
 
 export const balance: AccountFormula<string, { denom: string }> = {
+  docs: {
+    description: 'retrieves the balance of a specific token for this account',
+    args: [
+      {
+        name: 'denom',
+        description: 'denomination of the token to retrieve the balance for',
+        required: true,
+      },
+    ],
+  },
   compute: async ({ address, getBalance, args: { denom } }) => {
     if (!denom) {
       throw new Error('missing `denom`')
@@ -17,6 +27,9 @@ export const balance: AccountFormula<string, { denom: string }> = {
 }
 
 export const balances: AccountFormula<Record<string, string>> = {
+  docs: {
+    description: 'retrieves all token balances for this account',
+  },
   compute: async ({ address, getBalances }) =>
     (await getBalances(address)) || {},
 }

src/formulas/formulas/account/contract.ts

@@ -12,6 +12,17 @@ export const ownedBy: AccountFormula<
     key?: string
   }
 > = {
+  docs: {
+    description:
+      'retrieves contracts (that use cw-ownable to manage ownership) where the account is the owner',
+    args: [
+      {
+        name: 'key',
+        description: 'optional code ID key to filter by',
+        required: false,
+      },
+    ],
+  },
   compute: async ({
     address,
     args: { key },

src/formulas/formulas/account/daos.ts

@@ -16,6 +16,10 @@ export const memberOf: AccountFormula<
     proposalCount: number
   }[]
 > = {
+  docs: {
+    description: 'retrieves DAOs where the account is a member',
+    args: [],
+  },
   compute: async (env) => {
     const {
       address: walletAddress,
@@ -210,6 +214,9 @@ export const memberOf: AccountFormula<
 }
 
 export const adminOf: AccountFormula<string[]> = {
+  docs: {
+    description: 'retrieves DAOs where the account is the admin',
+  },
   compute: async ({
     address: walletAddress,
     getTransformationMatches,

src/formulas/formulas/account/nft.ts

@@ -12,16 +12,18 @@ type CollectionWithTokens = {
 }
 
 export const collections: AccountFormula<CollectionWithTokens[]> = {
+  docs: {
+    description:
+      'retrieves NFT collections with their NFTs owned by the account',
+    args: [],
+  },
   compute: async (env) => {
-    const { address: walletAddress, getTransformationMatches } = env
+    const { address, getTransformationMatches } = env
 
     // Potential NFT contracts where the wallet address has tokens.
     const matchingContracts =
       (
-        await getTransformationMatches(
-          undefined,
-          `tokenOwner:${walletAddress}:*`
-        )
+        await getTransformationMatches(undefined, `tokenOwner:${address}:*`)
       )?.map(({ contractAddress }) => contractAddress) ?? []
 
     const uniqueAddresses = Array.from(new Set(matchingContracts))
@@ -49,7 +51,7 @@ export const collections: AccountFormula<CollectionWithTokens[]> = {
             ...env,
             contractAddress: collectionAddress,
             args: {
-              owner: walletAddress,
+              owner: address,
             },
           }),
         })
@@ -61,8 +63,13 @@ export const collections: AccountFormula<CollectionWithTokens[]> = {
 }
 
 export const stakedWithDaos: AccountFormula<CollectionWithTokens[]> = {
+  docs: {
+    description:
+      'retrieves NFT collections with their NFTs staked by the account with DAOs',
+    args: [],
+  },
   compute: async (env) => {
-    const { address: walletAddress, getTransformationMatches, getCodeIdsForKeys } = env
+    const { address, getTransformationMatches, getCodeIdsForKeys } = env
 
     // NFT voting contracts where the wallet address has staked tokens.
     const daoVotingCw721StakedCodeIds = getCodeIdsForKeys(
@@ -72,15 +79,15 @@ export const stakedWithDaos: AccountFormula<CollectionWithTokens[]> = {
       (
         await getTransformationMatches(
           undefined,
-          `stakedNft:${walletAddress}:*`,
+          `stakedNft:${address}:*`,
           undefined,
           daoVotingCw721StakedCodeIds.length > 0
             ? daoVotingCw721StakedCodeIds
             : undefined
         )
       )?.map(({ contractAddress, name }) => ({
         votingContract: contractAddress,
-        tokenId: name.replace(`stakedNft:${walletAddress}:`, ''),
+        tokenId: name.replace(`stakedNft:${address}:`, ''),
       })) ?? []
 
     const uniqueVotingContracts = Array.from(

src/formulas/formulas/account/polytone.ts

@@ -2,6 +2,10 @@ import { AccountFormula } from '@/types'
 
 // Map polytone note contract to the proxy contract for this account.
 export const proxies: AccountFormula<Record<string, string>> = {
+  docs: {
+    description:
+      'retrieves mapping of polytone note contract to the remote address controlled by this account on the chain the note is connected to',
+  },
   compute: async ({ address: walletAddress, getTransformationMatches }) => {
     const notesWithRemoteAddress =
       (await getTransformationMatches(

src/formulas/formulas/account/proposals.ts

@@ -8,6 +8,9 @@ export const created: AccountFormula<
       proposalId: number
     }[]
 > = {
+  docs: {
+    description: 'retrieves proposals created by the account',
+  },
   compute: async ({ address: walletAddress, getTransformationMatches }) => {
     // Proposals for v1/v2 dao-proposal-single and v2 dao-proposal-multiple.
     const proposedTransformations =
@@ -30,6 +33,9 @@ export const votesCast: AccountFormula<
       proposalId: number
     } & Omit<VoteCast, 'voter'>)[]
 > = {
+  docs: {
+    description: 'retrieves votes cast by the account',
+  },
   compute: async ({ address: walletAddress, getTransformationMatches }) => {
     // Votes for dao-proposal-single and dao-proposal-multiple.
     const voteCastTransformations =
@@ -53,6 +59,10 @@ export const stats: AccountFormula<{
   created: number
   votesCast: number
 }> = {
+  docs: {
+    description:
+      'retrieves statistics about proposals created and votes cast by the account',
+  },
   compute: async (env) => {
     const [createdResponse, votesCastResponse] = await Promise.all([
       created.compute(env),

src/formulas/formulas/account/tokens.ts

@@ -9,6 +9,9 @@ type ContractWithBalance = {
 }
 
 export const list: AccountFormula<ContractWithBalance[]> = {
+  docs: {
+    description: 'retrieves a list of CW20 token balances for the account',
+  },
   compute: async (env) => {
     const { address, getTransformationMatches } = env
 

src/formulas/formulas/account/valence.ts

@@ -1,6 +1,9 @@
 import { AccountFormula } from '@/types'
 
 export const accounts: AccountFormula<string[]> = {
+  docs: {
+    description: 'retrieves valence accounts owned by this account',
+  },
   compute: async (env) => {
     const { address, getTransformationMatches, getCodeIdsForKeys } = env
 

src/formulas/formulas/account/vesting.ts

@@ -3,6 +3,10 @@ import { Op } from 'sequelize'
 import { AccountFormula } from '@/types'
 
 export const ownerOf: AccountFormula<string[]> = {
+  docs: {
+    description:
+      'retrieves the addresses of cw-vesting contracts owned by the account or by cw1-whitelist contracts where the account is an admin',
+  },
   compute: async (env) => {
     const { address, getTransformationMatches, getCodeIdsForKeys } = env
 

src/formulas/formulas/account/veto.ts

@@ -33,6 +33,10 @@ type VetoableProposalDaos = {
 }
 
 export const vetoableProposals: AccountFormula<VetoableProposalDaos[]> = {
+  docs: {
+    description:
+      'retrieves all proposals this account has the authority to veto',
+  },
   compute: async (env) => {
     const { address, getTransformationMatches, getCodeIdsForKeys } = env
 

src/formulas/formulas/contract/common.ts

@@ -4,6 +4,9 @@ import { ContractInfo } from '../types'
 import { makeSimpleContractFormula } from '../utils'
 
 export const info: ContractFormula<ContractInfo> = {
+  docs: {
+    description: 'retrieves the contract info (name and version)',
+  },
   compute: async ({ contractAddress, getTransformationMatch }) => {
     const info = (
       await getTransformationMatch<ContractInfo>(contractAddress, 'info')
@@ -17,13 +20,20 @@ export const info: ContractFormula<ContractInfo> = {
   },
 }
 
-// cw-ownership
+// cw-ownable
 export const ownership = makeSimpleContractFormula({
+  docs: {
+    description:
+      'retrieves the contract ownership defined by the cw-ownable crate',
+  },
   transformation: 'ownership',
   fallbackKeys: ['ownership'],
 })
 
 export const instantiatedAt: ContractFormula<string> = {
+  docs: {
+    description: 'retrieves the contract instantiation timestamp',
+  },
   compute: async ({ contractAddress, getContract }) => {
     const timestamp = (
       await getContract(contractAddress)
@@ -42,6 +52,37 @@ export const instantiatedAt: ContractFormula<string> = {
 // keys="map_namespace":"key_in_map" or keys="map_namespace":1 depending on the
 // type of the key.
 export const item: ContractFormula<any, { key: string; keys: string }> = {
+  docs: {
+    description:
+      'retrieves a value stored in the contract state at the given key',
+    args: [
+      {
+        name: 'key',
+        description: '`Item` key to retrieve',
+        required: false,
+      },
+      {
+        name: 'keys',
+        description:
+          '`Map` key to retrieve (by joining JSON-stringified keys with a colon)',
+        required: false,
+        examples: {
+          simple: {
+            summary: 'access a string-keyed map',
+            value: '"map_namespace":"key_in_map"',
+          },
+          numeric: {
+            summary: 'access a numeric-keyed map',
+            value: '"map_namespace":1',
+          },
+          tuple: {
+            summary: 'access a map with a tuple key',
+            value: '"map_namespace":"address":1:"another_key"',
+          },
+        },
+      },
+    ],
+  },
   compute: async ({ contractAddress, get, args: { key, keys } }) => {
     if (key) {
       return await get(contractAddress, key)
@@ -71,6 +112,39 @@ export const map: ContractFormula<
   any,
   { key: string; keys: string; numeric: string }
 > = {
+  docs: {
+    description:
+      'retrieves a map stored in the contract state at the given key. if the map has a tuple key, you can access the map at any degree by omitting a suffix of the tuple key',
+    args: [
+      {
+        name: 'key',
+        description: '`Map` namespace to retrieve',
+        required: false,
+      },
+      {
+        name: 'keys',
+        description:
+          '`Map` namespace to retrieve (by joining JSON-stringified keys with a colon)',
+        required: false,
+        examples: {
+          simple: {
+            summary: 'access a normal map',
+            value: '"map_namespace"',
+          },
+          tuple: {
+            summary: 'access a map with a tuple namespace',
+            value: '"map_namespace":"address":1',
+          },
+        },
+      },
+      {
+        name: 'numeric',
+        description:
+          "whether or not the map's keys are numbers (otherwise treated as strings)",
+        required: false,
+      },
+    ],
+  },
   compute: async ({
     contractAddress,
     getMap,