kurosawa_akira

KO | EN

gitlite — search

#python #ai #typescript #llm #golang #rust #linux #java #windows #awesome #cli #kubernetes #pytorch #ios

(★ 13)

Set of smart contracts on StarkNet for Akira Decentralised Exchange

kurosawa_akira Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# kurosawa
Set of smart contracts on starkent for Akira dex exchange

# AccesorableLogicComponent

Manages ownership, executor roles, and user-delegated permissions. 
Supports secure ownership transfer, executor assignment with epoch validation, and user-to-executor delegation, 
ensuring outdated access is prevented using an epoch counter.

Emits events like OwnerChanged, ExecutorChanged, GlobalEpoch and ApprovalGranted for seamless integration with monitoring systems. 
Built-in methods enforce strict access control for the owner, executors, or both, ensuring reliable permission management.

Assumes the executor's contract logic cannot be upgraded without modifying its contract address

# ExchangeBalanceLogicComponent
This component supports efficient balance management across multiple tokens and users and is designed to integrate seamlessly with exchange-related smart contracts.

It facilitates minting, burning, transferring, and rebalancing token balances during trades while ensuring proper validation and event emission for tracking state changes.

# DepositComponent

The DepositComponent provides functionality for securely handling token deposits into a smart contract that integrates with the ExchangeBalanceLogicComponent. 
It facilitates token transfers from users to the contract, updates internal balances, and emits deposit-related events.

The deposit method must be called with sufficient ERC20 approval granted by the user prior to invoking the method.

The deposit_s method functions similarly to deposit, but the recipient is automatically set to the contract invoker (the caller).

The protected method non_atomic_deposit allows deposits to be performed non-atomically:
   a client can first execute an ERC20.transfer and then invoke this method. 
Additionally, it provides a mechanism to rescue client funds in case they mistakenly 
transfer ERC20 tokens directly to the contract without explicitly calling the deposit methods.

# WithdrawComponent
The WithdrawComponent provides functionality for securely handling token withdrawals in a smart contract that integrates with the ExchangeBalanceLogicComponent. 
It supports both on-chain and off-chain withdrawals with robust validation, delay enforcement, and gas fee management.

To mitigate issues with on-chain withdrawals impacting the depth book and execution state, delays in terms of block numbers and timestamps are enforced.
Upon contract creation, the delay is set to the maximum permissible value and can only be adjusted to reduce it. 
When a client invokes an on-chain withdrawal, a ReqOnChainWithdraw event is emitted, whenever actual withdrawal happened Withdrawal event is emitted.

The apply_withdraw method allows the exchange to immediately process on-chain withdrawals, bypassing the enforced delays. 
In return, the client covers the gas fees associated with the operation.

Additionally, clients can perform off-chain withdrawals, which do not incur any delays, as they are executed directly by the exchange.

The protected method safe_withdraw exists to securely return funds to the client after a trade. 
This method ensures that the contract does not have direct control over token burning, maintaining transparency and security.

# NonceComponent

The NonceComponent provides functionality for securely managing traders' nonces in a smart contract that integrates with ExchangeBalanceLogicComponent. 
It supports off-chain and on-chain nonce updates, ensuring proper validation, signature checks, and event emission.

# SignerComponent
The SignerLogicComponent provides functionality for managing signer bindings and validating signatures for traders within a smart contract. 
It supports multiple signing schemes, expiration-based approvals, and integration with external signature verifiers. 
This component is critical for securely managing both off-chain and on-chain signature-based operations.
### Default signing Schemes
Clients have access to the following signing schemes by default:

* Account: This scheme succeeds if the account.is_valid_signature method returns 'VALID'. It uses the standard signature validation implemented in the trader's account.
* ECDSA Curve: This scheme succeeds if the ECDSA signature, generated by the signer bound to the trader's trading account in the contract, is correct. Traders must explicitly bind a signer to their trading account using the bind_to_signer contract method to enable this scheme.
* Direct: This scheme succeeds if the trader's address matches the caller's address (trader == caller). It is useful for direct, self-executed operations.
### Custom signing schemes
The exchange can define additional signing schemes by registering external verifiers in the smart contract.
However, these schemes must be explicitly approved by each client (trader) before they can be used. 
Clients approve signing schemes by specifying an expiration period, ensuring the scheme is valid only for a limited time. 
This mechanism is implemented to enhance security and ensure that no unauthorized signing scheme can be used without the trader's consent.
### Security Considerations
* Explicit Approval: Custom signing schemes are inactive for a trader until explicitly approved. 
This ensures that traders have control over which schemes are allowed for their operations.
* Non-Upgradable Verifiers: External verifiers registered in the contract must not be upgradable. 
This ensures that the integrity of the verifier logic remains intact and prevents potential exploitation through unauthorized upgrades.

This approach ensures a robust, secure, and flexible mechanism for managing signatures and signing schemes, 
safeguarding the interests of both the exchange and its clients.

