@dydxprotocol/abacus

Abacus

Shared front-end and mobile logic written in Kotlin Multiplatform.

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 Documentations

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 to MavenLocal repo with the followinng command:

./gradlew publishToMavenLocal

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

Web

Abacus generates Javascript and Typescript files with the following command:

./gradlew assembleJsPackage

This outputs into build/distributions, and references the packages in the build/js directory.

Sample integration from a html page can be find in integration/Web.

Publishing to NPM

Abacus publishes using a library (https://github.com/mpetuska/npm-publish) with the following steps.

1. replace the 'obfuscated' with an npm API_KEY (todo: automate this / hide key) and bump version

2. ./gradlew assembleJsPackage
   

3. ./gradlew packJsPackage
   

4. ./gradlew publishJsPackageToNpmjsRegistry
   

5. Check published version (https://www.npmjs.com/package/@dydxprotocol/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 test

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

1. Update the version in build.gradle.kts
2. Run sh update_version.command - Update the version in abacus.podspec
3. in Xcode, open {project}/integraiton/iOS/abacus.ios.xcworkspace. Build and run.
4. The integration app doesn't have any UI to indicate the connections. Use Charles to check network traffic. It should contain the standard initial connections to 1. wss://api.dydx.exchange/v3/ws, with subscriptions to "v3_markets", "v3_trades", and "v3_orderbook" 2. https://api.dydx.exchange/v3/config

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 position notionalTotal/valueTotal etc 3.2 calculate account equity etc, leverage``, marginUsage, buyingPower3.3 calculate positionleverage, buyingPower`
  • AccountTransformer (step 2)
    • calculate postOrder and postAllOrderStates for account (total from trade input) and positions (size from trade input)
  • input (step 1)
    • TradeInput
      • size (size, usdcSize, leverage)
    • TransferInput (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)