feat: manta pacific testnet doc

docs/introduction/Manta-Pacific.md

@@ -12,15 +12,15 @@ Manta Pacific takes all of the work that the Manta team has already built on ZK,
 
 # How Does Manta Pacific Work?
 
-Manta Pacific is launched in the joint vision with Celestia and Optimism. By leveraging the data-availability layer provided by Celestia, the first modular consensus and data network, harnessing the advanced technology developed by p0x labs, and partnering with leading RaaS company Caldera, Manta Pacific build out an accessible ZK development environment in a modular, scalable manner with multiple groundbreaking advantages:
+Manta Pacific is launched in the joint vision with Celestia and Optimism. By leveraging the data-availability layer provided by Celestia, the first modular consensus and data network, harnessing the advanced technology developed by p0x labs, and partnering with leading RaaS company Manta Pacific, Manta Pacific build out an accessible ZK development environment in a modular, scalable manner with multiple groundbreaking advantages:
 
 ## 1. Significantly lower gas fee than any other ZK layer
 
 Manta Pacific’s modular stack provides unparalleled scalability for future zkApps building on top of our ecosystem.
 
 Manta Pacific uses Celestia as the data availability (DA) layer. Celestia uses the state of art data availability sampling - a 2-D Reed-Solomon encoding and Namespaced Merkle Tree (NMTs) - to solve the data availability problem of L2s in a trust-minimized way. Manta Pacific, which uses Celestia as the DA layer, can dramatically reduce the data portion of transaction costs on the network for the end users.
 
-Manta Pacific uses Caldera’s customized OP Stack Rollup solution as the execution layer. OP Stack has already been adopted by top projects for rollup solutions including Coinbase, a16z and Worldcoin. As the de-facto standard of L2 scaling, especially with the recent launch of Bedrock, OP Stack offers the best interoperability, engineering maturity, and long-term ecosystem outlook. In addition to scaling the computation using OP Stack, we leverage Caldera’s stateful precompiles to further reduce the computation cost of zero-knowledge proof verification-related costs.
+Manta Pacific uses Manta Pacific’s customized OP Stack Rollup solution as the execution layer. OP Stack has already been adopted by top projects for rollup solutions including Coinbase, a16z and Worldcoin. As the de-facto standard of L2 scaling, especially with the recent launch of Bedrock, OP Stack offers the best interoperability, engineering maturity, and long-term ecosystem outlook. In addition to scaling the computation using OP Stack, we leverage Caldera’s stateful precompiles to further reduce the computation cost of zero-knowledge proof verification-related costs.
 
 ## 2. EVM + Manta’s universal circuit rather than new language for wide ZK applications adoption
 Manta Atlantic deployed the first generation of Universal Circuits for the web3 industry, which offered support for various zkAssets including both fungible tokens and NFTs. Through Universal Circuits on Manta Atlantic, developers only need to use high level APIs to access programmable zkAsset.

docs/manta-pacific/Block Explorer.md

@@ -0,0 +1,9 @@
+Manta Pacific Chain comes equipped with a user-friendly block explorer that allows for easy viewing of important information such as:
+- Address balances
+- Transaction history
+- Verified contracts
+- Smart contract code and execution
+- Network statistics
+- Mining information
+
+It provides a valuable tool for anyone looking to better understand and interact with a blockchain, it provides transparency and accessibility to the inner workings of a blockchain, and it can be used for a variety of purposes such as tracking transactions, monitoring smart contract execution, and analyzing network activity.

docs/manta-pacific/EVM Compatible.md

@@ -0,0 +1,6 @@
+Manta Pacific chain is fully compatible with the Ethereum Virtual Machine, allowing them to run standard Ethereum smart contract code without modification or recompilation. This compatibility means that Manta Pacific work seamlessly with a wide range of existing Ethereum tooling, including:
+- General-purpose libraries like Ethers.js and Web3.js
+- Developer tools like Hardhat and Foundry
+- Popular wallets like Metamask
+
+This makes it easy for developers to build and deploy smart contracts, using the same tools and techniques they are already familiar with. Additionally, this compatibility ensures that existing Ethereum-based dApps can be easily ported to Manta Pacific with minimal modifications, providing a wide range of use cases and opportunities for developers to create new decentralized applications.

docs/manta-pacific/Faucet.md

