stellar

package
v1.6.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 29, 2026 License: AGPL-3.0 Imports: 5 Imported by: 0

README

pkg/stellar

Go client for everything Microvault does on the Stellar network — both classic operations (accounts, trustlines, payments) and Soroban smart-contract calls (the Vault). One composite service fronts both.

flowchart TD
    Host["host service"] --> Svc["stellar.Service"]
    Svc --> Classic["classic.Service<br/>accounts, trustlines,<br/>payments, USDC sends"]
    Svc --> Soroban["soroban.Service<br/>vault borrow/repay,<br/>views, admin"]
    Svc --> Poll["rpc.PollTransaction<br/>build to sign to<br/>submit to poll"]
    Classic --> RPC["Stellar RPC"]
    Soroban --> RPC
    RPC --> Net["Stellar network"]

Subpackages

Package What lives here
classic Off-chain Stellar ops: sponsored child-account creation, sponsored USDC trustlines, treasury USDC sends, trustline checks.
soroban Go client for the Vault contract: borrow/repay/accrue, read-only views, admin operations.
rpc PollTransaction — waits for a submitted transaction to be applied to the ledger.
types Request/response DTOs (dto.go), service errors, and contract-error mapping (errors.go).
testing MockRPCClient and deterministic test keys used by the table tests.

Building the service

stellar.Service embeds both classic.Service and soroban.Service, so a caller holds one handle for on-chain and off-chain work. Build it with NewService (stellar_service.go):

svc := stellar.NewService(
    rpcClient,           // *rpcclient.Client
    networkPassphrase,   // e.g. "Test SDF Network ; September 2015"
    treasuryPrivateKey,  // signs and pays for classic + treasury operations
    adminPrivateKey,     // signs Soroban admin operations
    contractID,          // the Vault contract
    usdcIssuer,          // issuer of the USDC asset we transact in
)

How it works

The concepts — the treasury sponsorship model, why child accounts hold zero XLM and carry no trustline, the two-key split, and the build/sign/submit/poll path — live in the package docs. Read them with go doc or on pkg.go.dev:

go doc ./pkg/stellar          # composite overview
go doc ./pkg/stellar/classic  # accounts, trustlines, USDC, sponsorship
go doc ./pkg/stellar/soroban  # the Vault contract client

Full reference

See docs/stellar/client.md — the complete Go-client reference: sponsorship model, account lifecycle, moving USDC, the Vault client, transaction confirmation, errors, configuration, and testing.

For the on-chain contract behaviour (deposit/withdraw, events, error codes) see docs/soroban/.

Documentation

Overview

Package stellar is the single entry point for everything the platform does on the Stellar network — both classic operations (accounts, trustlines, payments) and Vault smart-contract calls.

Service composes classic.Service and soroban.Service, so one handle covers off-chain and on-chain work. Build it with NewService, passing the RPC client, network passphrase, treasury and admin keys, the Vault contract ID, and the USDC issuer. The package also re-exports the request/response types and sentinel errors from the types package, so callers need only import this one.

The sub-packages hold the implementations: classic for off-chain Stellar ops, soroban for the Vault contract client, rpc for transaction confirmation, types for the shared DTOs and errors, and testing for the RPC mock.

One thing worth knowing up front: child accounts are fully sponsored by the treasury and hold zero XLM. They exist as tracking and audit markers, never hold USDC, and are created without a trustline. See the classic package for the full custody and sponsorship model, and docs/stellar/client.md for the complete reference.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrFailedToBuildTransaction      = types.ErrFailedToBuildTransaction
	ErrFailedToSignTransaction       = types.ErrFailedToSignTransaction
	ErrFailedToSubmitTransaction     = types.ErrFailedToSubmitTransaction
	ErrFailedToSignWithSponsorKey    = types.ErrFailedToSignWithSponsorKey
	ErrFailedToConvertTransaction    = types.ErrFailedToConvertTransaction
	ErrFailedToLoadAccount           = types.ErrFailedToLoadAccount
	ErrFailedToConvertCreditAsset    = types.ErrFailedToConvertCreditAsset
	ErrInvalidStellarAddress         = types.ErrInvalidStellarAddress
	ErrInvalidTransactionAmount      = types.ErrInvalidTransactionAmount
	ErrFailedToValidateTrustline     = types.ErrFailedToValidateTrustline
	ErrMissingTrustline              = types.ErrMissingTrustline
	ErrTransactionRejected           = types.ErrTransactionRejected
	ErrTransactionRejectedPermanent  = types.ErrTransactionRejectedPermanent
	ErrStellarCoreOverloaded         = types.ErrStellarCoreOverloaded
	ErrTransactionFailed             = types.ErrTransactionFailed
	ErrTransactionNotSuccessful      = types.ErrTransactionNotSuccessful
	ErrContextCancelled              = types.ErrContextCancelled
	ErrTransactionFailedOnLedger     = types.ErrTransactionFailedOnLedger
	ErrUnknownTransactionStatus      = types.ErrUnknownTransactionStatus
	ErrTransactionTimeout            = types.ErrTransactionTimeout
	ErrFailedToGetTransactionDetails = types.ErrFailedToGetTransactionDetails
	ErrInvalidContractID             = types.ErrInvalidContractID
	ErrNoSimulationResult            = types.ErrNoSimulationResult
	ErrSimulationFailed              = types.ErrSimulationFailed
	ErrVaultPaused                   = types.ErrVaultPaused
	ErrSharesLocked                  = types.ErrSharesLocked
	ErrInsufficientBalance           = types.ErrInsufficientBalance
)

