feat: generalize reward distribution

[loothero]

Summary

• Remove the velords-specific 80/20 proceeds split in favor of directing all proceeds to buybacks
• Simplifies the distribution logic and makes the contract more flexible for different tokenomics configurations
• All proceeds from token sales now go directly to TWAMM buyback orders, with resulting tokens sent to treasury

Changes

• Remove velords_address from constructor, storage, and interface
• Update distribute_proceeds to use 100% of proceeds for buybacks (previously 80% buybacks, 20% velords)
• Remove set_velords_address and get_velords_address functions
• Update deployment script and .env.example to remove velords configuration
• Update tests to reflect new constructor signature
• Update README.md and AGENTS.md documentation

Test plan

• All 143 tests pass with snforge test
• Build succeeds with scarb build
• Fork tests pass against mainnet

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello @loothero, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request refactors the contract's reward distribution system to be more flexible and straightforward. By eliminating a specific 80/20 proceeds split, all funds generated from token sales are now channeled directly into buyback mechanisms, with the resulting tokens sent to the treasury. This change simplifies the underlying logic and broadens the contract's applicability across various tokenomics models. Additionally, the initial token distribution process has been decoupled from the constructor and moved into a dedicated, owner-controlled function, enhancing deployment flexibility.

Highlights

• Simplified Reward Distribution: The contract's reward distribution mechanism has been generalized, removing the previous 80/20 split that allocated proceeds to 'veLords'. Now, all proceeds from token sales are directed entirely to TWAMM buyback orders.
• Dedicated Token Premint Function: A new premint_tokens function has been introduced, allowing for initial token distribution to specified recipients and amounts post-deployment, rather than during the constructor call. This provides greater flexibility and control over initial token allocation.
• Streamlined Contract Interface and Deployment: The velords_address parameter has been removed from the contract's constructor, storage, and interface. Corresponding set_velords_address and get_velords_address functions have also been eliminated, simplifying the contract's API and reducing its attack surface. The deployment script and documentation have been updated to reflect these changes.
• Enhanced Test Coverage: Existing tests have been updated to align with the new distribution logic and constructor signature. New tests have been added to specifically cover the functionality and access control of the premint_tokens function, ensuring its correct behavior and preventing misuse.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request generalizes the reward distribution by removing the velords-specific 80/20 split and directing all proceeds to buybacks. This simplifies the contract logic and enhances flexibility. The changes are well-implemented across the contract, tests, deployment scripts, and documentation. I've identified a high-severity issue regarding the total token supply calculation, along with a couple of medium-severity suggestions for the deployment script to improve portability and maintainability. Overall, this is a solid simplification of the contract's mechanics.

[Copilot]

Pull request overview

This PR removes the velords-specific 80/20 proceeds split and simplifies the reward distribution model by directing all proceeds to buybacks. The key changes include removing the velords_address parameter from the constructor and storage, replacing constructor-time token distribution with a new premint_tokens function callable after deployment, and updating the distribute_proceeds function to allocate 100% of proceeds to buyback orders instead of splitting them.

Key Changes:

• Removed velords address configuration from constructor, storage, and interface
• Replaced constructor-time recipient distribution with post-deployment premint_tokens function
• Changed proceed distribution from 80% buybacks / 20% velords to 100% buybacks

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/contract.cairo	Removed velords_address from storage and constructor; added premint_tokens function; updated distribute_proceeds to use 100% for buybacks; removed velords getter/setter
src/interfaces.cairo	Added premint_tokens function; removed set_velords_address and get_velords_address functions
tests/test_contract.cairo	Updated all tests to remove velords parameters; added comprehensive premint_tokens test coverage; updated constructor validation tests
tests/helper.cairo	Removed velords_address from setup and calldata builder functions
tests/constants.cairo	Removed MOCK_VELORDS_ADDRESS constant
scripts/deploy.sh	Removed velords configuration; added premint_tokens invocation; commented out initialization steps; updated ownership transfer logic
README.md	Updated documentation to reflect removal of velords revenue share and new 100% buyback model
AGENTS.md	Removed velords references from development guidelines
.env.example	Removed VELORDS_ADDRESS environment variable

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Critical deployment steps (approval, pool initialization, liquidity provisioning, and distribution start) are commented out. If this is intentional for a two-stage deployment process, it should be documented. Otherwise, the deployment script will only deploy the contract and premint tokens without actually initializing the TWAMM functionality.

