API Layer
ArkService
The ArkService is the primary API layer for interacting with the Arkade server
The
ArkService handles the core business logic of the Ark protocol’s batch processing system. Operations encompass onchain batch coordination and settlement, including the coordination of multi-party signing sessions using MuSig2, intent management, as well as offchain VTXO spending operations. It provides a comprehensive set of gRPC and REST endpoints to facilitate client-side coordination.
API Layer Logic
TheArkService abstracts much of the protocol logic, helping builders focus on client experiences.
| Operation Category | Methods | Purpose |
|---|---|---|
| System Information | GetInfo | Server parameters and network information |
| Intent Management | RegisterIntent, DeleteIntent | Client intent registration |
| Batch Participation | ConfirmRegistration, GetEventStream | Multi-party batch processing coordination |
| Tree Signing | SubmitTreeNonces, SubmitTreeSignatures | MuSig2 multi-signature coordination |
| Forfeit Management | SubmitSignedForfeitTx | Forfeit tx submission and retrieval |
| Offchain Execution | SubmitTx, FinalizeTx | Offchain tx submission and finalization |
| Real-time Updates | GetTransactionsStream | Live tx notifications |
Building without the SDKs still requires a solid understanding of how to create, validate, and process batch events.
API Layer Logic Explained
System Information
System Information
GetInfo provides essential server configuration and network parameters. It returns (GetInfoResponse)- ..the signer public key, network type, and version information
- ..timing parameters like round intervals and expiry delays
- ..economic parameters such as dust limits and min/max amounts for UTXOs and VTXOs
- ..the forfeit address where funds are sent as part of Arkade’s security mechanism
- ..market hour information, signaling operational time windows when the Arkade server processes batches
Intent Management
Intent Management
Intent registration and removal is using
BIP322 signatures for proof of ownership:RegisterIntentallows clients to register new transaction intentsDeleteIntentenables clients to remove previously registered intents
Batch Participation
Batch Participation
ConfirmRegistrationallows selected clients to confirm participation in the next batchGetEventStreamprovides clients with real-time batch updates including batch start, finalization, and failure notifications
Tree Signing via MuSig2
Tree Signing via MuSig2
The server coordinates the MuSig2 multi‑signature process:
SubmitTreeNonceslets clients submit nonces for the MuSig2 sessionSubmitTreeSignatureslets clients submit partial signatures for aggregation
Forfeit Management
Forfeit Management
SubmitSignedForfeitTxs handles forfeit transaction submission. The Arkade server verifies and finalizes the transaction as part of the batch settlement process.
If a delegate is involved, the forfeit transaction is partially signed with
SIGHASH_ALL | ANYONECANPAY allowing a connector output to be added once the delegate submits the intent.Offchain Execution
Offchain Execution
Arkade’s virtual mempool tracks the two-phase lifecycle of offchain transactions that spend VTXOs:
SubmitTxinitiates offchain spending with the user handing in signed Arkade transactions (signed_ark_tx) and unsigned checkpoint transactions (checkpoint_txs)FinalizeTxcompletes the process by submitting fully signed checkpoint transactions
Real-time Updates
Real-time Updates
GetTransactionsStream is a server-side streaming RPC that allows clients to receive real-time notifications for both Commitment and Arkade transactions.Each notification uses TxNotification, and which includes:- the transaction ID (
txid) andtxfields containing the transaction hash and the raw transaction data - VTXO state changes with
spent_vtxosshowing which VTXOs were consumed andspendable_vtxosshowing newly created VTXOs - Checkpoint transactions keyed by outpoint
Notes for Builders
The complete ArkService interface is defined in the Protocol Buffers specification and includes all these functions as part of the core gRPC service.- All endpoints follow RESTful conventions using HTTP annotations
- Query
GetInfoto verify server compatibility, network type, and version information before establishing connections arkv1.GetEventStreamandarkv1.GetTransactionsStreamare server-side streaming RPCs for event-driven clients that should be run in background processes to react in real-time- All client-side operations involving intent submission should be signed using BIP322-compatible wallets
- Intent registration and confirmation are critical steps before a client can participate in a settlement
The
ArkService is complementary to the IndexerService.
Use the ArkService for real-time updates and the IndexerService for historical transaction data and detailed analysis