# Renegade Python SDK
The Renegade Python SDK is a client library for interacting with the [Renegade](https://renegade.fi/) darkpool.
## Installation
```bash
uv add renegade-sdk
```
or
```bash
pip install renegade-sdk
```
# Usage
See [`examples/`](examples/) for usage examples.
## Basic Use
Todo...
## External Matches
In addition to the standard darkpool flow -- deposit, place order, receive a match, then withdraw -- Renegade also supports *external* matches. An external match is a match between an internal party -- with state committed into the darkpool -- and an external party, with no state in the darkpool. Importantly, external matches are settled atomically; that is, the deposit, place order, match, withdraw flow is emulated in a _single transaction_ for the external party.
An external match is generated and submitted on-chain by a client (see `ExternalMatchClient`). The client submits an `ExternalOrder` to the relayer to fetch a quote, and the relayer will attempt to match it against all consenting internal orders. If a match is found, the relayer will respond to the client with a quote containing:
- The match itself, specifying the amount and mint (ERC20 address) of the tokens bought and sold, fees, etc.
- A signature of the quote; which allows the client to authoritatively assemble the quote into a match bundle
If the client is satisfied with the quote, it can assemble the quote into a match bundle, which contains:
- The match itself, specifying the amount and mint (ERC20 address) of the tokens bought and sold
- An EVM transaction that the external party may submit in order to settle the match with the darkpool
The client should then submit this match to the darkpool.
Upon receiving an external match, the darkpool contract will update the encrypted state of the internal party, and fulfill obligations to the external party directly through ERC20 transfers. As such, the external party must approve the token they _sell_ before the external match can be settled.
### Example
The following snippet demonstrates how to request an external match, assemble the quote into a match bundle, and submit the bundle to the darkpool. See [`examples/external_match.py`](examples/external_match.py) for a complete example.
```python
from renegade import ExternalMatchClient
from renegade.types import AtomicMatchApiBundle, OrderSide, ExternalOrder
# Constants
BASE_MINT = "0xc3414a7ef14aaaa9c4522dfc00a4e66e74e9c25a" # Testnet wETH
QUOTE_MINT = "0xdf8d259c04020562717557f2b5a3cf28e92707d1" # Testnet USDC
# Create the client
api_key = os.getenv("EXTERNAL_MATCH_KEY")
api_secret = os.getenv("EXTERNAL_MATCH_SECRET")
client = ExternalMatchClient.new_sepolia_client(api_key, api_secret)
# Create the order
order = ExternalOrder(
base_mint=BASE_MINT,
quote_mint=QUOTE_MINT,
side=OrderSide.SELL,
quote_amount=30_000_000, # $30 USDC
min_fill_size=3_000_000, # $3 USDC minimum
)
# Fetch a quote from the relayer
print("Fetching quote...")
quote = await client.request_quote(order)
if not quote:
raise ValueError("No quote found")
# Assemble the quote into a bundle
print("Assembling quote...")
bundle = await client.assemble_quote(quote)
if not bundle:
raise ValueError("No bundle found")
print(f"Received bundle: {bundle}")
```
### Bundle Details
The *quote* returned by the relayer for an external match has the following structure:
- `order`: The original external order
- `match_result`: The result of the match, including:
- `fees`: The fees for the match
- `relayer_fee`: The fee paid to the relayer
- `protocol_fee`: The fee paid to the protocol
- `receive`: The asset transfer the external party will receive, *after fees are deducted*.
- `mint`: The token address
- `amount`: The amount to receive
- `send`: The asset transfer the external party needs to send. No fees are charged on the send transfer. (same fields as `receive`)
- `price`: The price used for the match
- `timestamp`: The timestamp of the quote
When assembled into a bundle (returned from `assemble_quote` or `request_external_match`), the structure is as follows:
- `match_result`: The final match result
- `fees`: The fees to be paid
- `receive`: The asset transfer the external party will receive
- `send`: The asset transfer the external party needs to send
- `settlement_tx`: The transaction to submit on-chain
- `tx_type`: The transaction type
- `to`: The contract address
- `data`: The calldata
- `value`: The ETH value to send
See example [`examples/quote_validation.py`](examples/quote_validation.py) for an example of using these fields to validate a quote before submitting it.
This can be run with
```bash
uv run examples/quote_validation.py
```
### Supported Tokens
The tokens supported by the darkpool can be found at the following links:
- [Testnet](https://github.com/renegade-fi/token-mappings/blob/main/testnet.json)
- [Mainnet](https://github.com/renegade-fi/token-mappings/blob/main/mainnet.json)
Raw data
{
"_id": null,
"home_page": null,
"name": "renegade-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "arbitrum, blockchain, darkpool, defi, mpc, zero-knowledge",
"author": null,
"author_email": "Renegade <joey@renegade.fi>",
"download_url": "https://files.pythonhosted.org/packages/52/64/9ed6d6ca1f1bd8bb36b9ea36ccd9844029189c2a60e2a9fd2e3dff6897d8/renegade_sdk-0.1.1.tar.gz",
"platform": null,
"description": "# Renegade Python SDK\nThe Renegade Python SDK is a client library for interacting with the [Renegade](https://renegade.fi/) darkpool.\n\n## Installation\n```bash\nuv add renegade-sdk\n```\nor\n```bash\npip install renegade-sdk\n```\n\n# Usage\nSee [`examples/`](examples/) for usage examples.\n\n## Basic Use\nTodo... \n\n## External Matches\nIn addition to the standard darkpool flow -- deposit, place order, receive a match, then withdraw -- Renegade also supports *external* matches. An external match is a match between an internal party -- with state committed into the darkpool -- and an external party, with no state in the darkpool. Importantly, external matches are settled atomically; that is, the deposit, place order, match, withdraw flow is emulated in a _single transaction_ for the external party.\n\nAn external match is generated and submitted on-chain by a client (see `ExternalMatchClient`). The client submits an `ExternalOrder` to the relayer to fetch a quote, and the relayer will attempt to match it against all consenting internal orders. If a match is found, the relayer will respond to the client with a quote containing:\n- The match itself, specifying the amount and mint (ERC20 address) of the tokens bought and sold, fees, etc.\n- A signature of the quote; which allows the client to authoritatively assemble the quote into a match bundle\n\nIf the client is satisfied with the quote, it can assemble the quote into a match bundle, which contains:\n- The match itself, specifying the amount and mint (ERC20 address) of the tokens bought and sold\n- An EVM transaction that the external party may submit in order to settle the match with the darkpool\n\nThe client should then submit this match to the darkpool.\n\nUpon receiving an external match, the darkpool contract will update the encrypted state of the internal party, and fulfill obligations to the external party directly through ERC20 transfers. As such, the external party must approve the token they _sell_ before the external match can be settled.\n\n### Example\nThe following snippet demonstrates how to request an external match, assemble the quote into a match bundle, and submit the bundle to the darkpool. See [`examples/external_match.py`](examples/external_match.py) for a complete example.\n```python\nfrom renegade import ExternalMatchClient\nfrom renegade.types import AtomicMatchApiBundle, OrderSide, ExternalOrder\n\n# Constants\nBASE_MINT = \"0xc3414a7ef14aaaa9c4522dfc00a4e66e74e9c25a\" # Testnet wETH\nQUOTE_MINT = \"0xdf8d259c04020562717557f2b5a3cf28e92707d1\" # Testnet USDC\n\n# Create the client\napi_key = os.getenv(\"EXTERNAL_MATCH_KEY\")\napi_secret = os.getenv(\"EXTERNAL_MATCH_SECRET\")\nclient = ExternalMatchClient.new_sepolia_client(api_key, api_secret)\n\n# Create the order\norder = ExternalOrder(\n base_mint=BASE_MINT,\n quote_mint=QUOTE_MINT,\n side=OrderSide.SELL,\n quote_amount=30_000_000, # $30 USDC\n min_fill_size=3_000_000, # $3 USDC minimum\n)\n\n# Fetch a quote from the relayer\nprint(\"Fetching quote...\")\nquote = await client.request_quote(order)\nif not quote:\n raise ValueError(\"No quote found\")\n\n# Assemble the quote into a bundle\nprint(\"Assembling quote...\")\nbundle = await client.assemble_quote(quote)\nif not bundle:\n raise ValueError(\"No bundle found\")\n\nprint(f\"Received bundle: {bundle}\")\n```\n\n### Bundle Details\nThe *quote* returned by the relayer for an external match has the following structure:\n- `order`: The original external order\n- `match_result`: The result of the match, including:\n- `fees`: The fees for the match\n - `relayer_fee`: The fee paid to the relayer\n - `protocol_fee`: The fee paid to the protocol\n- `receive`: The asset transfer the external party will receive, *after fees are deducted*.\n - `mint`: The token address\n - `amount`: The amount to receive\n- `send`: The asset transfer the external party needs to send. No fees are charged on the send transfer. (same fields as `receive`)\n- `price`: The price used for the match\n- `timestamp`: The timestamp of the quote\n\nWhen assembled into a bundle (returned from `assemble_quote` or `request_external_match`), the structure is as follows:\n- `match_result`: The final match result\n- `fees`: The fees to be paid\n- `receive`: The asset transfer the external party will receive\n- `send`: The asset transfer the external party needs to send\n- `settlement_tx`: The transaction to submit on-chain\n - `tx_type`: The transaction type\n - `to`: The contract address\n - `data`: The calldata\n - `value`: The ETH value to send\n\nSee example [`examples/quote_validation.py`](examples/quote_validation.py) for an example of using these fields to validate a quote before submitting it.\n\nThis can be run with\n```bash\nuv run examples/quote_validation.py\n```\n\n### Supported Tokens\nThe tokens supported by the darkpool can be found at the following links:\n- [Testnet](https://github.com/renegade-fi/token-mappings/blob/main/testnet.json)\n- [Mainnet](https://github.com/renegade-fi/token-mappings/blob/main/mainnet.json)",
"bugtrack_url": null,
"license": null,
"summary": "Python SDK for Renegade darkpool",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://docs.renegade.fi",
"Homepage": "https://github.com/renegade-fi/renegade-sdk"
},
"split_keywords": [
"arbitrum",
" blockchain",
" darkpool",
" defi",
" mpc",
" zero-knowledge"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "190fcba197d0f625cef09f037ff0db0cd48ec001f1fb3f91a3445d07b9ff473a",
"md5": "3d8696cd4e8f5a2a085ab4e335c008f5",
"sha256": "52d1dd6477888ee84acc847eda47f499d1755958d7fb292b284909f18763e8c8"
},
"downloads": -1,
"filename": "renegade_sdk-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3d8696cd4e8f5a2a085ab4e335c008f5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 12418,
"upload_time": "2024-12-18T23:08:21",
"upload_time_iso_8601": "2024-12-18T23:08:21.506832Z",
"url": "https://files.pythonhosted.org/packages/19/0f/cba197d0f625cef09f037ff0db0cd48ec001f1fb3f91a3445d07b9ff473a/renegade_sdk-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "52649ed6d6ca1f1bd8bb36b9ea36ccd9844029189c2a60e2a9fd2e3dff6897d8",
"md5": "20f901ccbeb414557214b297d0bdd6f3",
"sha256": "83196e1155398a061b6ea7bcc5fe5df4f765a55f805c1aaf06e99d49acf0fb49"
},
"downloads": -1,
"filename": "renegade_sdk-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "20f901ccbeb414557214b297d0bdd6f3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 13934,
"upload_time": "2024-12-18T23:08:22",
"upload_time_iso_8601": "2024-12-18T23:08:22.618585Z",
"url": "https://files.pythonhosted.org/packages/52/64/9ed6d6ca1f1bd8bb36b9ea36ccd9844029189c2a60e2a9fd2e3dff6897d8/renegade_sdk-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-18 23:08:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "renegade-fi",
"github_project": "renegade-sdk",
"github_not_found": true,
"lcname": "renegade-sdk"
}
JSON
