|
1 | | -# COTI V2 Confidentiality Preserving L2 | SDKs and Examples |
| 1 | +[](https://telegram.coti.io) |
| 2 | +[](https://discord.coti.io) |
| 3 | +[](https://twitter.coti.io) |
| 4 | +[](https://youtube.coti.io) |
2 | 5 |
|
3 | | -All repositories specified below contain smart contracts that implement confidentiality features using the COTI V2 |
4 | | -protocol. |
5 | | -The contracts provide examples for various use cases, such as Non-Fungible Tokens (NFTs), ERC20 tokens, Auction, and |
6 | | -Identity management. |
| 6 | +# coti-sdk-python |
7 | 7 |
|
8 | | -These contracts demonstrate how to leverage the confidentiality features of the COTI V2 protocol to enhance privacy and |
9 | | -security in decentralized applications. |
10 | | -The contracts are written in Solidity and can be compiled and deployed using popular development tools like Hardhat and |
11 | | -Foundry. |
| 8 | +[](https://pypi.org/project/coti-sdk/) |
| 9 | +[](https://www.python.org/downloads/release/python-31014/) |
12 | 10 |
|
13 | | -#### Important Links: |
| 11 | +Welcome to the official COTI Python SDK, a powerful SDK that allows developers to encrypt of transaction inputs and decrypt of encrypted data on the COTI blockchain. |
14 | 12 |
|
15 | | -[Docs](https://docs.coti.io) | [Devnet Explorer](https://explorer-devnet.coti.io) | [Discord](https://discord.gg/cuCykh8P4m) | [Faucet](https://faucet.coti.io) |
| 13 | +## Documentation |
16 | 14 |
|
17 | | -Interact with the network using any of the following: |
| 15 | +Full API documentation is available in the [COTI docs](https://docs.coti.io/coti-v2-documentation/build-on-coti/tools/python-sdk) |
18 | 16 |
|
19 | | -1. [Python SDK](https://github.com/coti-io/coti-sdk-python) | [Python SDK Examples](https://github.com/coti-io/coti-sdk-python-examples) |
20 | | -2. [Typescript SDK](https://github.com/coti-io/coti-sdk-typescript) | [Typescript SDK Examples](https://github.com/coti-io/coti-sdk-typescript-examples) |
21 | | -3. [Hardhat Dev Environment](https://github.com/coti-io/confidentiality-contracts) |
| 17 | +## Build and Install |
22 | 18 |
|
23 | | -The following contracts are available in each of the packages: |
24 | | - |
25 | | -| Contract | | python sdk | hardhat sdk | typescript sdk | Contract Description | |
26 | | -|--------------------------------|------------|------------|-------------|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------| |
27 | | -| `AccountOnboard` | deployment | ✅ * | ✅ | ❌ | Onboard a EOA account - During onboard network creates AES unique for that EOA which is used for decrypting values sent back from the network | |
28 | | -| `AccountOnboard` | execution | ✅ | ✅ | ✅ | " | |
29 | | -| `ERC20Example` | deployment | ✅ | ✅ | ❌ | Confidential ERC20 - deploy and transfer encrypted amount of funds | |
30 | | -| `ERC20Example` | execution | ✅ | ✅ | ✅ | " | |
31 | | -| `NFTExample` | deployment | ❌ | ✅ | ❌ | Confidential NFT example - saving encrypted data | |
32 | | -| `NFTExample` | execution | ❌ | ✅ | ❌ | " | |
33 | | -| `ConfidentialAuction` | deployment | ❌ | ✅ | ❌ | Confidential auction - encrypted bid amount | |
34 | | -| `ConfidentialAuction` | execution | ❌ | ✅ | ❌ | " | |
35 | | -| `ConfidentialIdentityRegistry` | deployment | ❌ | ✅ | ❌ | Confidential Identity Registry - Encrypted identity data | |
36 | | -| `ConfidentialIdentityRegistry` | execution | ❌ | ✅ | ❌ | " | |
37 | | -| `DataOnChain` | deployment | ✅ | ❌ | ❌ | Basic encryption and decryption - Good place to start explorining network capabilties | |
38 | | -| `DataOnChain` | execution | ✅ | ❌ | ✅ | " | |
39 | | -| `Precompile` | deployment | ✅ | ✅ | ❌ | Thorough examples of the precompile functionality | |
40 | | -| `Precompile` | execution | ✅ | ✅ | ❌ | " |- | |
41 | | - |
42 | | -(*) no deployment needed (system contract) |
43 | | - |
44 | | -> [!NOTE] |
45 | | -> Due to the nature of ongoing development, future versions might break existing functionality |
46 | | -
|
47 | | -### Faucet |
48 | | - |
49 | | -🤖 To request devnet/testnet funds use |
50 | | -our [faucet](https://faucet.coti.io) ([join discord] (https://discord.gg/cuCykh8P4m))) |
51 | | - |
52 | | -# COTI v2 Python SDK |
53 | | - |
54 | | -> [!NOTE] |
55 | | -> Please refer to the latest [tags](https://github.com/coti-io/coti-sdk-python/tags) to find the most stable version to |
56 | | -> use. |
57 | | -> All tagged versions are available to install via [pypi](https://pypi.org/project/coti-sdk/) |
58 | | -
|
59 | | -The COTI Python SDK can be installed as pypi package named `coti_sdk`, its modules are: |
60 | | - |
61 | | -1. `crypto_utils`: used for cryptographic operations |
62 | | -2. `utils` : used for web3 related operations |
63 | | - |
64 | | -The [Python script examples](https://github.com/coti-io/coti-sdk-python-examples) project contain scripts covering |
65 | | -various use cases, such as Non-Fungible Tokens (NFTs), ERC20 tokens, Auctions, and Identity management. It contains |
66 | | -smart contracts that implement confidentiality features using the COTI V2 protocol. These contracts demonstrate how to |
67 | | -leverage the confidentiality features of the COTI V2 protocol to implement privacy and enhance security in decentralized |
68 | | -applications. |
69 | | - |
70 | | -## Getting initial funds from the COTI Faucet |
71 | | - |
72 | | -The COTI faucet provides devnet/testnet funds for developers. To request devnet/testnet tokens: |
73 | | - |
74 | | -1. Head to https://faucet.coti.io/ |
75 | | -2. Send a message to the bot in the following format: |
76 | | - |
77 | | -``` |
78 | | -devnet <your_eoa_address> |
| 19 | +```bash |
| 20 | +pip install . |
79 | 21 | ``` |
80 | 22 |
|
81 | | -For Example: |
82 | | - |
83 | | -``` |
84 | | -devnet 0x71C7656EC7ab88b098defB751B7401B5f6d8976F |
85 | | -``` |
86 | | - |
87 | | -## Libraries |
88 | | - |
89 | | -There are two libraries located in the [coti](/coti/) folder that will allow you to interact with the COTI network. |
90 | | - |
91 | | -# Crypto Utilities (crypto_utils.py) |
92 | | -## Functions |
93 | | - |
94 | | -### `encrypt(key, plaintext)` |
95 | | - |
96 | | -Encrypts a 128-bit `plaintext` using the provided 128-bit AES `key` and ECB mode. |
97 | | - |
98 | | -- **Parameters:** |
99 | | - - `key (bytes)`: 128-bit AES key (16 bytes). |
100 | | - - `plaintext (bytes)`: 128-bit or smaller plaintext to encrypt. |
101 | | - |
102 | | -- **Returns:** |
103 | | - - `ciphertext (bytes)`: The encrypted text. |
104 | | - - `r (bytes)`: A random value used during encryption. |
105 | | - |
106 | | -### `decrypt(key, r, ciphertext)` |
107 | | - |
108 | | -Decrypts the `ciphertext` using the provided 128-bit AES `key` and the random value `r`. |
109 | | - |
110 | | -- **Parameters:** |
111 | | - - `key (bytes)`: 128-bit AES key. |
112 | | - - `r (bytes)`: Random value used during encryption. |
113 | | - - `ciphertext (bytes)`: Encrypted text to decrypt. |
114 | | - |
115 | | -- **Returns:** |
116 | | - - `plaintext (bytes)`: The decrypted original message. |
117 | | - |
118 | | -### `generate_aes_key()` |
119 | | - |
120 | | -Generates a random 128-bit AES key. |
121 | | - |
122 | | -- **Returns:** |
123 | | - - `key (bytes)`: Randomly generated 128-bit key (16 bytes). |
124 | | - |
125 | | -### `sign_input_text(sender, addr, function_selector, ct, key)` |
126 | | - |
127 | | -Signs an input message composed of multiple parts, including sender address, contract address, function selector, and ciphertext. |
128 | | - |
129 | | -- **Parameters:** |
130 | | - - `sender (bytes)`: Sender address. |
131 | | - - `addr (bytes)`: Contract address. |
132 | | - - `function_selector (str)`: Ethereum function selector (in hex). |
133 | | - - `ct (bytes)`: Ciphertext (concatenated). |
134 | | - - `key (bytes)`: Private key for signing. |
135 | | - |
136 | | -- **Returns:** |
137 | | - - `signature (bytes)`: Digital signature of the message. |
138 | | - |
139 | | -### `sign(message, key)` |
140 | | - |
141 | | -Signs a `message` using the provided `key` (Ethereum-style private key). |
142 | | - |
143 | | -- **Parameters:** |
144 | | - - `message (bytes)`: Message to sign. |
145 | | - - `key (bytes)`: Private key to use for signing. |
146 | | - |
147 | | -- **Returns:** |
148 | | - - `signature (bytes)`: The generated signature. |
149 | | - |
150 | | -### `build_input_text(plaintext, user_aes_key, sender, contract, function_selector, signing_key)` |
151 | | - |
152 | | -Encrypts a plaintext integer and signs the resulting ciphertext along with other parameters. |
153 | | - |
154 | | -- **Parameters:** |
155 | | - - `plaintext (int)`: Integer to encrypt. |
156 | | - - `user_aes_key (bytes)`: AES key for encryption. |
157 | | - - `sender (object)`: Ethereum-like sender object (with `address` attribute). |
158 | | - - `contract (object)`: Ethereum-like contract object (with `address` attribute). |
159 | | - - `function_selector (str)`: Function selector (in hex). |
160 | | - - `signing_key (bytes)`: Signing key for signature. |
161 | | - |
162 | | -- **Returns:** |
163 | | - - `dict`: Contains the `ciphertext` and `signature`. |
164 | | - |
165 | | -### `build_string_input_text(plaintext, user_aes_key, sender, contract, function_selector, signing_key)` |
166 | | - |
167 | | -Encrypts and signs string-based input data, breaking it into 8-byte chunks. |
168 | | - |
169 | | -- **Parameters:** |
170 | | - - `plaintext (str)`: String to encrypt. |
171 | | - - `user_aes_key (bytes)`: AES key for encryption. |
172 | | - - `sender (object)`: Ethereum-like sender object. |
173 | | - - `contract (object)`: Ethereum-like contract object. |
174 | | - - `function_selector (str)`: Function selector (in hex). |
175 | | - - `signing_key (bytes)`: Signing key for signature. |
176 | | - |
177 | | -- **Returns:** |
178 | | - - `dict`: Contains the `ciphertext` and `signature`. |
179 | | - |
180 | | -### `decrypt_uint(ciphertext, user_key)` |
181 | | - |
182 | | -Decrypts a ciphertext into an unsigned integer using AES. |
183 | | - |
184 | | -- **Parameters:** |
185 | | - - `ciphertext (int)`: Ciphertext to decrypt (in integer format). |
186 | | - - `user_key (bytes)`: AES key to use for decryption. |
187 | | - |
188 | | -- **Returns:** |
189 | | - - `int`: The decrypted integer. |
190 | | - |
191 | | -### `decrypt_string(ciphertext, user_key)` |
192 | | - |
193 | | -Decrypts a ciphertext back into a string, handling multiple formats of ciphertext. |
194 | | - |
195 | | -- **Parameters:** |
196 | | - - `ciphertext (dict/tuple)`: Ciphertext to decrypt, can be in event or state variable format. |
197 | | - - `user_key (bytes)`: AES key to use for decryption. |
198 | | - |
199 | | -- **Returns:** |
200 | | - - `str`: The decrypted string. |
201 | | - |
202 | | -### `generate_rsa_keypair()` |
203 | | - |
204 | | -Generates an RSA key pair for encryption and decryption. |
205 | | - |
206 | | -- **Returns:** |
207 | | - - `private_key_bytes (bytes)`: Serialized private key. |
208 | | - - `public_key_bytes (bytes)`: Serialized public key. |
209 | | - |
210 | | -### `decrypt_rsa(private_key_bytes, ciphertext)` |
211 | | - |
212 | | -Decrypts a ciphertext using RSA and a provided private key. |
213 | | - |
214 | | -- **Parameters:** |
215 | | - - `private_key_bytes (bytes)`: Private key used for decryption. |
216 | | - - `ciphertext (bytes)`: Ciphertext to decrypt. |
217 | | - |
218 | | -- **Returns:** |
219 | | - - `plaintext (bytes)`: Decrypted plaintext. |
220 | | - |
221 | | - |
222 | | -# Web3 Utilities (utils.py) |
223 | | -## Functions |
224 | | - |
225 | | -### `web3_connected(web3)` |
226 | | - |
227 | | -Checks if the Web3 instance is connected to the blockchain node. |
228 | | - |
229 | | -- **Parameters:** |
230 | | - - `web3 (Web3)`: Web3 instance. |
231 | | - |
232 | | -- **Returns:** |
233 | | - - `bool`: `True` if connected, otherwise `False`. |
234 | | - |
235 | | -### `print_network_details(web3)` |
236 | | - |
237 | | -Prints details about the connected network, such as the provider, chain ID, and the latest block hash. |
238 | | - |
239 | | -- **Parameters:** |
240 | | - - `web3 (Web3)`: Web3 instance. |
241 | | - |
242 | | -### `print_account_details(web3)` |
243 | | - |
244 | | -Prints details about the default account, including its address, balance in Wei and Ether, and the account nonce. |
245 | | - |
246 | | -- **Parameters:** |
247 | | - - `web3 (Web3)`: Web3 instance. |
248 | | - |
249 | | -### `init_web3(node_https_address, eoa, error_not_connected=True)` |
250 | | - |
251 | | -Initializes the Web3 instance and sets up the default account. It also injects the Geth POA middleware for POA chains. |
252 | | - |
253 | | -- **Parameters:** |
254 | | - - `node_https_address (str)`: The Ethereum node's HTTPS address. |
255 | | - - `eoa (eth_account.Account)`: The account to set as the default. |
256 | | - - `error_not_connected (bool)`: If `True`, raises an error if the connection fails. |
257 | | - |
258 | | -- **Returns:** |
259 | | - - `web3 (Web3)`: Initialized Web3 instance. |
260 | | - |
261 | | -### `get_eoa(account_private_key)` |
262 | | - |
263 | | -Creates an externally owned account (EOA) from a private key. |
264 | | - |
265 | | -- **Parameters:** |
266 | | - - `account_private_key (str)`: The private key for the account. |
267 | | - |
268 | | -- **Returns:** |
269 | | - - `eoa (eth_account.Account)`: The Ethereum account object. |
270 | | - |
271 | | -### `validate_address(address)` |
272 | | - |
273 | | -Validates if the given address is a valid Ethereum address and returns the checksum version of the address. |
274 | | - |
275 | | -- **Parameters:** |
276 | | - - `address (str)`: The Ethereum address. |
277 | | - |
278 | | -- **Returns:** |
279 | | - - `dict`: Contains `valid` (boolean) and `safe` (checksum address). |
280 | | - |
281 | | -### `get_latest_block(web3)` |
282 | | - |
283 | | -Retrieves the latest block on the blockchain. |
284 | | - |
285 | | -- **Parameters:** |
286 | | - - `web3 (Web3)`: Web3 instance. |
287 | | - |
288 | | -- **Returns:** |
289 | | - - `block (dict)`: The latest block. |
290 | | - |
291 | | -### `get_nonce(web3)` |
292 | | - |
293 | | -Retrieves the nonce (transaction count) for the default account. |
294 | | - |
295 | | -- **Parameters:** |
296 | | - - `web3 (Web3)`: Web3 instance. |
297 | | - |
298 | | -- **Returns:** |
299 | | - - `int`: The transaction count (nonce). |
300 | | - |
301 | | -### `get_native_balance(web3, address=None)` |
302 | | - |
303 | | -Gets the native token balance (e.g., Ether) for a given address or the default account. |
304 | | - |
305 | | -- **Parameters:** |
306 | | - - `web3 (Web3)`: Web3 instance. |
307 | | - - `address (str, optional)`: The Ethereum address. Defaults to the default account. |
308 | | - |
309 | | -- **Returns:** |
310 | | - - `int`: The balance in Wei. |
311 | | - |
312 | | -### `load_contract(file_path)` |
313 | | - |
314 | | -Loads a Solidity contract source code from a file. |
315 | | - |
316 | | -- **Parameters:** |
317 | | - - `file_path (str)`: Path to the Solidity contract file. |
318 | | - |
319 | | -- **Returns:** |
320 | | - - `str`: The contract source code. |
321 | | - |
322 | | -### `transfer_native(web3, recipient_address, private_key, amount_to_transfer_ether, native_gas_units)` |
323 | | - |
324 | | -Transfers the native token (e.g., Ether) from the default account to a recipient address. |
325 | | - |
326 | | -- **Parameters:** |
327 | | - - `web3 (Web3)`: Web3 instance. |
328 | | - - `recipient_address (str)`: Address to send the Ether. |
329 | | - - `private_key (str)`: Private key of the sender. |
330 | | - - `amount_to_transfer_ether (float)`: Amount of Ether to transfer. |
331 | | - - `native_gas_units (int)`: Gas units to use for the transaction. |
332 | | - |
333 | | -- **Returns:** |
334 | | - - `dict`: Transaction receipt. |
335 | | - |
336 | | -### `deploy_contract(contract, kwargs, tx_params)` |
337 | | - |
338 | | -Deploys a smart contract with the given constructor arguments and transaction parameters. |
339 | | - |
340 | | -- **Parameters:** |
341 | | - - `contract (Contract)`: Web3 contract instance. |
342 | | - - `kwargs (dict)`: Constructor arguments for the contract. |
343 | | - - `tx_params (dict)`: Transaction parameters including gas limit, gas price, and private key. |
344 | | - |
345 | | -- **Returns:** |
346 | | - - `dict`: Transaction receipt. |
347 | | - |
348 | | -### `exec_func_via_transaction(func, tx_params)` |
349 | | - |
350 | | -Executes a contract function via a transaction. |
351 | | - |
352 | | -- **Parameters:** |
353 | | - - `func (ContractFunction)`: Contract function to execute. |
354 | | - - `tx_params (dict)`: Transaction parameters including gas limit, gas price, and private key. |
355 | | - |
356 | | -- **Returns:** |
357 | | - - `dict`: Transaction receipt. |
358 | | - |
359 | | -### `sign_and_send_tx(web3, private_key, transaction)` |
360 | | - |
361 | | -Signs a transaction with the provided private key and sends it to the blockchain. |
362 | | - |
363 | | -- **Parameters:** |
364 | | - - `web3 (Web3)`: Web3 instance. |
365 | | - - `private_key (str)`: Private key to sign the transaction. |
366 | | - - `transaction (dict)`: Transaction details. |
367 | | - |
368 | | -- **Returns:** |
369 | | - - `dict`: Transaction receipt. |
| 23 | +--- |
370 | 24 |
|
371 | | -#### To report issues, please create a [github issue](https://github.com/coti-io/coti-sdk-python/issues) |
| 25 | +To report an issue, please see the [issues](https://github.com/coti-io/coti-eth-account/issues/new) tab. |
0 commit comments