Poseidon Signature Guide

This guide focuses on Poseidon Hashing and ECDSA Signature, integral components in the secure execution of Place Order operations on our DEX (Decentralized Exchange). Poseidon Hashing, a cryptographic hash function, minimizes complexity in generating and verifying zero-knowledge proofs, making it a fundamental element in our security architecture.

Poseidon Hashing

Construct Order Data

Prepare the order data, including relevant details such as trading pair, order type, quantity, price and vesselPublicKey.
Below is an example of how you can structure the order data, including all relevant details:

vesselPublicKey: Public key associated with Vessel. Please visit our website to get your Key.

takerFeeRate: Taker fee rate for the order. Retrieve this from our User Profile. If the fetched fee rates do not match the provided fee rates, an error is thrown when placing order.

makerFeeRate: Maker fee rate for the order.

timestamp: Unix timestamp in milliseconds when the order is placed.

clientOrderId: Unique identifier for the order, often generated based on timestamp.

buyAssetId: The asset you are acquiring in the trade.

sellAssetId: The asset you are using to make the purchase.

buyAssetAmount: Amount of the buy asset.

sellAssetAmount: Amount of the sell asset.

These data structure can be put into the following example of order data:

{
  "vesselPublicKey": "0xYourVesselPublicKey",
  "takerFeeRate": 2000,
  "makerFeeRate": 2000,
  "timestamp": 1644568800000,
  "clientOrderId": "uniqueOrderIdentifier",
  "buyAssetId": 4,
  "sellAssetId": 1,
  "buyAssetAmount": 18000000000,
  "sellAssetAmount": 64800000000000000000
}

Construct AMM Data

AMM Data including relevant details such as poolId, tickindex, timestamp, asset amount, nounce and vesselPublicKey.

vesselPublicKey: Public key associated with Vessel. Please visit our website to get your Key.

poolId: The unique identifier of the AMM pool.

tickIndexL: The minimum price tick index.

tickIndexR: The maximum price tick index.

timestamp: Unix timestamp in milliseconds when the order is placed.

baseAmount: Amount of the base asset.

quoteAmount: Amount of the quote asset.

nonce: An arbitrary number that can be used just once in a cryptographic communication.

These data structure can be put into the following example of order data:

{
  "vesselPublicKey": "0xYourVesselPublicKey",
  "takerFeeRate": 2000,
  "makerFeeRate": 2000,
  "timestamp": 1644568800000,
  "clientOrderId": "uniqueOrderIdentifier",
  "buyAssetId": 4,
  "sellAssetId": 1,
  "buyAssetAmount": 18000000000,
  "sellAssetAmount": 64800000000000000000
}

Poseidon Calculation

For Placing Order

The Poseidon hash is calculated based on the provided order details and the Vessel Public Key using the following formula:

M s g H a s h = P ose i d o n (P ose i d o n (P ose i d o n (X, Y), Z), U)

Where:

X = buyAssetId + sellAssetId \cdot 2^{32} + takerFeeRate \cdot 2^{64} + makerFeeRate \cdot 2^{96} + timestamp \cdot 2^{128}

Y = buyAssetAmount + sellAssetAmount \cdot 2^{126}

Z = clientOrderId

U = Poseidon (pointX % ∣ F_{q} ∣, pointY % ∣ F_{q} ∣)

Notes:

pointX

is the result of combining 0x with the first 64 bytes of vesselPublicKey(without 0x).

pointY

is the result of combining 0x with the last 64 bytes of vesselPublicKey(without 0x).

U

Z

, and

timestamp

uniquely identify each order, while other variables provide detailed order information.

Specify fee rates (

makerFeeRate

and

takerFeeRate

) as integer values, with the actual percentage obtained by dividing the input by

1 0^{6}

Asset amount should be multiplied by

1 0^{o n C hain Dec ima l}

For Adding Liquidity

M s g H a s h = P ose i d o n (X, Y, Z)

Where:

X = poolId + tickIndexL \cdot 2^{32} + tickIndexR \cdot 2^{96} + timestamp \cdot 2^{160} + 2^{224}

Y = baseAmount + quoteAmount \cdot 2^{126}

Z = nonce

For Removing Liquidity

M s g H a s h = P ose i d o n (X, Y, Z)

Where:

X = poolId + tickIndexL \cdot 2^{32} + tickIndexR \cdot 2^{96} + timestamp \cdot 2^{160}

Y = baseAmount + quoteAmount \cdot 2^{126}

Z = nonce

For Collecting Fee

M s g H a s h = P ose i d o n (X, Y, Z)

Where:

X = poolId + tickIndexL \cdot 2^{32} + tickIndexR \cdot 2^{96} + timestamp \cdot 2^{160}

Y = 0

Z = nonce

ECDSA Signature

Generate an ECDSA signature using the secp256k1 elliptic curve based on the

M s g H a s h

and VesselPrivateKey.

JavaScript Example

For your convenience, a JavaScript script is provided below to streamline the process of generating Poseidon signatures for order placement on our platform.

If you prefer to calculate Poseidon signatures in other platforms, we offer an example on Vessel GitHub. This example demonstrates how to access Poseidon implementation in different platforms through C shared libraries, following cgo examples.

Generate Order Signature Script Code

Generate AMM Signature Script Code

Script Guide

Run the Script Locally

Copy the JavaScript script into your local environment.

Run the script using your preferred JavaScript runtime environment.

Install the required Node.js modules.

The dependency on ethers version ^5.7.2 is recommended. Other versions may cause errors.

Input Default or Custom Parameters

The script comes with default parameters for testing purposes on Testnet.

Modify parameters such as symbol, side, quantity, vesselPublicKey, vesselPrivateKey to match your desired order details.

When generating an AMM signature, users can input "AddLiquidity", "RemoveLiquidity" and "CollectFee" as the value for the type parameter.

Copy Results for Apifox Testing

Once the script completes, it will generate the body parameters and the timestamp for the header for order placement.

Copy the json, then paste it into the body of your order placement request in Apifox.

Copy the Unix timestamp in the script output and set it in the header of your order placement request in APIfox.

Important Notes

Keep Your vesselPrivateKey Secure

Never share your vesselPrivateKey with anyone. It's crucial for generating signature for order placement.

Timestamp Usage

The timestamp in the signature cannot be earlier than the order placement request timestamp by more than 60 seconds. Ensure synchronization for accurate results.

Feel free to customize parameters based on your testing needs. Experience the simplicity of generating Poseidon signatures for secure and authenticated order placement.

Poseidon Hashing#

Construct Order Data#

Construct AMM Data#

Poseidon Calculation#

For Placing Order#

For Adding Liquidity#

For Removing Liquidity#

For Collecting Fee#

ECDSA Signature#

JavaScript Example#

Generate Order Signature Script Code#

Generate AMM Signature Script Code#

Script Guide#

Run the Script Locally#

Input Default or Custom Parameters#

Copy Results for Apifox Testing#

Important Notes#

Keep Your vesselPrivateKey Secure#

Timestamp Usage#

Poseidon Hashing

Construct Order Data

Construct AMM Data

Poseidon Calculation

For Placing Order

For Adding Liquidity

For Removing Liquidity

For Collecting Fee

ECDSA Signature

JavaScript Example

Generate Order Signature Script Code

Generate AMM Signature Script Code

Script Guide

Run the Script Locally

Input Default or Custom Parameters

Copy Results for Apifox Testing

Important Notes

Keep Your vesselPrivateKey Secure

Timestamp Usage