Skip to content

Commit ef7c3f9

Browse files
0xKurt0xKurt
committed
basic docs
1 parent e889f3b commit ef7c3f9

9 files changed

+664
-21
lines changed

‎README.md

+14-2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,15 @@
1-
# Headline
1+
## A Smart Contract Bot Protection
22

3-
> An awesome project.
3+
.. by using captchas. Solving captchas has become an intuitive part of the web2 ecosystem, that is very effective in the fight against bots. Currently in the beta phase, Solve3 remodels this native web2 tool into one that can easily and elegantly be utilized in web3 space.
4+
5+
## Getting Started
6+
7+
If you're new to Solve3, start with these two sections:
8+
9+
- [Contracts Overview](contract.md): Learn more about the contracts in general.
10+
- [Contract Implementation](contractImplementation.md): Find out how to add Solve3's protection to your smart contracts.
11+
- [Frontend Implementation](captcha.md): Discover how to incorporate Solve3's captcha module into your web3 applications.
12+
13+
## Dive Deeper
14+
15+
Use the sidebar to explore more about Solve3.

‎_coverpage.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<!-- _coverpage.md -->
2+
3+
![logo](_media/logo.svg)
4+
5+
# Solve3<small>docs</small>
6+
7+
> Bot Protection for Smart Contracts
8+
9+
10+
[GitHub](https://github.com/solve3-org/)
11+
[Get Started](contract)

‎_media/contract-diagram.png

55.7 KB
Loading

‎_media/logo.svg

+269
Loading

‎_sidebar.md

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<!-- docs/_sidebar.md -->
2+
3+
- [Introduction](/)
4+
- [Contracts Overview](contract.md)
5+
<!-- - [Diagram](contract#diagram)
6+
- [Solve3Master](contract#solve3master)
7+
- [Solve3Verify](contract#solve3verify) -->
8+
- [Contract Implementation](contractImplementation.md)
9+
- [Quick start](contractImplementation#quick-start)
10+
- [Import Solve3Verify](contractImplementation#import-the-contract)
11+
- [Inherit](contractImplementation#inherit-from-solve3verify)
12+
- [Initialize](contractImplementation#initialize-the-contract)
13+
- [Add modifier](contractImplementation#add-solve3verify-modifier)
14+
- [Disable Solve3](contractImplementation#abstract-function-disablesolve3)
15+
- [Advanced options](contractImplementation#advanced-options)
16+
- [Frontend Implementation](captcha.md)
17+
- [Quick start](captcha#quick-start)
18+
- [Installation](captcha#installation)
19+
- [Initialization](captcha#initialization)
20+
- [Event handling](captcha#event-handling)
21+
- [Handshake](captcha#handshake)
22+
- [Sign message](captcha#sign-message)
23+
- [Open captcha](captcha#open-captcha)
24+
- [Full Example](captcha#full-example)

‎captcha.md

+128
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
## Quick start <!-- {docsify-ignore-all} -->
2+
3+
4+
The Solve3 Captcha Node Module is designed to offer captcha protection for your smart contracts, effectively guarding against bot interference. Here's a step-by-step guide to help you integrate this module into your projects frontend.
5+
6+
### Installation
7+
8+
Begin by installing the `@solve3/captcha` package using npm or yarn. Open your terminal and run:
9+
10+
```bash
11+
npm install @solve3/captcha
12+
# or
13+
yarn add @solve3/captcha
14+
```
15+
16+
<!-- ### Usage -->
17+
18+
Now, let's dive into the implementation:
19+
20+
### Initialization
21+
22+
First, you need to initialize the Solve3 Captcha module by importing it and creating an instance of it. This step should be done at the beginning of your code.
23+
24+
```javascript
25+
import { Solve3 } from "@solve3/captcha";
26+
27+
const solve3 = new Solve3();
28+
```
29+
30+
### Event handling
31+
The Solve3 Captcha module emits a "success" event when the user successfully completes the captcha challenge. You can listen for this event and define what should happen when the event is triggered.
32+
33+
```javascript
34+
solve3.on("success", async (proof) => {
35+
// This is where you can send the transaction using the proof.
36+
// Example: sendTransaction(proof);
37+
});
38+
```
39+
40+
### Handshake
41+
42+
Before sending a transaction, you'll need a message (handshake) to sign. This message typically includes the user's wallet address, the destination contract, and the network ID (chain ID).
43+
44+
```javascript
45+
const messageToSign = await solve3.init({
46+
account: walletAddress,
47+
destination: destinationContract,
48+
network: chainId,
49+
});
50+
```
51+
52+
### Sign message
53+
54+
You need to sign the message with the user's wallet. This can be done using a signing function provided by your Ethereum library (e.g., ethers.js or web3.js). Make sure you have the user's wallet set up and available.
55+
56+
```javascript
57+
const signature = await signMessage(messageToSign);
58+
```
59+
60+
### Open captcha
61+
62+
Finally, open the Solve3 Captcha challenge, passing the previously obtained signature. This will display the captcha challenge to the user.
63+
64+
```javascript
65+
await solve3.open(signature);
66+
```
67+
68+
## Full Example
69+
70+
**using React.js and wagmi**
71+
72+
This React.js example initializes the Solve3 Captcha module, gets the message to sign, signs the message using wagmi, and opens the captcha challenge when the `Set Message`` button is clicked. Make sure to replace the placeholders with your actual values and Ethereum provider.
73+
74+
```javascript
75+
import { useState } from "react";
76+
import { useAccount, useSignMessage, useContractWrite } from "wagmi";
77+
import { abi } from "./abi";
78+
import { Solve3 } from "@solve3/captcha";
79+
80+
const Message = () => {
81+
const yourContract: `0x${string}` = "0xYourContractAddress";
82+
83+
const { signMessageAsync } = useSignMessage();
84+
const { address } = useAccount();
85+
const [message, setMessage] = useState<string>("");
86+
87+
const { writeAsync } = useContractWrite({
88+
address: yourContract,
89+
abi: abi,
90+
functionName: "setMessage",
91+
});
92+
93+
const solve3 = new Solve3();
94+
95+
solve3.on("success", async (proof: string) => {
96+
// function sig: setMessage(string memory message, bytes memory proof)
97+
await writeAsync({ args: [message, proof] });
98+
});
99+
100+
const onClickHandler = async () => {
101+
const messageToSign: string = await solve3.init({
102+
account: address as string,
103+
destination: yourContract,
104+
network: 5,
105+
});
106+
107+
const signature = await signMessageAsync({ message: messageToSign });
108+
await solve3.open(signature);
109+
};
110+
111+
return (
112+
<div>
113+
...
114+
<h3>New Message:</h3>
115+
<input
116+
type="text"
117+
value={message}
118+
onChange={(e) => setMessage(e.target.value)}
119+
/>
120+
<button onClick={onClickHandler}>Set Message</button>
121+
...
122+
</div>
123+
);
124+
};
125+
126+
export default Message;
127+
128+
```

‎contract.md

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
<h2>Contracts Overview</h2>
2+
3+
Solve3 consists of two essential contracts: `Solve3Master` and `Solve3Verify`. We'll provide an overview of these contracts, their functions, and their deployment addresses.
4+
5+
### Diagram <!-- {docsify-ignore-all} -->
6+
7+
![Diagram](_media/contract-diagram.png)
8+
9+
### Solve3Master <!-- {docsify-ignore} -->
10+
11+
The `Solve3Master` contract is the core of Solve3, managing signer status, nonces, and contract ownership. While developers are not required to implement it, understanding its inner workings can be valuable.
12+
13+
* **Functions**:
14+
15+
* `initialize(address _signer)`: Initializes the contract with a signer address.
16+
* `getNonce(address _account)`: Retrieves the nonce of an account.
17+
* `getTimestampAndNonce(address _account)`: Gets the timestamp and nonce of an account.
18+
* `isSigner(address _account)`: Checks if an account is a signer.
19+
* `setSigner(address _account, bool _flag)`: Sets the signer status of an account.
20+
* `transferOwnership(address _newOwner)`: Transfers ownership of the contract.
21+
* `recoverERC20(address _token)`: Recovers ERC20 tokens.
22+
* `verifyProof(bytes calldata _proof)`: Verifies a proof and returns account of the proof, timestamp and whether the proof was verified or not.
23+
* **Events**:
24+
25+
* `OwnershipTransferred`: Triggered when contract ownership is transferred.
26+
* `SignerChanged`: Fired when the signer status of an account changes.
27+
28+
### Solve3Verify
29+
30+
The `Solve3Verify` abstract contract is used to protect your smart contracts with Solve3. You must implement this contract to validate Solve3 proofs. It includes functions to set timestamps and disable Solve3 if needed.
31+
32+
#### Implementation Guide <!-- {docsify-ignore} -->
33+
34+
**Note:** Implementation guide can be found [here](contractsImplementation.md).
35+
36+
* **Functions**:
37+
38+
* `__init_Solve3Verify(address _solve3Master)`: Initializes the `Solve3Verify` contract with the Solve3 master contract.
39+
* `disableSolve3(bool _flag)`: Allows you to disable or enable Solve3 as needed.
40+
* `setValidPeriodSeconds(uint256 _validPeriodSeconds)`: Sets the period in seconds for which a signature is valid.
41+
* **Error Handling**:
42+
43+
* `Solve3VerifyInitializedAlready`: Thrown if trying to initialize the contract when it's already initialized.
44+
* `Solve3VerifyIsDisabled`: Thrown when a function requires Solve3 to be disabled.
45+
* `Solve3VerifyIsNotDisabled`: Thrown when a function requires Solve3 not to be disabled.
46+
* `Solve3VerifyUnableToVerify`: Thrown when a Solve3 proof cannot be verified.
47+
* `Solve3VerifyAddressMismatch`: Thrown when the account in the proof does not match the sender's account.
48+
* `Solve3VerifyMsgSignedTooEarly`: Thrown when a message is signed too early.
49+
* `Solve3VerifySignatureInvalid`: Thrown when a signature is invalid.
50+
* **Events**:
51+
52+
* `Solve3VerifyDisabled`: Fired when Solve3 is disabled.
53+
* `Solve3ValidFromTimestampSet`: Triggered when the valid-from timestamp is set.
54+
* `Solve3ValidPeriodSecondsSet`: Triggered when the valid period in seconds is set.

‎contractImplementation.md

+133
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
## Introduction <!-- {docsify-ignore} -->
2+
3+
4+
The `Solve3Verify.sol` contract is a critical component of the [Solve3](https://solve3.org) bot protection system. It enables you to verify Solve3 proofs and ensure secure interactions within your smart contracts. This documentation provides a detailed guide on integrating and using the `Solve3Verify` contract in your Ethereum-based projects.
5+
6+
## Quick Start <!-- {docsify-ignore} -->
7+
8+
Integrating the `Solve3Verify` contract into your project is a straightforward process. Here's a quick start guide:
9+
10+
### Import Solve3Verify <!-- {docsify-ignore} -->
11+
12+
Begin by importing the `Solve3Verify` contract into your Solidity project.
13+
14+
```solidity
15+
import "@solve3/contracts/Solve3Verify.sol";
16+
```
17+
18+
### Inherit from Solve3Verify <!-- {docsify-ignore} -->
19+
20+
In your contract, inherit from the `Solve3Verify` contract.
21+
22+
```solidity
23+
contract YourContract is Solve3Verify {
24+
// Your contract code here
25+
}
26+
```
27+
28+
### Initialize the Contract <!-- {docsify-ignore} -->
29+
30+
In your contract's constructor, call the `__init_Solve3Verify` function with the address of the Solve3 Master contract as an argument.
31+
32+
```solidity
33+
constructor(address _solve3Master) {
34+
__init_Solve3Verify(_solve3Master);
35+
// Your constructor code here
36+
}
37+
```
38+
39+
### Add solve3Verify modifier <!-- {docsify-ignore} -->
40+
41+
To verify the proof created by Solve3 you have to add the `solve3Verify` modifier to your function and pass the `_proof` parameter.
42+
43+
```solidity
44+
function foo(bytes memory _proof) external solve3Verify(_proof) {
45+
// Your function implementation
46+
}
47+
```
48+
49+
### Abstract Function disableSolve3 <!-- {docsify-ignore} -->
50+
51+
Since Solve3 is in beta, you have to implement a function to disable Solve3 verification in your contract.
52+
53+
!> Don't forget to add access control like OpenZeppelin `Ownable`
54+
55+
```solidity
56+
function disableSolve3(bool _flag) external override onlyOwner {
57+
_disableSolve3(_flag);
58+
}
59+
```
60+
61+
Your contract is now ready to verify Solve3 proofs for secure interactions.
62+
63+
## Advanced Options
64+
65+
The `Solve3Verify` contract provides optional functions to enhance flexibility and control in your project based on your personal needs or the chain you want to deploy to.
66+
67+
### Set Valid From Timestamp
68+
69+
To customize the timestamp from which the signature is valid, you can implement the following internal function:
70+
71+
```solidity
72+
function _setValidFromTimestamp(uint256 _validFromTimestamp) internal {
73+
validFromTimestamp = _validFromTimestamp;
74+
}
75+
```
76+
77+
This function allows you to adjust the timestamp based on your specific requirements.
78+
79+
**Note:** Per default the `validFromTimestamp` is set to timestamp of the contract deployment.
80+
81+
### Set Valid Period Seconds
82+
83+
You can modify the period in seconds for which the signature is valid using this internal function:
84+
85+
```solidity
86+
function _setValidPeriodSeconds(uint256 _validPeriodSeconds) internal {
87+
validPeriodSeconds = _validPeriodSeconds;
88+
}
89+
```
90+
91+
Use this function to change the period for which the signature remains valid.
92+
93+
**Note:** Per default the `validPeriodSeconds` is set to 300 seconds.
94+
95+
Developers can customize the `validFrom` and `validPeriod` functionality by overriding the following functions:
96+
97+
### Custom validFrom Implementation
98+
99+
`function validFrom() public view virtual returns (uint256)`
100+
101+
This overridable function allows developers to modify the timestamp from which the signature is considered valid.
102+
103+
```solidity
104+
function validFrom() public view virtual returns (uint256) {
105+
// Custom logic to determine the validFrom timestamp
106+
return yourCustomValidFromTimestamp;
107+
}
108+
```
109+
110+
### Custom validPeriod Implementation
111+
112+
`function validPeriod() public view virtual returns (uint256)`
113+
114+
This overridable function enables developers to change the period in seconds for which the signature remains valid.
115+
116+
```solidity
117+
function validPeriod() public view virtual returns (uint256) {
118+
// Custom logic to determine the valid period in seconds
119+
return yourCustomValidPeriodSeconds;
120+
}
121+
```
122+
123+
These functions provide flexibility for developers to adapt Solve3 verification to their specific project requirements.
124+
125+
126+
## Public Variables and View Functions
127+
128+
The `Solve3Verify` contract includes various public variables and view functions for inspecting its state. These include:
129+
130+
* `public solve3Master`: The address of the Solve3 Master contract.
131+
* `public solve3Disabled`: A flag indicating whether Solve3 verification is disabled.
132+
* `public validFromTimestamp`: The timestamp from which the signature is valid.
133+
* `public validPeriodSeconds`: The period in seconds for which the signature is valid.

0 commit comments

Comments
 (0)