Suggested change

	# LIQ_OUTPUT=$(starkli invoke --watch --account "$STARKNET_ACCOUNT" --private-key "$STARKNET_PK" --rpc "$STARKNET_RPC" "$CONTRACT_ADDRESS" provide_initial_liquidity "$INITIAL_PAYMENT_TOKEN_LIQUIDITY" "$INITIAL_DUNGEON_TICKET_LIQUIDITY" "$INITIAL_MIN_LIQUIDITY" 2>&1 || true)
	# LIQ_EXIT=$?
	# if [ $LIQ_EXIT -ne 0 ]; then
	# print_error "provide_initial_liquidity failed"
	# echo "$LIQ_OUTPUT"
	# exit 1
	# fi
	# LIQ_TX=$(echo "$LIQ_OUTPUT" | grep -oE 'transaction: 0x[0-9a-fA-F]+' | head -1 | awk '{print $2}')
	# if [ -n "$LIQ_TX" ]; then print_tx "$LIQ_TX"; fi
	# print_info "Starting token distribution"
	# DIST_OUTPUT=$(starkli invoke --watch --account "$STARKNET_ACCOUNT" --private-key "$STARKNET_PK" --rpc "$STARKNET_RPC" "$CONTRACT_ADDRESS" start_token_distribution 2>&1 || true)
	# DIST_EXIT=$?
	# if [ $DIST_EXIT -ne 0 ]; then
	# print_error "start_token_distribution failed"
	# echo "$DIST_OUTPUT"
	# exit 1
	# fi
	# DIST_TX=$(echo "$DIST_OUTPUT" | grep -oE 'transaction: 0x[0-9a-fA-F]+' | head -1 | awk '{print $2}')
	# if [ -n "$DIST_TX" ]; then print_tx "$DIST_TX"; fi
	LIQ_OUTPUT=$(starkli invoke --watch --account "$STARKNET_ACCOUNT" --private-key "$STARKNET_PK" --rpc "$STARKNET_RPC" "$CONTRACT_ADDRESS" provide_initial_liquidity "$INITIAL_PAYMENT_TOKEN_LIQUIDITY" "$INITIAL_DUNGEON_TICKET_LIQUIDITY" "$INITIAL_MIN_LIQUIDITY" 2>&1 || true)
	LIQ_EXIT=$?
	if [ $LIQ_EXIT -ne 0 ]; then
	print_error "provide_initial_liquidity failed"
	echo "$LIQ_OUTPUT"
	exit 1
	fi
	LIQ_TX=$(echo "$LIQ_OUTPUT" | grep -oE 'transaction: 0x[0-9a-fA-F]+' | head -1 | awk '{print $2}')
	if [ -n "$LIQ_TX" ]; then print_tx "$LIQ_TX"; fi
	print_info "Starting token distribution"
	DIST_OUTPUT=$(starkli invoke --watch --account "$STARKNET_ACCOUNT" --private-key "$STARKNET_PK" --rpc "$STARKNET_RPC" "$CONTRACT_ADDRESS" start_token_distribution 2>&1 || true)
	DIST_EXIT=$?
	if [ $DIST_EXIT -ne 0 ]; then
	print_error "start_token_distribution failed"
	echo "$DIST_OUTPUT"
	exit 1
	fi
	DIST_TX=$(echo "$DIST_OUTPUT" | grep -oE 'transaction: 0x[0-9a-fA-F]+' | head -1 | awk '{print $2}')
	if [ -n "$DIST_TX" ]; then print_tx "$DIST_TX"; fi

[Copilot]

This commented line should be removed to keep the code clean. If it was intended for debugging, it should not be committed to the repository.

Suggested change

#PREMINT_OUTPUT=$(starkli invoke --watch --account "$STARKNET_ACCOUNT" --private-key "$STARKNET_PK" --rpc "$STARKNET_RPC" "$CONTRACT_ADDRESS" premint_tokens $RECIPIENTS_ARRAY_ARG $AMOUNTS_ARRAY_ARG 2>&1 || true)

[Copilot]

For consistency with other starkli invoke calls in this script (see lines 511, 524), this invocation should include 2>&1 || true to properly capture error output. The current line 495 may not handle failures correctly.

Suggested change

	PREMINT_OUTPUT=$(starkli invoke --watch --account "$STARKNET_ACCOUNT" --private-key "$STARKNET_PK" --rpc "$STARKNET_RPC" "$CONTRACT_ADDRESS" premint_tokens $RECIPIENTS_ARRAY_ARG $AMOUNTS_ARRAY_ARG)
	PREMINT_OUTPUT=$(starkli invoke --watch --account "$STARKNET_ACCOUNT" --private-key "$STARKNET_PK" --rpc "$STARKNET_RPC" "$CONTRACT_ADDRESS" premint_tokens $RECIPIENTS_ARRAY_ARG $AMOUNTS_ARRAY_ARG 2>&1 || true)