Skip to main content

Container Operate

Icon​

ContainerOperate_image1.png

Function​

The Container Operate component manages the contents - either resources or entities - within containers.

Key Points​

Suggestion

The Container Operate component should be used in conjunction with Containers(data components) and Container Operate Connectors. These concepts can be better understood when considered together. It's recommended that you first read the Containers chapter to fully understand the concept of resources.

Understanding and Applying​

  • They can express the outflow/consumption/payment and inflow/production/income of producible and consumable resources.
Examples
  • In a game, a farmer stores harvested grain in a warehouse, where the grain is the resource and the warehouse is the resource container. Storing the grain represents the operation of adding resources to the container.
  • In the DeFi field, users utilize their EOA wallets to engage with a DEX to swap 3000 USDC for 1 ETH. In this transaction, assets like USDC and ETH act as resources, while both the users' wallets, which record an outflow of USDC and an inflow of ETH, and the DEX liquidity pools, which record an outflow of ETH and an inflow of USDC, act as containers. This exchange process illustrates how a container operation occurs.
  • They can also express the request and release of reusable resources.
Example
  • When a car enters the parking lot, it essentially "requests" a parking space. Once obtained, the car can enter. When leaving, it "releases" the parking space. In this case, the parking lot is the resource container, the parking space is the resource, and requesting and releasing represent resource operations.
Tip: Container Operate in DeFi

In DeFi modeling, we usually view various ERC20 tokens as resources and user wallets and DEX liquidity pools as resource containers. This allows us to easily manage the various token balances of EOA account addresses and smart contract addresses, rather than completely copying the ERC20 global ledger mode, thereby achieving convenient transaction simulation and a more intuitive understanding of the system's fundamental mechanisms.

Graphic Modeling Syntax​

  • The Container Operate component is connected to other components through a Sequence Connector within a process.

  • You can connect it to the Containers with a Container Operate Connector. The Container Operate Connector is unidirectional, with different directions representing inflow and outflow of resources.

    ContainerOperate_image2.png

Tips for Reading Models More Effectively

The Container Operate component activates only when the process trigger reaches it. To avoid confusion, we recommend a specific reading order.

Start by following the Sequence Connector to understand the main logic of the entire process. Then, focus on the details of the Container Operate. This method, often called "read the trunk first, then the branches", helps prevent confusion arising from the simultaneous presence of multiple processes and components.

  • Each Container Operate Connector can only connect to one container, but multiple Connectors can be connected to one Container Operate component.

The Container Operate component has no output data.​

Mechanism of Resource Operations​

Note

Operations on resource containers are referred to as resource operations.

Basic​

  • Operations on containers are carried out separately based on their names (the keys of the container), and they are independent of each other.
  • The basic information for resource operations includes:
    • Direction
      • It comes from the Container Operate Connector. When the Container Operate Connector points from the Container Operate component to the Container, it represents putting resources into the Container; the opposite represents getting them out of the Container.
    • Type and Amount of Resources
      • It comes from the settings on the Container Operate Connector properties panel.
    • Whether it is an exchange mode
      • According to the exchange mode setting of the resource operation object.
    • Properties and States of the Container
      • A Container's properties and current state are defined by its settings. These include the types of resources it can store, its initial amount, capacity limit, and whether or not the initial amount can hold a negative value.
    • Operation Exceptions
      • The method for catching operation failures is determined by the Boundary Event settings associated with the resource operation.
Model Example 1

In the Container Resource 1, the initial amount of resource a is 10, and 1 is taken out at each Tick. After a total of 10 Ticks, the remaining resource a is 0.

Influence of Container Properties on Operations​

  • Container Capacity Limit

    Since the container can set an upper limit on capacity, if the amount of resources put into it exceeds the capacity limit during simulation operation, a running error will be triggered immediately, and it will not wait for capacity to be freed up.

  • Negative Resource Balances

    When a resource container is set to disallow negative balances, a running error will be triggered immediately if the amount of resources taken out is insufficient during a simulation run. The system will not wait for resource balance to recover enough.

Boundary Events​

