Improvement: Centralize Idea, Prop, Funding State

[dowlandaiello]

Improvement: Centralize Idea Logic

This improvement aims to consolidate all the Idea and Proposal loading logic in lib/utils/ipfs.ts by creating a new context available via a VisDataProvider component, and relevant hooks for loading specific information, as defined by the following API:

Proposed API

Each method in the following API is accompanied by an asynchronous sibling, from which its functionalty is derived. These methods are intended for internal use, e.g., for implementing more hooks. But you may use them if you wish.

Statefulness

One of the goals of this new API is to improve performance by caching loaded items on a most-frequently-used basis. This means that methods for loading content from this API can initiate loading uncached data, or simply instantly return cached data. Furthermore, all records on Vision are nullable, and subject to network latency, and client errors. As such, every method in the Vision API will return data wrapped in a VisDataEntry defined as:

type VisDataEntry<TOk, TErr> = Loading | Ok<TOk> | Failed<TErr> | Null;

Where TOk is the desired data type to load, TErr is the type of any error that might occur, and Loading, Failed, and Ok are defined as:

type Loading = {
	state: "loading";
};

type Ok<TOk> = {
	state: "ok";
	val: TOk,
};

type Failed<TErr> = {
	state: "failed";
	val: TErr,
};

type Null = {
	state: "null";
};

Error Types

The exact nature of error types that might arise while using this API shall be discovered in development. E is considered as a stand in for more specific error types that will be discovered in the immediate future.

useIdea<T extends BasicIdeaInformation | ExtendedIdeaInformation>(string addr): VisDataEntry<T, E>

Returns a cached copy of an Idea, or initiates loading the Idea, where the data returned describes an Idea to two varying degrees of detail: BasicIdeaInformation and ExtendedIdeaInformation.

The behavior of these types is well defined in the IdeaBubble component. However, it will be consolidated to wherever this new API is implemented. The same is true for ExtendedIdeaInformation, which is defined in the IdeaDetailCard component.

useImmediateChildren<T extends Set<string> | { [childAddr: string]: FundingRate }>(parentAddr: string): VisDataEntry<T, E>

Returns a cached list of addresses of children being funded by the Idea, or a mapping of child addresses to funding rates.

useDescendants<T extends Set<string> | { [childAddr: string]: FundingRate }>(parentAddr: string, interestedUntil?: (parentAddr: string) => bool): VisDataEntry<T, E>

Returns a cached list of addresses of children being funded by the Idea, or a mapping of child addresses to funding rates, where each child is a descendant of the parent, at a terminant depth defined by interestedUntil, a closure determining if the descendants of a child should be calculated (e.g., based on tags, or a user's interests). By default, the tree is walked to its terminal leaves.

useProposals<T extends Set<GossipProposalInformation> | Set<ExtendedProposalInformation>>(parentAddr: string, criteria: Set<ProposalStatus>): VisDataEntry<T, E>

Returns a cached set of proposals for a DAO at parentAddr, where criteria describes the necessary degree of maturity for proposals to return, and where ProposalStatus is defined as:

type ProposalStatus = Accepted | Rejected | Pending;

And the possible states for ProposalStatus are defined as their stringly-typed components:

type Accepted = {
	status: "accepted";
}

type Rejected = {
	status: "rejected";
}

type Pending = {
	status: "pending";
}

useProposalVotes<T extends Set<string> | { [voterAddr: string]: ProposalVote }>(proposalAddr: string): VisDataEntry<T, E>

Returns a cached set of the addresses of all voters for a proposal indicated by the address proposalAddr, or a mapping from each voter to the details of their vote, where a vote is described by ProposalVote, or initiates a load of these data.

Liveliness

Another goal of this API is to improve on the availability of up-to-date informatino on Vision by replacing existing synchronous code with event-driven code that can receive up-to-date information from Ethereum as it arrives.

The major roadblock to implementing this functionality so far has been a lack of centralization in managing these listeners, which have to be destroyed and recreated when an Idea goes out of scope. However, this can be easily implemented in the scope of this API, because it implements a most-frequently-used cache, so Ideas have a defined lifetime.