Ledger Service API

Canton Network access layer providing balance queries, token transfers, party management, and smart contract interactions on the Canton ledger.

Endpoints

Method	Endpoint	Description
`GET`	`/api/ledger/balance/:partyId`	Get CC/Amulet balance for party
`POST`	`/api/ledger/transfer`	Transfer tokens between parties
`GET`	`/api/ledger/identity`	Get ledger identity information
`POST`	`/api/ledger/parties`	Allocate new party on Canton
`GET`	`/api/ledger/parties`	List tenant's parties
`POST`	`/api/ledger/contracts`	Create contract on ledger
`GET`	`/api/ledger/contracts/:id`	Get contract by ID
`POST`	`/api/ledger/contracts/:id/exercise`	Exercise choice on contract
`GET`	`/api/ledger/time`	Get current ledger time
`GET`	`/api/ledger/domains`	List synchronization domains

Get Balance

GET /api/ledger/balance/party::alice::12345
X-Tenant-Id: your-tenant-id

Response

{
  "data": {
    "partyId": "party::alice::12345",
    "balance": "1000.00",
    "currency": "CC",
    "holdingFee": "0.01",
    "lastUpdated": "2024-01-15T10:30:00Z"
  }
}

Transfer Tokens

POST /api/ledger/transfer
X-Tenant-Id: your-tenant-id
Content-Type: application/json

{
  "sender": "party::alice::12345",
  "receiver": "party::bob::67890",
  "amount": "100.00",
  "reference": "Payment for services"
}

Response

{
  "data": {
    "transactionId": "tx_abc123",
    "sender": "party::alice::12345",
    "receiver": "party::bob::67890",
    "amount": "100.00",
    "status": "completed",
    "completedAt": "2024-01-15T10:30:00Z"
  }
}

Allocate Party

POST /api/ledger/parties
X-Tenant-Id: your-tenant-id
Content-Type: application/json

{
  "displayName": "Treasury Wallet",
  "partyHint": "treasury"
}

Response

{
  "data": {
    "partyId": "party::treasury::54321",
    "displayName": "Treasury Wallet",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

List Parties

GET /api/ledger/parties
X-Tenant-Id: your-tenant-id

Response

{
  "data": [
    {
      "partyId": "party::alice::12345",
      "displayName": "Alice",
      "createdAt": "2024-01-01T00:00:00Z"
    },
    {
      "partyId": "party::treasury::54321",
      "displayName": "Treasury Wallet",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Create Contract

POST /api/ledger/contracts
X-Tenant-Id: your-tenant-id
Content-Type: application/json

{
  "templateId": "Tenzro.Token:Asset",
  "payload": {
    "owner": "party::alice::12345",
    "amount": "1000.00",
    "symbol": "USDC"
  }
}

Exercise Choice

POST /api/ledger/contracts/contract_abc123/exercise
X-Tenant-Id: your-tenant-id
Content-Type: application/json

{
  "choice": "Transfer",
  "argument": {
    "newOwner": "party::bob::67890",
    "amount": "100.00"
  }
}

Get Ledger Time

GET /api/ledger/time
X-Tenant-Id: your-tenant-id

Response

{
  "data": {
    "currentTime": "2024-01-15T10:30:00Z",
    "ledgerEffectiveTime": "2024-01-15T10:30:00Z"
  }
}

Canton Network Integration

The Ledger Service connects to Canton Network, a privacy-first enterprise blockchain. Key concepts:

Parties - Identities on the ledger that can own contracts
Contracts - Smart contract instances with state
Choices - Actions that can be exercised on contracts
Domains - Synchronization domains for privacy isolation

Error Codes

Code	Description
`PARTY_NOT_FOUND`	Party does not exist
`INSUFFICIENT_BALANCE`	Not enough balance for transfer
`CONTRACT_NOT_FOUND`	Contract does not exist or is archived
`INVALID_CHOICE`	Choice not available on contract
`DOMAIN_UNAVAILABLE`	Synchronization domain not available