Skip to main content

How it works

More detailed information about the inner workings of Improv Protocol can be found in the Smart contract overview

Starting a story​

Every story on Improv Protocol starts as an idea. After refining the idea, a writer submits the story summary as a proposal to the improv-hub contract.

Proposals contain:

  • a title.
  • a genre.
  • a brief synopsis of the proposed story.
  • a cast of characters and a list of NFT collections each character can be selected from.
  • a minimum funding target (minimum bid price).
  • a writing deadline.
  • a bidding deadline.
  • a short background on the author.
  • a hero image.

Character details​

Details for each character are submitted in the initial proposal message. Each character in the proposal is associated with a chain-id and a list of addresses. This list specifies which NFT collections the writer deems eligible for casting. Upon submission, a story's proposal message is sent to Wormhole to allow for cross-chain bidding on the Terra or Ethereum blockchains.

For the casting call auction, each character must have:

  • a name.
  • a description.
  • a list of allowable NFT collections the character can be cast from.
  • a reserve price to start the bidding.
  • a bidding increment that specifies the price difference between competing bids.

Specifying which NFT collections are eligible for casting allows the author to retain some amount of creative control over their characters.

Casting the story​

Once a proposal has been successfully submitted, the casting auction starts. You can think of this auction as an open casting call for NFT characters. Anyone with an NFT in a collection specified in a story's proposal can submit a bid to have their NFT cast as one of the characters in the story. When the auction is finished, the winning bidders will be cast into their character positions, and the writer can start writing their story.

Auction details​

The improv-auction contract implements an auction with the following characteristics:

  • Bids are accepted from the start of the auction until the auction's specified end time.
  • Each bid includes an NFT contract and its token ID.
  • All bids are denominated in USDC.
  • The submitter of each bid must the owner of their specified NFT.
  • All bids must be greater than the reserve price specified in the initial proposal.
  • Each successive bid must be greater than the previous by at least the minimum increment.
  • Every time there is a new highest bidder, the funds from the previous highest bid are returned.

Auction contract info​

Improv Protocol was designed to work on multiple chains. In order to relay information between chains, the Improv protocol uses Wormhole and relayers to exchange VAA messages between the Terra-side improv-hub contract and the various external improv-auction contracts. VAAs contain wrapped messages combined with verified signatures that prove the messages' authenticity across different chains.

Because the improv-auction and improv-hub contracts are not directly linked, relayers are used to deliver VAAs, allowing the two contracts to interact.

The improv-hub contract is in charge of the proposal state and parameters, final auction state, and overall execution of the story process. The improv-auction contract handles the details of each specific cast auction.

The reporting process​

The auction ends at the bidding deadline specified in the proposal.

After the auction ends, relayers on each chain have 30 minutes to submit an auction report to the improv-hub contract.

The auction report details the state of the improv-auction contract using the proposal-id. The improv-auction contract on each chain sends Wormhole messages containing the outcome of the auction. A relayer picks up the message from Wormhole once finalized, and then submits the VAAs to improv-hub, which records the auction state.

Auction finalization​

If the bids for the characters meet the minimum funding target outlined by the proposal, the improv-hub contract finalizes the proposal and the writer can begin writing their story. The successful proposal information is relayed via Wormhole to the improv-auction contracts on their respective chains.

Upon receiving a message of the successful auction, the winning bid amounts of the auction are sent to an escrow account. Arbitration NFTs are minted for each character and sent to the winning bidders. Winners will use these NFTs during the veto period to signify whether they accept or veto a final story.

If an auction is unsuccessful and does not meet the minimum funding requirement, all bids are refunded and the story proposal fails.

Drafting a story​

authors submit drafts via our Improv-protocol's Webapp which are uploaded to IFPS

After a successful auction is completed, the author can begin writing their story. Any time between the end of the auction and the writing deadline, authors can submit a draft of their stories to the Improv web app which uploads them to IPFS. Authors can get feedback on their stories by interacting with their winning cast members on Discord. Authors should try to get as much feedback from their cast members as they can before submitting a final draft of their story.

Once an author has gotten sufficient feedback and completes a final draft of their story, they can submit their story as a final version.

The veto period​

When a finalized story is received, a one-week veto period begins. During the veto period, cast members will decide whether they accept the final version of the story. If they are severely displeased with the story, they can submit a veto using their arbitration NFT.

If enough cast members submit a veto, the story will go back to the writing phase and will have to be re-submitted with changes. Cast members should be open and vocal on their Discord forum about their vetos to give the author ample feedback to remedy their story.

When stories are re-submitted, they enter another one-week veto period. This process continues until a story passes the veto period or until the writing deadline runs out. If the writing deadline runs out before another veto period can begin, the story is considered failed, and all funds are sent back to the cast members. To give authors ample time to remedy their stories, an extension period is added to the writing deadline as a buffer.

Passing a story​

Once a final draft is submitted and successfully passes the veto period without triggering a re-submission, the story is considered Passed 🎉. At this point, all the proceeds from the auction are released and sent to the author. Terra-side auctions are sent directly to the author. Ethereum-side auction proceeds are sent to the author via Wormhole.