@@ -0,0 +1,3 @@
+Manta Pacific chains include a built-in crypto faucet that allows users to easily acquire and test the native cryptocurrency of the chain. This feature is designed to make it easy for developers, testers, and new users to obtain small amounts of cryptocurrency and use it to explore the functionality and features of the blockchain.
+The faucet feature is typically configured to dispense small amounts of cryptocurrency to users who request it, allowing them to test the functionality of the chain without having to make a purchase.
+The crypto faucet feature is a valuable tool for developers who are building applications on top of the chain, as it allows them to test their applications with real cryptocurrency without incurring any financial risk. Additionally, it is a great way for new users to get started with the blockchain and familiarize themselves with its features and functionality.

docs/manta-pacific/JSON-RPC Nodes.md

@@ -0,0 +1,2 @@
+Manta Pacific provide a JSON-RPC interface that allows developers and users to interact with the blockchain and perform various actions, such as sending transactions, querying account balances, and more. The nodes in the chain are designed to serve JSON-RPC requests over both HTTP(S) and Websockets, providing a flexible and convenient way to interact with the blockchain. The behavior of the JSON-RPC interface is defined by the Ethereum JSON-RPC specification, providing a standard and familiar interface for developers to work with.
+One of the key advantages of this JSON-RPC compatibility is that it provides compatibility with existing client libraries, such as Ethers.js, Web3.js, Web3.py and go's web3 library. These libraries are widely used in the Ethereum ecosystem and provide developers with a convenient way to interact with the blockchain using familiar and well-documented APIs. This compatibility ensures that developers can easily build and deploy decentralized applications on Manta Pacific using the same tools and techniques they are already familiar with.

docs/manta-pacific/Testnet Info.md

