Transaction flow

Every state-changing operation in the Silvana Ledger service uses a two-phase transaction model. This guarantees that the private key never leaves the client, and that the server never submits anything the agent has not explicitly authorised.

Phases

Prepare

The client calls PrepareTransaction with a TransactionOperation enum value and a matching params oneof. The server builds the Canton transaction, returns its hash (prepared_transaction_hash), the serialized prepared_transaction, a transaction_id, and a TrafficEstimate.

Sign

The client signs prepared_transaction_hash with the agent’s Ed25519 private key — see Authentication for details on how signatures are carried.

Execute

The client calls ExecuteTransaction with transaction_id and the hex-encoded signature. The server submits the transaction to Canton and returns the outcome — including update_id, contract_id, any newly created contracts, and the traffic actually consumed.

TransactionOperation

The enum selects which sub-operation the server should build in phase 1:

enum TransactionOperation {
  TRANSACTION_OPERATION_UNSPECIFIED = 0;

  // DvP settlement
  TRANSACTION_OPERATION_PAY_DVP_FEE   = 1;
  TRANSACTION_OPERATION_PROPOSE_DVP   = 2;
  TRANSACTION_OPERATION_ACCEPT_DVP    = 3;
  TRANSACTION_OPERATION_PAY_ALLOC_FEE = 4;
  TRANSACTION_OPERATION_ALLOCATE      = 5;

  // Canton Coin transfers
  TRANSACTION_OPERATION_TRANSFER_CC = 6;

  // Preapproval
  TRANSACTION_OPERATION_REQUEST_PREAPPROVAL = 7;

  // Recurring payments
  TRANSACTION_OPERATION_REQUEST_RECURRING_PREPAID    = 8;
  TRANSACTION_OPERATION_REQUEST_RECURRING_PAYASYOUGO = 9;

  // User service
  TRANSACTION_OPERATION_REQUEST_USER_SERVICE = 10;

  // CIP-56 token transfers
  TRANSACTION_OPERATION_TRANSFER_CIP56 = 11;
  TRANSACTION_OPERATION_ACCEPT_CIP56   = 12;

  // CC merge-split
  TRANSACTION_OPERATION_SPLIT_CC = 13;

  // Atomic batch via Execute_MultiCall DAR choice
  TRANSACTION_OPERATION_EXECUTE_MULTICALL = 14;
}

Operations reference

Each enum value corresponds to one dedicated method page that documents its params message:

Operation	`params` field	Page
`PAY_DVP_FEE`	`pay_fee`	PayDvpFee
`PROPOSE_DVP`	`propose_dvp`	ProposeDvp
`ACCEPT_DVP`	`accept_dvp`	AcceptDvp
`PAY_ALLOC_FEE`	`pay_fee`	PayAllocFee
`ALLOCATE`	`allocate`	Allocate
`TRANSFER_CC`	`transfer_cc`	TransferCc
`SPLIT_CC`	`split_cc`	SplitCc
`REQUEST_PREAPPROVAL`	`request_preapproval`	RequestPreapproval
`TRANSFER_CIP56`	`transfer_cip56`	TransferCip56
`ACCEPT_CIP56`	`accept_cip56`	AcceptCip56
`REQUEST_RECURRING_PREPAID`	`request_recurring_prepaid`	RequestRecurringPrepaid
`REQUEST_RECURRING_PAYASYOUGO`	`request_recurring_payasyougo`	RequestRecurringPayasyougo
`REQUEST_USER_SERVICE`	`request_user_service`	RequestUserService
`EXECUTE_MULTICALL`	`execute_multicall`	ExecuteMultiCall

PrepareTransactionRequest

message PrepareTransactionRequest {
  TransactionOperation operation = 1;

  oneof params {
    PayFeeParams                       pay_fee                        = 10;
    ProposeDvpParams                   propose_dvp                    = 11;
    AcceptDvpParams                    accept_dvp                     = 12;
    AllocateParams                     allocate                       = 13;
    TransferCcParams                   transfer_cc                    = 14;
    RequestPreapprovalParams           request_preapproval            = 15;
    RequestRecurringPrepaidParams      request_recurring_prepaid      = 16;
    RequestRecurringPayasyougoParams   request_recurring_payasyougo   = 17;
    RequestUserServiceParams           request_user_service           = 18;
    TransferCip56Params                transfer_cip56                 = 19;
    AcceptCip56Params                  accept_cip56                   = 20;
    SplitCcParams                      split_cc                       = 21;
    ExecuteMultiCallParams             execute_multicall              = 22;
  }

  MessageSignature request_signature = 30;
}

PrepareTransactionResponse

string

Opaque server-assigned ID. Pass this into ExecuteTransaction.

string

Hex-encoded Canton transaction hash. This is what the agent must sign.

string

Canton command ID used for idempotency.

bytes

Serialised prepared transaction (for deterministic re-hashing if desired).

string

Canton hashing scheme version used to compute the hash.

TrafficEstimate

Estimated Canton traffic (read_cost, write_cost, total_cost) the transaction will consume.

MessageSignature

Provider signature over the response payload — see Authentication.

TransactionStatus

Always PENDING after prepare.

ExecuteTransactionRequest

string

required

Value returned from PrepareTransaction.

string

required

Hex-encoded Ed25519 signature over prepared_transaction_hash.

MessageSignature

required

Message-level signature from the cloud agent — see Authentication.

ExecuteTransactionResponse

bool

true if the transaction was submitted and committed successfully.

string

Canton update ID of the committed transaction.

string (optional)

Primary contract created by the transaction (if any).

CreatedContractInfo[]

All contracts created by the transaction — useful for tracking new amulets from change/split.

TrafficEstimate

Actual traffic consumed.

string (optional)

Featured-app rewards earned, if applicable.

uint64 (optional)

Mining round in which rewards were earned.

string (optional)

Human-readable error.

ProviderError (optional)

Structured error (ProviderRpcError) when success = false.

TransactionStatus

EXECUTED on success, FAILED on error.

Introduction

Core (read-only)

Transfer

Preapproval

Fee Payment

DvP (Delivery vs Payment)

CIP-56 Tokens

Recurring Payments

Onboarding

MultiCall

User Service

Bridge

Transaction flow

Phases

TransactionOperation

Operations reference

PrepareTransactionRequest

PrepareTransactionResponse

ExecuteTransactionRequest

ExecuteTransactionResponse

​Phases

​TransactionOperation

​Operations reference

​PrepareTransactionRequest

​PrepareTransactionResponse

​ExecuteTransactionRequest

​ExecuteTransactionResponse

Phases

TransactionOperation

Operations reference

PrepareTransactionRequest

PrepareTransactionResponse

ExecuteTransactionRequest

ExecuteTransactionResponse