States / Availability

Availability is the main state machine that powers String Theory. States are focused on modeling whether or not money is available to be used; operations like withdrawals and transfers are only permissible on available money.

This level of precision means that with String Theory you can be confident that your financial decisions are safe. Plus, precise availabilities encourage eagerly recording money movements rather than waiting for a “final” transaction, which improves financial accuracy and auditability. These properties combined allow you to build more complex business logic around money. With states, String Theory helps make your money work for you .

State Machine

State Descriptions

Note

As mentioned in amounts, knots can represent any type of asset, including non-monetary values; however, we will just refer to money in this section for ease of reading.

Available

The money represented by this knot is allowed to be withdrawn. This is similar to available balance in your bank account: it’s money that is in your account and free to be used.

Properties

1. Contributes to available balance
2. Can be withdrawn or transferred

Withdrawn

The money represented by this knot has been used. This is similar to your outbound transactions in your bank account: it’s money that has been spent. Withdrawn knots serve as a record of the money that moved through your account/system but is no longer there.

Properties

1. Does not contribute to available balance
2. Cannot be withdrawn or transferred
3. Can be returned to become available again

Pending Deposit

This knot represents money that you are expecting to enter your system, but has not cleared yet. This is similar to pending credits in your bank account: it’s money that is expected to be available soon. Pending deposit knots serve as a record of the money that is expected to move into your account/system.

Properties

1. Does not contribute to available balance
2. Cannot be withdrawn or transferred
3. Can be confirmed to become available
4. Can be canceled to mark a failure

Pending Withdrawal

This knot represents money that you are expecting to leave your system, but has not cleared yet. This is similar to pending debits in your bank account: it’s money that is expected to be gone soon. Pending withdrawal knots serve as a record of the money that is expected to move out of your account/system.

Properties

1. Does not contribute to available balance
2. Cannot be transferred
3. Can be confirmed to become withdrawn
4. Can be canceled to become available again

Pending Return

This knot represents money that you are expecting to re-enter your system, but is not available yet. This is similar to a pending deposit: it’s money that is expected to be available soon. Except, unlike a pending deposit which is new money, a pending return is money that the system already knows about but that was previously withdrawn.

Properties

1. Does not contribute to available balance
2. Cannot be transferred
3. Can be confirmed to become available
4. Can be canceled to become withdrawn again

Cancelled

This knot represents money that you were expecting to enter the system, but later found out would not arrive. This money is not available to be used. If it later turns out that it will arrive, you can restore it to the pending deposit state.

Properties

1. Does not contribute to available balance
2. Cannot be withdrawn or transferred
3. Can be restored to pending deposit

Adding New States

State management is fundamental to the system, and so these states are enforced on a fairly low level. This provides a lot of safety but also means adding new states is a non-trivial process. If your business needs to define additional states, we recommend using custom tags to be able to identify and operate on those states. If you feel strongly that you need to add new states to String Theory, please reach out to us and we’ll be happy to help you design a solution that works for your business.