Re-export error variables

View Source 
var MapContractError = types.MapContractError

Re-export function

Functions

This section is empty.

Types

type BorrowRequest 

type BorrowRequest = types.BorrowRequest

Re-export types from the types package for external consumers

type BorrowResponse 

type BorrowResponse = types.BorrowResponse

Re-export types from the types package for external consumers

type BumpYieldRequest added in v1.1.2 

type BumpYieldRequest = types.BumpYieldRequest

Re-export types from the types package for external consumers

type BumpYieldResponse added in v1.1.2 

type BumpYieldResponse = types.BumpYieldResponse

Re-export types from the types package for external consumers

type ContractError 

type ContractError = types.ContractError

Re-export types from the types package for external consumers

type CreateAccountRequest 

type CreateAccountRequest = types.CreateAccountRequest

Re-export types from the types package for external consumers

type EstablishTrustlineRequest added in v1.0.0 

type EstablishTrustlineRequest = types.EstablishTrustlineRequest

Re-export types from the types package for external consumers

type MultiSigConfig 

type MultiSigConfig = types.MultiSigConfig

Re-export types from the types package for external consumers

type RepayForRequest added in v1.1.2 

type RepayForRequest = types.RepayForRequest

Re-export types from the types package for external consumers

type RepayRequest 

type RepayRequest = types.RepayRequest

Re-export types from the types package for external consumers

type RepayResponse 

type RepayResponse = types.RepayResponse

Re-export types from the types package for external consumers

type SendUSDCRequest 

type SendUSDCRequest = types.SendUSDCRequest

Re-export types from the types package for external consumers

type SendUSDCResponse 

type SendUSDCResponse = types.SendUSDCResponse

Re-export types from the types package for external consumers

type Service 

type Service interface {
	classic.Service
	soroban.Service
}

Service composes both classic and soroban services

func NewService 

func NewService(
	rpcClient *rpcclient.Client,
	networkPassphrase string,
	treasuryPrivateKey string,
	adminPrivateKey string,
	contractID string,
	usdcIssuer string,
) Service

NewService creates a new Stellar service with both classic and Soroban support

type SponsoredPaymentTransactionRequest 

type SponsoredPaymentTransactionRequest = types.SponsoredPaymentTransactionRequest

Re-export types from the types package for external consumers

type SponsoredPaymentTransactionResponse 

type SponsoredPaymentTransactionResponse = types.SponsoredPaymentTransactionResponse

Re-export types from the types package for external consumers

type VaultStatus 

type VaultStatus = types.VaultStatus

Re-export types from the types package for external consumers

Source Files

View all Source files

Directories

Path Synopsis
Package classic holds the platform's non-Soroban Stellar operations: creating accounts, establishing trustlines, and moving USDC.
 Package classic holds the platform's non-Soroban Stellar operations: creating accounts, establishing trustlines, and moving USDC.
Package rpc waits for a submitted Stellar transaction to be applied to the ledger.
 Package rpc waits for a submitted Stellar transaction to be applied to the ledger.
Package soroban is the Go client for the Vault smart contract.
 Package soroban is the Go client for the Vault smart contract.
Package testing provides the shared test doubles for the stellar packages.
 Package testing provides the shared test doubles for the stellar packages.
Package types holds the request and response DTOs shared across the stellar packages, plus the error values they return.
 Package types holds the request and response DTOs shared across the stellar packages, plus the error values they return.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.