[xGov Proposal #3572597746] Open-Source TraitSwap & LootBox Template for Algorand NFT Projects

Governance Discussions xGov Proposals
1

Summary

This proposal requests retroactive funding for the open-source release of a
production-ready TraitSwap & LootBox template for Algorand NFT projects —
built, battle-tested, and live at monstrs.famverse.xyz.

Repository: GitHub - filippofalleroni/Trait-swap-and-Loot-Box · GitHub (MIT License)

What was built

Two complete utilities that any Algorand NFT project can deploy:

1. Trait Swapping (ARC-19)
Holders browse traits, preview them on their NFT, and apply with a single transaction.
The system composites layered images, uploads to IPFS via Pinata, and updates on-chain
metadata — all server-side. Projects configure their own catalog, pricing, and layer
structure.

2. Loot Box (Commit-Reveal + VRF)
A TEALScript smart contract using PCG32 randomness (based on Giorgio Ciotti’s
lib-pcg-avm) seeded by Algorand’s VRF
beacon. Users commit, wait 8+ rounds, then reveal — the contract derives a verifiable
random value for weighted prize selection. Fungible token and NFT prizes are
distributed automatically from a server-side master wallet.

3. White-label & ready to deploy
All configuration is centralized (collection addresses, trait definitions, prize tiers,
branding). Any project can deploy without touching core logic. Supports Pera, Defly,
and Lute. Built on Next.js 14. Includes preview modes for safe testing.

4. Admin panel
Wallet-signature authenticated (no passwords). Covers prize configuration, treasury
balances, ASA opt-in, and prize pool inventory.

Why this matters

Trait swapping and loot boxes are proven engagement and revenue tools in NFT
ecosystems, but building them on Algorand from scratch requires deep expertise in
ARC-19 updates, IPFS pinning, commit-reveal patterns, VRF randomness, and
server-side wallet management. This template packages all of that into a documented,
deployable starting point — significantly lowering the barrier for every project on
Algorand.

A core part of the MONSTRS model is reinvesting 50% of all loot box fees back
into the Algorand NFT community by purchasing NFTs from other projects.
Open-sourcing this template means any project can adopt the same flywheel —
more loot boxes running across the ecosystem means more revenue flowing back
to NFT artists and builders on Algorand.

Proof of production use

The system has been running live at monstrs.famverse.xyz
for 3 months:

Metric Value
Traits swapped 500+
Loot boxes opened 1,000+
Community NFTs purchased 100+
Time in production 3 months

Multiple NFT project leads have reached out asking how to replicate this system for
their own collections — confirming real demand for this kind of tooling on Algorand.

Technical stack

  • Smart contract: TEALScript, PCG32 RNG via lib-pcg-avm, Algorand VRF beacon
  • Frontend: Next.js 14, @txnlab/use-wallet (Pera, Defly, Lute)
  • Storage: IPFS via Pinata
  • Standard: ARC-19 for on-chain NFT metadata updates
  • Auth: Wallet-signature challenge-response (no passwords)

About the team

MONSTRS is a solo-led project by Filippo (@famversedotxyz
on X). The full system — from trait mechanics to loot box economy — was designed and
directed by Filippo, with developers brought in to execute the build.

Questions & feedback welcome

Happy to answer any questions about the technical implementation, the open-source
structure, or the MONSTRS production experience. All feedback appreciated before
the proposal goes to vote.

2

Proposal link

3

There’s no fail-safe for if the VRF round expires, or is this logic handled on frontend?

You have two global states, pcgInc is always 0, but you have this.pcgInc | 1 logic later, just curious what the intention of this is?

The logic you have for PCG32 deviates greatly from what was open-sourced at first glance: PCG

4

Thanks for highlighting these issues, your feedback is really appreciated. We’ve addressed all three points you raised and made several other improvements as well.

We’re also open to open-sourcing our production codebase if the xGovs feel that would be more useful, but we believe the template as it stands would be much easier for a developer to pick up and make their own.

5

First off, you removed the PCG logic entirely, which is not ideal since you originally were moving towards incorporating formal logic for PCG that has been established (and recently funded by xGovs to recognize that it is of value).

I’m not saying that this is wrong, just pointing out what the logic was replaced with — if you want to stick with this new logic wouldn’t you need to adjust portions of your proposal that mention using PCG?

const seed = blocks[committed + 1].seed;
const randomValue = btoi(extract3(seed, 0, 8))

Also, you’ve now just opened up an exploit — someone can just wait 50~ minutes if they don’t like their reward after simulating your reveal method and call your reclaim method. I’m not entirely sure this is a step forward.

6

Thanks for the detailed feedback, we appreciate the scrutiny. Here’s our reasoning on both points.

Re: Reclaim exploit concern

The reclaim method can’t be used to cherry-pick results, the payment to treasury and the commit are in an atomic transaction group. If someone commits and then reclaims without revealing, they’ve already paid the crate price and receive nothing. They’d need to pay again to recommit, so each “reroll” attempt costs them the full crate price. Additionally, prize selection uses server-side randomness generated at reveal time, not the on-chain VRF seed, so there is nothing deterministic for a user to simulate in advance.

Re: Removing PCG logic

PCG is a deterministic function of its seed, so it doesn’t add any protection against simulation, if someone can read the VRF seed (which is a public block field), they can compute the PCG output just as easily. For a single random value per reveal, direct VRF extraction is equivalent. We kept a reference to lib-pcg-avm in the contract comments for cases where multiple random values are needed from a single seed.

7

Gotcha` — there are no references to payment transactions or any transactions in the group except for Txn.sender in the contract I’m looking at just FYI

Your commit method is public (where the commit round is set in a box) and doesn’t have any assertions preventing someone from calling it whenever they want, for example after simulating the result of reveal.

You state that they need to pay the “crate” price again if they recommit, but the logic in your contract doesn’t match that.

You lost me here, so what is the purpose of the contract then?

Ahhh I see, so regardless of the VRF output they don’t know how it maps to some reward. I got you — but technically their reward is no longer verifiable if there is no on-chain mapping or disclosure of how it maps to their reward, right? Which is the purpose of putting it on chain in the first place?

8

Good points, you were right that the contract was missing those checks when you reviewed it. We’ve since tightened things up based on your feedback. On verifiability, the prize table and weights are served publicly and the selection logic is open source, so the mapping from any VRF output to its prize is independently verifiable. Appreciate the back and forth, it’s genuinely made the template stronger.

You’re right that having the prize mapping happen off-chain, even with public weights and open source code, is a weaker guarantee than having it fully on-chain. So we’ve updated the contract to verify the payment in the atomic group, reject duplicate commits, and handle expiry. The VRF value is now used directly for prize selection, and since the prize table and selection logic are both public, the full path from commit to prize is independently verifiable. Your feedback pushed us to make it properly trustless rather than jus technically defensible.

9

Awesome, last thing I’ll say is it’s better not to abandon your original stance of “Claim your random reward or risk losing it after 50~ minutes when VRF round expires”.

Especially considering that you state the reward mapping off-chain is public.

If you want to be forgiving and keep it that’s fine just disclose above the method with a comment or something that users can await the round to expire if the resulting output wouldn’t be favorable, reclaim their payment, and recommit if that method is available.

Thanks for being receptive =)

Note: I think the only ARC standard that supports fully on-chain modification of metadata for ASA’s is ARC69, unless you have a bunch of reserve addresses ready to use on-chain mapped somehow. I have an old Pyteal example somewhere but it’s on algo-learn.com somewhere for sure if you were curious

10

Good call, we’ll add a comment above the reclaim method documenting that since the prize mapping is public, users could choose not to reveal unfavorable outcomes and let the commit expire. They still lose the crate price either way, but it’s worth being transparent about. And thanks for the ARC-69 pointer, we’ll take a look. Really appreciate you taking the time to dig into this, the template is significantly better for it.

11

Quick update on the TraitSwap & LootBox template ahead of the vote.

The contract now verifies the payment in the atomic group (sender, receiver, amount), rejects duplicate commits, enforces expiry windows, and includes the reclaim() method with the design tradeoff documented transparently — as discussed in this thread.

On verifiability — the user calls reveal() themselves on-chain. The contract reads the VRF seed from the block after their commit, extracts a random uint64, and returns it via ABI. The server reads that return value from the confirmed transaction logs and uses it for weighted prize selection against the public prize table. The full path from commit to prize is deterministic and independently verifiable — anyone can replay the same VRF output against the open-source selection logic and confirm the result.

Beyond the contract, the template has had a full security pass:

  • Payment verification with bounds checking
  • Transaction replay prevention
  • Rate limiting across all routes
  • SSRF protection on metadata fetching
  • Input validation
  • Crash recovery (pending state survives browser close so users don’t lose payments)
  • Distribution retries
  • Safe error handling that doesn’t leak internals

We’ve also migrated all of these improvements over to the live MONSTRS website at monstrs.famverse.xyz where the trait lab and loot box are actively used, so the template reflects real production-tested code.

The aim is for any Algorand NFT project to be able to fork this, configure it for their collection, and deploy a working trait swapper and verifiably random loot box without starting from scratch. The README covers setup, configuration, security, and deployment. If anyone wants to dig into the code or test it out, we’d welcome the feedback.

12

Thank you for the proposal @famverse!

While I haven’t had the time yet to review the repo, in general I like the proposal - its goals, demonstrated traction, and ask amount.

My only wish would be that since now the work has been changed based on the feedback of @Atsoc1993, it would be prudent IMO to have the new version live and battle-tested in production a bit longer before going to the vote.

Another point of feedback, it would make a very strong case if the project leads that you refer to in the proposal as asking for such a system would comment on this thread and/or if they would allow you to name/cite them.

13

Thanks a lot for the thoughtful feedback, @uhudo — really appreciate you taking the time.

Completely agree on letting the new version run live and get battle-tested in production a bit longer before going to the vote. We’d rather have the GLOOT system proven out properly than rush it, so we’re happy to hold off for now. We’ve also already implemented all the changes to the MONSTRS website that we’d discussed, so those are live too.

On the project leads point: there’s been interest from a couple of teams, and I’ll let them comment on this thread directly, which I agree would strengthen the case.

Happy to keep you posted as the production testing progresses.

14

This is a really helpful tool for projects. Trait swapping is popular in the Algorand NFT community. Wish it had existed already, would have saved us a significant amount of time and money which could have been used on other things we intend to build.

15

This would be a great addition to our project - Crazy Embryo Club. Our Crazy Clones are minted as ARC19 but we are only set up to do manual trait swaps.
Hopefully we will be able to utilize this in our project!

16

Quick update — the proposal is now live and has gone to vote.

After some advice that it’d be worth getting it in front of the xGovs while they’re actively voting this period, we decided to go ahead now rather than wait. Production testing has been going well in the meantime, so we felt good about it.

Since the last update we’ve also shipped another round of reliability improvements to the trait swapper, live on monstrs.famverse.xyz and mirrored in the open-source template.

Huge thanks to everyone for the kind words and interest — @Moriarty, @HippieNerdFarmer, really glad to hear it’d be useful for your projects. That’s exactly what we’re hoping for: fork it, configure it for your collection, and go. Happy to help anyone who wants to test it out. :folded_hands:

Also great to see @Staxx backing the TraitLab (his comment’s pending mod approval).

17

As a NFT project lead who has zero experience coding, more of these tools are needed in our communities. I have used all of them as a Monstr holder, having these available for our own projects would be beneficial to all.

18

@famverse Did you submit your repo to Electric Capital? I can’t find it. Note that this is one of T&C requirements.

19

Hi @uhudo, thanks for the reminder! We’ve just submitted the repo to Electric Capital and are waiting for the PR to be approved. I’ll follow up here once it’s merged.