# LayerAkiraCore
The LayerAkiraCore contract is a modular smart contract designed to manage the core operations of a decentralized exchange. 
It integrates various components, including balance management, signer logic, deposit handling, withdrawal management, nonce tracking, and access control.

Clients must explicitly authorize the current executor in the smart contract to allow the exchange's executor contract 
to modify the state in the core contract related to the client's trading activities. 
This ensures that only approved executors can perform actions on behalf of the client, maintaining security and control over trading operations.

# BaseTradeComponent

The BaseTradeComponent is a critical module for managing trade execution and settlement within the LayerAkira ecosystem. 
It facilitates efficient handling of both ecosystem and external trades, enforces rigorous trade validation, and applies associated fees while maintaining security and transparency. 
This component seamlessly interact with the LayerAkiraCore and LayerAkiraExternalGrantor.

It provides two key internal methods for the executor contract:

* apply_ecosystem_trades: 
Enables the executor to match ecosystem takers with ecosystem makers. 
(Ecosystem refers to trades where funds originate from the LayerAkiraCore contract, and the signature scheme is rather deterministic.

* apply_single_taker: 
Allows the executor to match external and ecosystem takers with ecosystem makers.

### Fees and Gas Costs
* Gas Fees:
 Every trade incurs gas fees, which can be paid in the native STRK token or any other token specified in the order. 
The conversion rate for non-native tokens is provided by the user in the signed action.
* Exchange and Router, and integrator fees: 
Each trade includes exchange fees for both makers and takers, 
along with optional router fees and integrator fees. 
Routers act as intermediaries that relay client orders to the LayerAkira exchange (e.g., aggregators, frontends, or individual parties).
Integrators act as smth that built on top of routers. For example, router is aggregator service while integrator is a wallet.
### Handling External Trades

In the case of external trades, there is a possibility of trade failure due to malicious taker behavior. Instead of reverting the transaction, the contract:

* Marks the affected orders as filled to prevent re-execution of this amounts.
* Punishes the router for failing to validate the taker properly.
* Rewards the market maker (MM) and the exchange with a small amount of gas tokens to offset the opportunity loss.
* The fine is deducted from the router contract, minted to the core contract, and distributed between the MM and the exchange.

### apply_single_taker Specifics
The skip_taker_validation flag is set to true only when a client directly places an order into the exchange contract. 
In such cases, no further validation is necessary.
This ensures that the system remains efficient and secure, while providing flexibility for both ecosystem and external trades.

# SORLayerAkiraExecutor

The SORLayerAkiraExecutor (Smart Order Routing) module provides advanced trade execution capabilities for multi-step and snip-9 trades. 
It is designed to handle both atomic taker orders and multi-order routing scenarios, enabling efficient and secure order fulfillment.

This component extends the functionality of the BaseTradeComponent, integrating seamlessly with its trade execution logic while adding features specific to multi-step trades and snip-9.

### snip-9
* Client Multicall: Signed by the client, executed using executeoutside. The sequence of calls typically includes:
   * Approve
   * Additional approves...
   * placeTakerOrder

* Exchange multicall: 
  * Client multicall 
  * fullfillTakerOrder: 
    * Executes the locked taker order with the necessary maker orders and ensures completion.

Both the client multicall and fullfillTakerOrder are enforced to occur within the same transaction, maintained by a locking mechanism to ensure atomicity and prevent state conflicts.
Leverage of snip-9 allows to avoid separate approval from order signing

### Synthetic matching on LayerAkira

leverage snip-9 to allow atomic execution for multileg match (detailed explanation: https://github.com/LayerAkira/kurosawa_akira/pull/30)
* Client Multicall:
   * Approve
   * Additional approves...
   * placeSORTakerOrder

* Exchange multicall:
   * Client multcall
   * fulfillSORAtomic
     * Executes the locked taker order with the necessary maker orders and ensures completion.

# LayerAkiraExecutor

The LayerAkiraExecutor contract is designed to handle the execution layer of the LayerAkira decentralized exchange. 
It provides functionality to manage order execution, 
including both single and bulk trades, nonce updates, withdrawals, and ecosystem-based trade flows. 
The contract ensures security and efficiency through its integration with other core components like BaseTradeComponent.
Additionally provides matching primitives for settling trades for addons/extensions -- contracts that would extend funtionality like SORLayerAkiraExecutor.
Serves as an extension as well as bypassing contract size limitations in Starknet.

# LayerAkiraExternalGrantor

The LayerAkiraExternalGrantor contract is a core module responsible for managing router registrations, deposits, withdrawals, and their interactions with the LayerAkira executor and core contracts.
It ensures that routers maintain required balances to be able to route orders to exchange.

Note that transfer_to_core designed to avoid giving explicit access for executor contract to mint tokens in LayerAkiraCore

# General flow

Clients sign ofchain typed messages that represent trading actions and submit them to LayerAkira exchange (offchain matching engine).
Matching engine process events and publish results of actions into the smart contracts.

kurosawa_akira

kurosawa_akira Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

kurosawa_akira

kurosawa_akira Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README