docs

contracts/docs_templates/{{contracts}}.hbs

@@ -66,7 +66,10 @@ outline: deep
 {{#each errors}}
 ### **{{{name}}}**
 
-{{{notice}}}
+{{#each notice}}
+{{{this}}}
+
+{{/each}}
 
 {{{fullFormat}}}
 

contracts/src/game/interface/IStratagems.sol

@@ -36,7 +36,10 @@ interface IStratagemsGameplay is UsingStratagemsTypes, UsingStratagemsEvents {
 	function addToReserve(uint256 tokensAmountToAdd, Permit calldata permit) external;
 
 	/// @notice called by players to commit their moves
-	///  this can be called multiple time, the last call overriding the previous.
+	///  this can be called multiple time in the same epoch, the last call overriding the previous.
+	///  When a commitment is made, it needs to be resolved in the resolution phase of the same epoch.abi
+	///  If missed, player can still reveal its moves but none of them will be resolved.
+	///   The player would lose its associated reserved amount.
 	/// @param commitmentHash the hash of the moves
 	function makeCommitment(bytes24 commitmentHash) external;
 
@@ -70,8 +73,10 @@ interface IStratagemsGameplay is UsingStratagemsTypes, UsingStratagemsEvents {
 	/// @param secret the secret used to make the commit
 	/// @param moves the actual moves
 	/// @param furtherMoves if moves cannot be contained in one tx, further moves are represented by a hash to resolve too
-	///  Note that you have to that number of mvoes
-	/// @param useReserve whether the tokens are taken from the reserve or from approvals
+	///  Note that you have to that have enough moves (specified by MAX_NUM_MOVES_PER_HASH = 32)
+	/// @param useReserve whether the tokens are taken from the reserve or from approvals.
+	///  This allow player to keep their reserve intact and use it on their next move.
+	///  Note that this require the Stratagems contract to have enough allowance.
 	function resolve(
 		address player,
 		bytes32 secret,
@@ -80,7 +85,7 @@ interface IStratagemsGameplay is UsingStratagemsTypes, UsingStratagemsEvents {
 		bool useReserve
 	) external;
 
-	/// @notice called by player if they missed the resolution phase and want to minimze the token loss
+	/// @notice called by player if they missed the resolution phase and want to minimze the token loss.
 	///  By providing the moves, they will be slashed only the amount of token required to make the moves
 	/// @param player the account who committed the move
 	/// @param secret the secret used to make the commit
@@ -95,14 +100,15 @@ interface IStratagemsGameplay is UsingStratagemsTypes, UsingStratagemsEvents {
 
 	/// @notice should only be called as last resort
 	/// this will burn all tokens in reserve
-	/// If player has access to the secret, better call acknowledgeMissedResolution
+	/// If player has access to the secret, better call `acknowledgeMissedResolution`
 	function acknowledgeMissedResolutionByBurningAllReserve() external;
 
-	/// @notice poke a position, resolving its virtual state and if dead, reward neighboor enemies colors
+	/// @notice poke a position, resolving its virtual state.
+	//  If dead as a result, it will reward neighboor enemies colors
 	/// @param position the cell position
 	function poke(uint64 position) external;
 
-	/// poke and collect the tokens won
+	/// @notice poke and collect the tokens won across multiple cells
 	/// @param positions cell positions to collect from
 	function pokeMultiple(uint64[] calldata positions) external;
 }

contracts/src/game/interface/UsingStratagemsErrors.sol

@@ -2,14 +2,44 @@
 pragma solidity ^0.8.0;
 
 interface UsingStratagemsErrors {
+	/// @notice Game has not started yet, can't perform any action
 	error GameNotStarted();
+
+	/// @notice When in Resolution phase, it is not possible to commit new moves or cancel previous commitment
+	///  During Resolution phase, players have to reveal their commitment, if not already done.
 	error InResolutionPhase();
+
+	/// @notice When in Commit phase, player can make new commitment but they cannot resolve their move yet.
 	error InCommitmentPhase();
+
+	/// @notice Previous commitment need to be resolved before making a new one. Even if the corresponding reveal phase has passed.\
+	///  It is also not possible to withdraw any amount from reserve until the commitment is revealed.\
+	/// @notice If player lost the information to reveal, it can acknowledge failure which will burn all its reserve.\
 	error PreviousCommitmentNotResolved();
+
+	/// @notice to make a commitment you always need at least one `config.numTokensPerGems` amount in reserve
+	///  Player also need one `config.numTokensPerGems`  per moves during the resolution phase.
+	/// @param inReserve amount in reserver as the time of the call
+	/// @param expected amount required to proceed
 	error ReserveTooLow(uint256 inReserve, uint256 expected);
+
+	/// @notice Player have to reveal their commitment using the exact same move values
+	///  If they provide different value, the commitment hash will differ and Stratagems will reject their resolution.
 	error CommitmentHashNotMatching();
+
+	/// @notice Player can only resolve moves they commited.
 	error NothingToResolve();
+
+	/// @notice Player can only resolve their move in the same epoch they commited.abi
+	///  If a player resolve later it can only do to minimize the reserve burn cost by calling : `acknowledgeMissedResolution`
 	error InvalidEpoch();
+
+	/// @notice Player can make arbitrary number of moves per epoch. To do so they group moves into (MAX_NUM_MOVES_PER_HASH = 32) moves
+	///  This result in a recursive series of hash that they can then submit in turn while resolving.
+	///  The limit  (MAX_NUM_MOVES_PER_HASH = 32) ensure a resolution batch fits in a block.
 	error InvalidFurtherMoves();
+
+	/// @notice Player have to resolve if they can
+	/// Stratagems will prevent them from acknowledging missed resolution if there is still time to resolve.
 	error CanStillResolve();
 }

contracts/src/game/interface/UsingStratagemsEvents.sol

@@ -53,6 +53,10 @@ interface UsingStratagemsEvents is UsingStratagemsTypes {
 	// Event to make it easier to check what is happening
 	// TODO get rid ?
 	// --------------------------------------------------------------------------------------------
-
+	/// @notice A move has been resolved.
+	/// @param position cell at which the move take place
+	/// @param player account making the move
+	/// @param oldColor previous color of the cell
+	/// @param newColor color that takes over
 	event MoveProcessed(uint64 indexed position, address indexed player, Color oldColor, Color newColor);
 }

contracts/src/game/interface/UsingStratagemsTypes.sol

@@ -21,11 +21,13 @@ interface UsingStratagemsTypes {
 		Evil
 	}
 
+	/// @notice Move struct that define position and color
 	struct Move {
 		uint64 position; // TODO make it bigger ? uint32 * uint32 is probably infinitely big enough
 		Color color;
 	}
 
+	/// @notice Permit struct to authorize EIP2612 ERC20 contracts
 	struct Permit {
 		uint256 value;
 		uint256 deadline;
@@ -34,6 +36,7 @@ interface UsingStratagemsTypes {
 		bytes32 s;
 	}
 
+	/// @notice Config struct to configure the game instance
 	struct Config {
 		IERC20WithIERC2612 tokens;
 		address payable burnAddress;
@@ -44,6 +47,7 @@ interface UsingStratagemsTypes {
 		uint256 numTokensPerGems;
 	}
 
+	/// @notice Cell struct representing the current state of a cell
 	struct FullCell {
 		address owner;
 		uint24 lastEpochUpdate;

contracts/src/game/internal/UsingStratagemsState.sol

@@ -93,7 +93,7 @@ abstract contract UsingStratagemsState is
 	address payable internal immutable BURN_ADDRESS;
 
 	/// @notice the number of moves a hash represent, after that players make use of furtherMoves
-	uint8 internal constant MAX_NUM_MOVES_PER_HASH = 16;
+	uint8 internal constant MAX_NUM_MOVES_PER_HASH = 32;
 
 	/// @notice Create an instance of a Stratagems game
 	/// @param config configuration options for the game

docs/contracts/Gems.md

@@ -264,6 +264,7 @@ event Transfer(address indexed from, address indexed to, uint256 value)
 
 The permit has expired
 
+
 error DeadlineOver(uint256 currentTime, uint256 deadline)
 
 | Name | Description 
@@ -275,6 +276,7 @@ error DeadlineOver(uint256 currentTime, uint256 deadline)
 
 An invalid address is specified (for example: zero address)
 
+
 error InvalidAddress(address addr)
 
 | Name | Description 
@@ -285,6 +287,7 @@ error InvalidAddress(address addr)
 
 The msg value do not match the expected value
 
+
 error InvalidMsgValue(uint256 provided, uint256 expected)
 
 | Name | Description 
@@ -296,12 +299,14 @@ error InvalidMsgValue(uint256 provided, uint256 expected)
 
 The signature do not match the expected signer
 
+
 error InvalidSignature()
 
 ### **InvalidTotalAmount**
 
 The total amount provided do not match the expected value
 
+
 error InvalidTotalAmount(uint256 provided, uint256 expected)
 
 | Name | Description 
@@ -313,6 +318,7 @@ error InvalidTotalAmount(uint256 provided, uint256 expected)
 
 the amount requested exceed the allowance
 
+
 error NotAuthorizedAllowance(uint256 currentAllowance, uint256 expected)
 
 | Name | Description 
@@ -324,6 +330,7 @@ error NotAuthorizedAllowance(uint256 currentAllowance, uint256 expected)
 
 the amount requested exceed the balance
 
+
 error NotEnoughTokens(uint256 currentBalance, uint256 expected)
 
 | Name | Description