@dydxprotocol/v4-abacus

dYdX Chain Abacus

Shared front-end and mobile logic written in Kotlin Multiplatform (https://kotlinlang.org/docs/multiplatform.html).

The library generates Swift framework for iOS, JVM library for Android, and Javascript code for Web.

Install Java 11

https://www.oracle.com/java/technologies/downloads/#java11

Documentation

API Documentation

iOS

Abacus uses Cocoapods to integrate with iOS project. The gradle configuration contains the steps needed to generate the .podspec file. Run

./gradlew podspec

to generate abacus.podspec. Configure your iOS project (https://github.com/dydxprotocol/native-ios) to import abacus.podspec.

You can also build the Abacus for iOS by running:

./gradlew assembleXCFramework

This generates the iOS framework in build/XCFrameworks folder.

Debugging on iOS directly from XCode is possible with a plugin (https://github.com/touchlab/xcode-kotlin)

Android

Abacus builds and pushes the JVM target as a Github package with the following command:

./publish_android.sh

The Android app (https://github.com/dydxprotocol/native-android) has the Gradle build step to pull the Abacus target from GithubPackage.

v4-web

If you are using v4-abacus with the v4-web repo, follow local development instructions here.

Other JavaScript / TypeScript

Abacus generates a Javascript / Typescript UMD module with the following command:

./gradlew assembleJsPackage

This outputs into build/packages/js.

A local npm package can be built with:

./gradlew packJsPackage

A tarball of the package should be created in build/packages and you can install it to your project for local testing:

npm install PATH_TO_TARBALL

Publishing to NPM

Abacus is published to an npm library (https://www.npmjs.com/package/@dydxprotocol/v4-abacus).

Unit Tests

Shared code should have unit tests written in Kotlin residing in the src/CommonTest directory. Run the tests with the following command

./gradlew jvmtest

Integration Tests

Integration tests can be written to call Abacus from non-Kotlin code (i.e., Swift, JS). Sample integration projects can be found in the integration directory.

Version Bump

./bump_version.sh

Auto-lint

Enable pre-commit to auto-lint/auto-format your changes before git commit:

brew install pre-commit pre-commit install

How to use

// create a state machine
val stateMachine = PerpTradingStateMachine()

// send socket payload to the state machine and get the state
// the param is the complete socket text
val state = stateMachine.socket(payloadText)

// See src/commonTest/kotlin/exchange.dydx.abacus/PerpV3Tests.kt for testing code

Structure

Misc:

• Utils
• Protocols

state (top state)

• app -> AppStateMachine (contains network logic)
• modal -> StateMachine (contains business logic)
• changes -> Changes (utilities to identify which part of the state has changed)

processing:

step 1: processor (dynamic objects - dictionaries, list, not typed)

• markets
  • orderbook
  • trades
  • funding
• asset (referenced from markets, such as icon, url etc)
• wallet (user info)
  • account
    • subaccount
      • assetPositions
      • openPositions
      • orders
      • fills
      • transfers
      • historicalPnl
• configs (from Veronica mostly)

step 2 calculator (dynamic)

• market (summary info)
• account (step 3)
  • subaccount
    • 3.1 calculate positon notionalTotal/valueTotal etc
    • 3.2 calculate account equity etc, leverage, margin usage, buyingpower
    • 3.3 calcualte position levereage, buyingpower
• account transformer (step 2)
  • calculate postOrder and postAllOrderStates for account (total from trade input) and positions (size from trade input)
• input (step 1)
  • trade input
    • size (size, usdcSize, leverage)
  • transfer input (not complete)

step 3 validator (from postOrder and postAllOrders states)

• trade
• transfer

step 4 output (structs, typed data)

• converts dynamic data to typed

step 5 responses

• Construct response object from output

CommonTest

test (supporting classes, mostly mocks) utils (just utilities)

AppStateMachine (app)

• StateMachine (payload and validation folder)

payload (test StateMachine payload and interaction)

• API -> expected state validation (separated from payload, to target validation tests)

app (test AppStateMachine IO requests)