@@ -0,0 +1,7 @@
+You can deploy your application onto a Manta Pacific Chain via the same means as any Ethereum-compatible blockchain.
+
+- RPC URL : https://manta-testnet.calderachain.xyz/http
+- Websocket URL : wss://manta-testnet.calderachain.xyz/ws
+- Chain ID : 3441005
+
+[More Testnet Information](https://pacific.manta.network/)

docs/zkShuffle/Circuits/01-ContractInterface.md

@@ -0,0 +1,282 @@
+---
+title: 'Contract Interface'
+description: 'zkShuffle Contract desc'
+---
+
+
+# Overview
+
+zkShuffle Contracts provide two contract interfaces to help developers build their own card games:
+- [IShuffleStateManager](https://github.com/manta-network/zkShuffle/blob/main/packages/contracts/contracts/shuffle/IShuffleStateManager.sol): The manager of shuffle state machine, which creates and registers shuffle state, deals and opens cards.
+- [IBaseGame](https://github.com/manta-network/zkShuffle/blob/main/packages/contracts/contracts/shuffle/IBaseGame.sol): Developers need to inherit this interface when writing their own game contracts.
+
+
+# IShuffleStateManager
+
+### createShuffleGame
+
+```function createShuffleGame(uint8 numPlayers) external returns (uint256)```[[src]](https://github.com/manta-network/zkShuffle/blob/main/packages/contracts/contracts/shuffle/ShuffleManager.sol#L161-L163)
+
+Creates a new game and returns the game ID of the newly created game.
+This could only be called by game contract.
+
+**Parameters:**
+- ```numPlayers```: The number of players.
+
+**Return:**
+- ```gameId```: The created shuffle game ID.
+
+**Example:**
+```solidity
+pragma solidity >=0.8.2 <0.9.0;
+import "IBaseGame.sol";
+import "IShuffleStateManager.sol";
+contract Game is IBaseGame {
+    IShuffleStateManager public shuffle;
+    constructor(IShuffleStateManager _shuffle) {
+        shuffle = _shuffle;
+    }
+    function createGame() external {
+        uint256 shuffleId = shuffle.createShuffleGame(2);
+        ...
+    }
+    ...
+}
+```
+
+### register
+
+```function register(uint256 gameId, bytes calldata next) external```[[src]](https://github.com/manta-network/zkShuffle/blob/main/packages/contracts/contracts/shuffle/ShuffleManager.sol#L210-L217)
+
+Enters the register state, which can only be called by the game owner.
+
+**Parameters:**
+- ```gameId```: The created shuffle game ID.
+- ```next```: The calldata that contains the function signature and parameters, and it will be executed in the next invocation.
+
+> **Note:** The ```gameId``` parameter in all the interfaces corresponds to the return value of the ```createShuffleGame``` function.
+
+> **Note:** ```register``` only initiate the registration phase so that players can register, it doesn't actually perform the registration.
+
+### playerRegister
+
+```function playerRegister(uint256 gameId, address signingAddr, uint256 pkX, uint256 pkY) external returns (uint256)```[[src]](https://github.com/manta-network/zkShuffle/blob/main/packages/contracts/contracts/shuffle/ShuffleManager.sol#L228-L233)
+
+Performs the registration for a certain player, which can be called by game contract or directly called by user.
+
+**Parameters:**
+- ```gameId```: The created shuffle game ID.
+- ```signingAddr```: The signing address of the player, usually it's player's metamask address.
+- ```pkX```: The X-coordinate of the public key generated by BabyJub curve. It can be generated by SDK
+- ```pkY```: The Y-coordinate of the public key generated by BabyJub curve. It can be generated by SDK
+
+**Return:**
+- ```pid```: The player index in the game.
+
+> **Note:** If you don't have special needs, it's better to use SDK to do the registering.
+
+**Example:**
+```solidity
+pragma solidity >=0.8.2 <0.9.0;
+import "IBaseGame.sol";
+import "IShuffleStateManager.sol";
+contract Game is IBaseGame {
+    IShuffleStateManager public shuffle;
+    uint256 public shuffleId;
+    constructor(IShuffleStateManager _shuffle) {
+        shuffle = _shuffle;
+    }
+    function createGame() external {
+        shuffleId = shuffle.createShuffleGame(2);
+    }
+    function registerGame(uint256 pkX, uint256 pkY) external {
+        bytes memory next = abi.encodeWithSelector(
+            this.dummy.selector
+        );
+        shuffle.register(shuffleId, next);
+        uint256 playerIdx = shuffle.playerRegister(
+            shuffleId,
+            msg.sender,
+            pkX,
+            pkY
+        );
+        ...
+    }
+    function dummy() external {
+        ...
+    }
+    ...
+}
+```
+
+### shuffle
+
+```function shuffle(uint256 gameId, bytes calldata next) external```[[src]](https://github.com/manta-network/zkShuffle/blob/main/packages/contracts/contracts/shuffle/ShuffleManager.sol#L280-L283)
+
+Initiates the shuffle phase, which can only be called by game contract.
+
+**Parameters:**
+- ```gameId```: The created shuffle game ID.
+- ```next```: The calldata that will be executed in the next invocation.
+
+> **Note:** ```shuffle``` only initiate the shuffle phase so that players can shuffle, it doesn't actually perform the shuffle.
+
+### dealCardsTo
+
+```function shuffle(uint256 gameId, BitMaps.BitMap256 memory cards, uint256 playerId, bytes calldata next) external```[[src]](https://github.com/manta-network/zkShuffle/blob/main/packages/contracts/contracts/shuffle/ShuffleManager.sol#L332-L337)
+
+Specifies a set of cards to be dealed to a players, which can only be called by game contract.
+
+**Parameters:**
+- ```gameId```: The created shuffle game ID.
+- ```cards```: The cards to deal.
+- ```playerId```: The player index in the shuffle game.
+- ```next```: The calldata that will be executed in the next invocation.
+
+> **Note:** ```dealCardsTo``` only initiate the dealing phase so that players can deal, it doesn't actually perform the dealing.
+
+> **Note:** ```cards``` is represented in bitMap. For example: if the data of ```cards``` is 28, it corresponds to the binary representation 11100. This means that the cards with indexes [2, 3, 4] need to be dealt.
+
+### openCards
+
+```function openCards(uint256 gameId, uint256 playerId, uint8 openningNum, bytes calldata next) external```[[src]](https://github.com/manta-network/zkShuffle/blob/main/packages/contracts/contracts/shuffle/ShuffleManager.sol#L477-L482)
+
+Specifies a player to open a number of cards, which can only be called by game contract.
+
+**Parameters:**
+- ```gameId```: The created shuffle game ID.
+- ```playerId```: The player index in the shuffle game.
+- ```openningNum```: The number of cards that the player wants to open.
+- ```next```: The calldata that will be executed in the next invocation.
+
+```register``` ```shuffle``` ```dealCardsTo``` ```openCards```, these four functions all specify ```next``` as the next operation to be executed, but their execution timing is different.
+| function | when ```next``` will be called |
+|:--------|:--------|
+| register | after all the players have registered |
+| shuffle | after all the players have shuffled the deck |
+| dealCardsTo | after all the players except for the one with the ```playerId``` have dealt cards |
+| openCards | after each player has opened cards |
+
+### endGame
+
+```function openCards(uint256 gameId) external```[[src]](https://github.com/manta-network/zkShuffle/blob/main/packages/contracts/contracts/shuffle/ShuffleManager.sol#L547-L548)
+
+Ends the game, which can only be called by game contract.
+
+**Parameters:**
+- ```gameId```: The created shuffle game ID.
+
+### curPlayerIndex
+
+```function curPlayerIndex(uint256 gameId) external returns(uint256)```[[src]](https://github.com/manta-network/zkShuffle/blob/main/packages/contracts/contracts/shuffle/ShuffleManager.sol#L78-L80)
+
+Gets the player index of which player needs to take action.
+
+**Parameters:**
+- ```gameId```: The created shuffle game ID.
+
+**Return:**
+- ```currentPlayerIdx```: The currentPlayerIdx indicates which player needs to take action.
+
+### getPlayerIdx
+
+```function getPlayerIdx(uint256 gameId, address player) external returns(uint256)```[[src]](https://github.com/manta-network/zkShuffle/blob/main/packages/contracts/contracts/shuffle/ShuffleManager.sol#L140-L143)
+
+Gets the player index of `player` in `gameId` game.
+
+**Parameters:**
+- ```gameId```: The created shuffle game ID.
+- ```player```: The player's address.
+
+**Return:**
+- ```playerIdx```: The player index in the shuffle game.
+
+### INVALID_INDEX
+
+INVALID_INDEX is a constant with a value of 999999, used to represent an invalid card index and player index.
+
+**Example:**
+```solidity
+pragma solidity >=0.8.2 <0.9.0;
+import "IBaseGame.sol";
+import "IShuffleStateManager.sol";
+contract Game is IBaseGame {
+    IShuffleStateManager public shuffle;
+    uint256 public shuffleId;
+    ...
+    function getPlayerIndex() external {
+        uint256 playerIdx = shuffle.getPlayerIdx(shuffleId, msg.sender);
+        require(playerIdx != shuffle.INVALID_INDEX());
+        ...
+    }
+}
+```
+
+### getNumCards
+
+```function getNumCards(uint256 gameId) external returns(uint256)```[[src]](https://github.com/manta-network/zkShuffle/blob/main/packages/contracts/contracts/shuffle/ShuffleManager.sol#L64-L66)
+
+Gets the number of cards.
+
+**Parameters:**
+- ```gameId```: The created shuffle game ID.
+
+**Return:**
+- ```numCards```: The number of cards.
+
+### queryCardValue
+
+```function queryCardValue(uint256 gameId, uint256 cardIndex) external returns(uint256)```[[src]](https://github.com/manta-network/zkShuffle/blob/main/packages/contracts/contracts/shuffle/ShuffleManager.sol#L580-L583)
+
+Queries the card value of `cardIndex`-th card in `gameId`.
+
+**Parameters:**
+- ```gameId```: The created shuffle game ID.
+- ```cardIndex```: The index of a card in the deck.
+
+**Return:**
+- ```cardValue```: The actual card value in the deck.
+
+### getDecryptRecord
+
+```function getDecryptRecord(uint256 gameId, uint256 cardIdx) external returns(BitMaps.BitMap256 memory)```[[src]](https://github.com/manta-network/zkShuffle/blob/main/packages/contracts/contracts/shuffle/ShuffleManager.sol#L86-L89)
+
+Gets the decryption record (i.e., which players have decrypted this card).
+
+**Parameters:**
+- ```gameId```: The created shuffle game ID.
+- ```cardIdx```: The index of a card in the deck.
+
+**Return:**
+- ```record```: It indicates which players have already dealt this card. For example, if the ```record``` value is 5, it corresponds to the binary representation 101. This means that the player with indexes [0, 2] has dealt the card.
+
+### queryAggregatedPk
+
+```function queryAggregatedPk(uint256 gameId) external returns(uint px, uint py)```[[src]](https://github.com/manta-network/zkShuffle/blob/main/packages/contracts/contracts/shuffle/ShuffleManager.sol#L96-L98)
+
+Queries the aggregated public key for card shuffling/dealing in `gameId`-th game. The public key is a elliptic curve point on BN254 G1 curve.
+
+**Parameters:**
+- ```gameId```: The created shuffle game ID.
+
+**Return:**
+- ```pkX```: The X-coordinate of the aggregated public key.
+- ```pkY```: The Y-coordinate of the aggregated public key.
+
+## IBaseGame
+
+### cardConfig
+Developers need to implement the cardConfig interface, which represents the number of cards included in the game.
+
+**Example:**
+```solidity
+pragma solidity >=0.8.2 <0.9.0;
+import "IBaseGame.sol";
+contract Game is IBaseGame {
+    // This indicates that the game contract is based on a deck of 30 cards.
+    function cardConfig() external pure override returns (DeckConfig) {
+        return DeckConfig.Deck30Card;
+    }
+    ...
+}
+```