Operations on containers are not always successful. Problems like insufficient withdrawals, reaching capacity limits, and errors in handling the amount and type of resources can result in failures. Setting a Boundary Event for the Container Operate component is an effective way to establish a response mechanism for these operational challenges.

  • Error Boundary Events

    It is equivalent to setting a failure coping mechanism. Once the operation fails, the Trigger will immediately flow to the subsequent objects of the boundary event.

  • Timer Boundary Events

    It is equivalent to setting a waiting mechanism. The waiting time t depends on the settings of the Boundary Event. When an operation abnormality occurs (such as exceeding the upper limit for placement, insufficient extraction, etc.), the Trigger will temporarily pile up and wait for a maximum of t time. During the waiting period, if the operation conditions are met (such as enough capacity has been freed up or resource storage has recovered enough), the Trigger will normally flow to the subsequent objects of this container operation; if the operation conditions are not met after waiting for t time, the Trigger will flow to the subsequent objects of the boundary event.

Model Example 2
  • Based on model example 1 (where the container is set to disallow negative balances), if we extend the total number of model runs to 20 Ticks, then the resource a of Resource1 will be exhausted after the 10th Tick. Any subsequent attempts to withdraw resource a from the container will result in an error.
  • By adding an error boundary event to this Container Operate component for the "not enough" issue, any withdrawal operations after the 10th Tick without sufficient resources will trigger the error boundary. This prevents the run from being interrupted by errors. Consequently, the a resource remains at 0, and the GetNone variable records 10 instances of insufficient withdrawal.
Tips

Direct modifications to the resource quantity in a container do not trigger boundary events.

For instance, if a container with a timer boundary event attempts to withdraw a resource but lacks sufficient quantity, even if a formula updates the resource amount to sufficient during the delay period, the withdrawal operation will not be executed immediately. The condition for the withdrawal will only be evaluated when another operation occurs on the container, at which point the system will check if the withdrawal can now proceed.

Regarding Exchange​

  • Multi-resource "Conservation" Operation

    • The essence of exchange is that multiple participants give certain resources and receive other resources at the same time.
    • For example, during commodity trading, the buyer pays the seller currency and receives a certain amount of goods from the seller at the same time. The total amount of various resources received and paid by the exchange parties is "conserved".

  • When a resource Container Operate component is connected to 2 or more operation Connectors of different directions, you can choose the "exchange" mode, which will strictly ensure that the resources are "conserved" during the operation.

  • The system provides a convenient mechanism to ensure that the exchange is completely conserved, and you need to turn on the switch on the component.

  • In a conserved exchange involving multiple resources, for any specific resource, if there are n operations, after defining the quantities for n-1 operations, the quantity of the last operation can be left blank by default as "Auto", and the system will strictly keep the exchange resources conserved.

    ContainerOperate_image3.png

  • You can also customize all n operations, and the system will check whether the quantities of each resource set are conserved during operation. If they are not conserved, the system will report an error.

Tip
  • As Container Operate components are suitable for expressing exchange scenarios, they are widely used in Web3 field simulation modeling.
Model Example 3

User A's wallet WalletA and the trading pool Pool exchange USDC and ETH tokens at a price of 3000. With an initial principal of 10000 USDC in WalletA, after purchasing 3 times and buying 1 ETH each time, WalletA will own 3 ETH and a remaining principal of 1000 USDC. This is a conservative exchange.

  • Of course, in the case of multiple Container Operate Connectors and multi-directional connections, you can also choose a non-exchange mode. In this case, the system conservation mechanism will not intervene, and it only expresses several operations at the same time.

Simultaneous Validity of Operations​

  • When a Container Operate component is connected to multiple Container Operate Connectors, each Connector corresponding operation must succeed before the Trigger will continue to flow backward.
  • If there is no boundary event, the failure of any operation will cause all operations to fail and report an error to terminate the operation.
  • If there are boundary events, once the boundary event is triggered, all operations on the Container Operate Connectors are invalid.

Usage and Setting Methods​

The Container Operate component has only one setting: Exchange mode. All other settings are for general Compute Before or After Action.

ContainerOperate_image4.png

Exchange Toggle Switch​

  • When exchange scenario conditions are not met, the switch remains in the off position and cannot be configured.
  • When exchange scenario conditions are met, the exchange mode switch can be configured, allowing the user to decide whether to turn it on or off.
Tips

The term "meeting exchange scenario conditions" refers to situations where the resource Container Operate component is connected to two or more Container Operate Connectors with different directions.

This implies that if there is only one Connector, or multiple Connectors in the same direction, an exchange is not possible.

The conservative exchange mode specifically includes two situations:

  • Resource Transfer: This occurs when there are two operations involving the same resource type in different directions. This is similar to System Dynamics, as demonstrated in Model Example 4.
  • Exchange: This occurs when there are two or more resource types involved, with two or more operations and different directions, as shown in Model Example 3.
Model Example 4

In this example, the WETH resource is transferred from one container, Stock1, to another, Stock2.