API Definition

Description of the subscriptions API, learn how to subscribe to data.

All the JS examples in this definition are made using PaltaLabs' Mercury SDK. We thank the Paltalabs team for providing and maintaining this SDK!

Before you use those examples, you need to define mercuryInstance:

import { Mercury } from "mercury-sdk";

const mercuryInstance = new Mercury({
  backendEndpoint: process.env.MERCURY_BACKEND_ENDPOINT,
  graphqlEndpoint: process.env.MERCURY_GRAPHQL_ENDPOINT,
  email: process.env.MERCURY_TESTER_EMAIL,
  password: process.env.MERCURY_TESTER_PASSWORD,
});

Contract Events Subscription

Contract event subscriptions allow you to start indexing smart contract events.

cURL

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $JWT_TOKEN" \
     -d '{
          "contract_id": "CONTRACT_ID",
          "topic1": "SOME_SCVAL_XDR",
          "topic2": "SOME_SCVAL_XDR",
          "topic3": "SOME_SCVAL_XDR",
          "topic4": "SOME_SCVAL_XDR"
         }' \
     MERCURY_ENDPOINT/event

Javascript (Mercury SDK From PaltaLabs)

mercuryInstance.subscribeToContractEvents({
  contractId: "CONTRACT_ID",
  topic1: "SOME_SCVAL_XDR",
  topic2: "SOME_SCVAL_XDR",
  topic3: "SOME_SCVAL_XDR",
  topic4: "SOME_SCVAL_XDR",
});

Contract Data Ledger Entries Subscription

Contract data ledger entries subscriptions allow you to index all changes to certain contract data. For example, imagine that it could keep track of balances.

cURL

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $JWT_TOKEN" \
     -d '{
          "contract_id": "CONTRACT_ID",
          "key_xdr": "SOME_SCVAL_XDR",
          "durability": "persistent"
          "hydrate": true
         }' \
     MERCURY_ENDPOINT/entry

Javascript (Mercury SDK From PaltaLabs)

const args = {
    contractId: "CONTRACT_ID",
    keyXdr: "SOME_SCVAL_XDR", // For example AAAAFA== is contract instance.
    durability: "persistent",
    hydrate: true,
}
const subscribe = await mercuryInstance.subscribeToLedgerEntries(args).catch((err) => {
    console.error(err)
})

Note that the hydrate: bool flag specifies whether you want to make a light upon subscribing. This means the current value in the ledger will be queriable after the subscription.

Ledger Entries Expiration Subscription

Tracks the current lifetime of a certain ledger entry.

cURL

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $JWT_TOKEN" \
     -d '{
          "hash_xdr": "HASHED_LEDGER_KEY_XDR_BASE64",
         }' \
     MERCURY_ENDPOINT/expiration

Where hash_xdr is a base64 encoded XDR object Hash which wraps the SHA256 of a LedgerKey XDR object.

Generating the correct hash_xdr can be non-trivial without guidance, so we will include here a brief Rust snippet that you can use to calculate the param:

// Make sure to import sha2::{Digest, Sha256} and all the XDR structures used first.
#[test]
fn to_bytes() {
    let key = LedgerKey::ContractData(LedgerKeyContractData {
        contract: ScAddress::Contract(Hash(stellar_strkey::Contract::from_string("CDRBYAW4UHXWVBCM4MIYZNL2EAW4TEKLQKUS7SXO67BG4IWAHXIDW63A").unwrap().0)),
        key: ScVal::LedgerKeyContractInstance,
        durability: ContractDataDurability::Persistent
    });
    let mut hasher = Sha256::new();
    hasher.update(key.to_xdr(Limits::none()).unwrap());
    let result = hasher.finalize().as_slice().try_into().unwrap();
    println!("Your hash_xdr is {}", Hash(result).to_xdr_base64(Limits::none()).unwrap());
}

Account Subscriptions

Account subscriptions allow you to start indexing operations, balances, and the account object of a certain Stellar account. These are mostly used for the Stellar "classic" side.

cURL

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $JWT_TOKEN" \
     -d '{
          "publickey": "PUBLIC_KEY",
          "hydrate": true
         }' \
     MERCURY_ENDPOINT/account

Javascript (Mercury SDK From PaltaLabs)

mercuryInstance.subscribeToFullAccount({
  address: "PUBLIC_KEY",
});

Note that the hydrate: bool flag specifies whether you want to make a light catchup upon subscribing. This means that the latest operations and current balances of the public key will be queriable right after the subscription, even if these were emitted before the time of the subscription.

When specifying hydrate: true, if no account exists on the network with that public key, the backend will return an error.