Update to latest funnel setup

PaimaStudios · Aug 30, 2023 · b9a3276 · b9a3276
1 parent 524b424
commit b9a3276
Show file tree

Hide file tree

Showing 4 changed files with 15 additions and 13 deletions.
diff --git a/docs/home/3 - Reacting to Events/2 - Chain Data Extensions/2 - ERC20.md b/docs/home/3 - Reacting to Events/2 - Chain Data Extensions/2 - ERC20.md
@@ -29,7 +29,7 @@ The ERC20 CDE does not schedule any inputs, so the `scheduledPrefix` field can b
 
 ```ts
 export async function getFungibleTokenBalance(
-  readonlyDBConn: Pool,
+  readonlyDBConn: PoolClient,
   cdeName: string,
   walletAddress: string
 ): Promise<bigint | null>;
@@ -74,7 +74,7 @@ where:
 ```ts
 // total amount the specified address has deposited to the deposit address
 export async function totalAmountDeposited(
-  readonlyDBConn: Pool,
+  readonlyDBConn: PoolClient,
   cdeName: string,
   walletAddress: string
 ): Promise<bigint | null>;
@@ -84,7 +84,7 @@ export async function totalAmountDeposited(
 
 ```ts
 export async function findUsersWithDepositsGreaterThan(
-  readonlyDBConn: Pool,
+  readonlyDBConn: PoolClient,
   cdeName: string,
   thresholdAmount: bigint
 ): Promise<string[]>;

diff --git a/docs/home/3 - Reacting to Events/2 - Chain Data Extensions/3 - ERC721.md b/docs/home/3 - Reacting to Events/2 - Chain Data Extensions/3 - ERC721.md
@@ -38,7 +38,7 @@ where:
 
 ```ts
 export async function getNftOwner(
-  readonlyDBConn: Pool,
+  readonlyDBConn: PoolClient,
   cdeName: string,
   nftId: bigint
 ): Promise<string | null>;
@@ -48,7 +48,7 @@ export async function getNftOwner(
 
 ```ts
 export async function isNftOwner(
-  readonlyDBConn: Pool,
+  readonlyDBConn: PoolClient,
   cdeName: string,
   nftId: bigint,
   ownerAddress: string
@@ -59,7 +59,7 @@ export async function isNftOwner(
 
 ```ts
 export async function getOwnedNfts(
-  readonlyDBConn: Pool,
+  readonlyDBConn: PoolClient,
   cdeName: string,
   ownerAddress: string
 ): Promise<bigint[]>;
@@ -69,7 +69,7 @@ export async function getOwnedNfts(
 
 ```ts
 export async function getAllOwnedNfts(
-  readonlyDBConn: Pool,
+  readonlyDBConn: PoolClient,
   ownerAddress: string
 ): Promise<
   {

diff --git a/docs/home/3 - Reacting to Events/2 - Chain Data Extensions/4 - Generic.md b/docs/home/3 - Reacting to Events/2 - Chain Data Extensions/4 - Generic.md
@@ -71,7 +71,7 @@ export interface GenericCdeDataUnit {
 
 ```ts
 export async function getGenericDataBlockheight(
-  readonlyDBConn: Pool,
+  readonlyDBConn: PoolClient,
   cdeName: string,
   blockHeight: number
 ): Promise<GenericCdeDataUnit[]>;
@@ -81,7 +81,7 @@ export async function getGenericDataBlockheight(
 
 ```ts
 export async function getGenericDataBlockheightRange(
-  readonlyDBConn: Pool,
+  readonlyDBConn: PoolClient,
   cdeName: string,
   fromBlock: number,
   toBlock: number

diff --git a/docs/home/3 - Reacting to Events/3 - Funnel Types/1 - Intro.md b/docs/home/3 - Reacting to Events/3 - Funnel Types/1 - Intro.md
@@ -12,15 +12,17 @@ All Paima Funnels implement a simple interface
 
 ```typescript
 interface ChainFunnel {
-  getExtensions: () => ChainDataExtension[];
-  extensionsAreValid: () => boolean;
-  recoverState: () => Promise<void>;
   readData: (blockHeight: number) => Promise<ChainData[]>;
   readPresyncData: (fromBlock: number, toBlock: number) => Promise<PresyncChainData[]>;
+  getDbTx(): PoolClient;
 }
 ```
 
-Multiple funnels are combined together based on the developer's needs using the [decorator pattern](https://en.wikipedia.org/wiki/Decorator_pattern), allowing to mix-and-match funnel types depending on the game's setup to get all the data they need.
+Funnels are meant to be stateless between blocks to avoid subtle bugs in the case of errors during the sync process (so that state properly gets reset), as well as to encapsulate the fact that funnels are executed together in a joint SQL transaction. Funnels that need state should use:
+- For persistent storage, use the Paima SQL database. This can be use to hydrate the funnel type using a custom-defined `recoverState`. If used, you should NOT assume that data for your funnel being persisted in the database implies the game state machine will successfully be updated. Fetching data (funnels) and update the game machine are done in separate SQL transactions (so it's possible fetching data succeeds, but updating the game fails so re-fetching the data is required)
+- A custom cache entry in `FunnelCacheManager` for state that either needs to be persisted (ex: query a batch of data that gets processed across multiple blocks) or that needs to be shared between funnels
+
+Multiple funnels are combined together based on the developer's needs using a combination of the [composite pattern](https://en.wikipedia.org/wiki/Composite_pattern) and the [decorator pattern](https://en.wikipedia.org/wiki/Decorator_pattern), allowing to mix-and-match funnel types depending on the game's setup to get all the data they need.
 
 At its core, Paima will call the `readData` function according to `POLLING_RATE` (which by default is based on `BLOCK_TIME`), and pass in the next expected block height (based off what is stored on disk by the Paima state machine).