FRAGMENT

Documentation

B Deploy your Ledger#

Once you've designed your Ledger, you can deploy it using the dashboard, the API, or by embedding our CLI in your CI.

a. Dashboard

#

You can edit and store your Schema and create Ledgers directly from the FRAGMENT Dashboard. This is useful during development, but is not recommended for production workflows.

b. API

#

You can call the API to store your Schema and create Ledgers. This is useful if you want to automate your Ledger deployment or have multiple environments which you want to keep in-sync. If you are creating many Schemas and Ledgers, you can also call the storeSchema and createLedger APIs directly from your product.

Call storeSchema to store a Schema. Depending on your use case, you may share one Schema for all your users, or create a Schema per user.

storeSchema query"
↓
mutation QuickstartStoreSchema($schema: SchemaInput!) {
  storeSchema(schema: $schema) {
    ... on StoreSchemaResult {
      schema {
        key
        name
        version {
          version
          created
          json
        }
      }
    }
    ... on Error {
      code
      message
    }
  }
}
 
storeSchema variables"
↓
{
  "schema": {
    "key": "quickstart-schema",
    "name": "Quickstart Schema",
    "chartOfAccounts": {
      "defaultCurrency": {
        "code": "USD"
      },
      "defaultCurrencyMode": "single",
      "accounts": [
        {
          "key": "assets",
          "type": "asset",
          "children": [
            {
              "key": "banks",
              "children": [
                {
                  "key": "user-cash"
                }
              ]
            }
          ]
        },
        {
          "key": "liabilities",
          "type": "liability",
          "children": [
            {
              "key": "users",
              "template": true,
              "consistencyConfig": {
                "ownBalanceUpdates": "strong"
              },
              "children": [
                {
                  "key": "available"
                },
                {
                  "key": "pending"
                }
              ]
            }
          ]
        },
        {
          "key": "income",
          "type": "income"
        },
        {
          "key": "expense",
          "type": "expense",
          "children": []
        }
      ]
    },
    "ledgerEntries": {
      "types": [
        {
          "type": "user_funds_account",
          "description": "Funding {{user_id}} for {{funding_amount}}.",
          "lines": [
            {
              "account": { "path": "assets/banks/user-cash" },
              "key": "funds_arrive_in_bank",
              "amount": "{{funding_amount}}"
            },
            {
              "account": { "path": "liabilities/users:{{user_id}}/available" },
              "key": "increase_user_balance",
              "amount": "{{funding_amount}}"
            }
          ]
        },
        {
          "type": "p2p_transfer",
          "description": "P2P of {{transfer_amount}} from {{from_user_id}} to {{to_user_id}}.",
          "lines": [
            {
              "account": {
                "path": "liabilities/users:{{from_user_id}}/available"
              },
              "key": "decrease_from_user",
              "amount": "-{{transfer_amount}}"
            },
            {
              "account": { "path": "liabilities/users:{{to_user_id}}/available" },
              "key": "increase_to_user",
              "amount": "{{transfer_amount}}"
            }
          ],
          "conditions": [
            {
              "account": {
                "path": "liabilities/users:{{from_user_id}}/available"
              },
              "postcondition": {
                "ownBalance": {
                  "gte": "0"
                }
              }
            }
          ]
        }
      ]
    }
  }
}
 

Create a Ledger using the createLedger mutation.

createLedger
mutation QuickstartCreateLedger(
  $ik: SafeString!
  $ledger: CreateLedgerInput!
  $schema: SchemaMatchInput
) {
  createLedger(
    ik: $ik,
    ledger: $ledger,
    schema:$schema
  ) {
    ... on CreateLedgerResult {
      ledger {
        ik
        name
        created
        balanceUTCOffset
        schema {
          key
        }
      }
    }
    ... on Error {
      code
      message
    }
  }
}

The schema.key field is set to the key from the storeSchema API call.

createLedger variables
{
  "ik": "quickstart-ledger",
  "ledger": {
    "name": "Quickstart Ledger",
    "balanceUTCOffset": "-08:00"
  },
  "schema": {
    "key": "quickstart-schema"
  }
}

You can set the balanceUTCOffset to specify the timezone for balance calculations. See the Timezone offsets section for more details.

c. CLI

#

The FRAGMENT CLI can be installed in your CI and used to store your Schema.

Here's an example of how you can use the CLI in a Github Action workflow:

Fragment CLI in Github Actions"
↓
- name: Use Node.js 20.x
  uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4
  with:
    node-version: 20.x
- name: Install Fragment CLI
  run: |
    npm install -g @fragment-dev/cli
    echo "Fragment CLI installed"
- name: Authenticate with Fragment
  run: |
    fragment login \
      --client-id ${{ vars.FRAGMENT_CLIENT_ID }} \
      --client-secret ${{ vars.FRAGMENT_CLIENT_SECRET }} \
      --api-url ${{ vars.FRAGMENT_API_URL }} \
      --oauth-url ${{ vars.FRAGMENT_OAUTH_URL }} \
      --oauth-scope ${{ vars.FRAGMENT_OAUTH_SCOPE }}
- name: Store Schema
  run: |
    fragment store-schema --path my-schema.jsonc
 

Read the CLI Command Reference to learn more about the FRAGMENT CLI.