Documentation
¶
Index ¶
- Constants
- Variables
- func ComputeContractID(networkPassphrase, deployerAddress string, salt [32]byte) (string, error)
- func ComputeSACContractID(networkPassphrase string, asset xdr.Asset) (string, error)
- func ContractCodeLedgerKey(wasmHash xdr.Hash) xdr.LedgerKey
- func ContractInstanceLedgerKey(contractID string) (xdr.LedgerKey, error)
- func GenerateDeterministicSalt(deployerAddress, contractName string) [32]byte
- type Deployer
- func NewDeployer(rpcClient *rpcclient.Client, networkPassphrase string, signer *keypair.Full, ...) *Deployer
- func NewDeployerFromChain(ch cldfstellar.Chain, opts ...DeployerOption) (*Deployer, error)
- func NewDeployerWithSigner(rpcClient *rpcclient.Client, networkPassphrase string, signer TxSigner, ...) *Deployer
- func (d *Deployer) ContractInstanceState(ctx context.Context, contractID string) (bool, xdr.Hash, error)
- func (d *Deployer) ContractWasmHash(ctx context.Context, contractID string) (xdr.Hash, error)
- func (d *Deployer) DeployContract(ctx context.Context, wasmPath string, salt [32]byte) (string, error)
- func (d *Deployer) DeployContractBytes(ctx context.Context, wasmBytes []byte, salt [32]byte) (string, error)
- func (d *Deployer) DeployContractBytesWithArgs(ctx context.Context, wasmBytes []byte, salt [32]byte, ctorArgs []xdr.ScVal) (string, error)
- func (d *Deployer) DeployContractWithArgs(ctx context.Context, wasmPath string, salt [32]byte, ctorArgs []xdr.ScVal) (string, error)
- func (d *Deployer) DeploySACToken(ctx context.Context, asset xdr.Asset) (string, error)
- func (d *Deployer) ExtendTTLTo(ctx context.Context, keys []xdr.LedgerKey, targetTTL uint32) ([]uint32, error)
- func (d *Deployer) ExtendTTLToMax(ctx context.Context, keys []xdr.LedgerKey) ([]uint32, error)
- func (d *Deployer) GetEvents(ctx context.Context, contractID string, startLedger uint32, topics []string) ([]protocolrpc.EventInfo, error)
- func (d *Deployer) InvokeContract(ctx context.Context, contractID string, functionName string, args []xdr.ScVal) (*xdr.ScVal, error)
- func (d *Deployer) NativeAccountState(ctx context.Context, rawAccountKey []byte) (balance *big.Int, seq uint64, exists bool, err error)
- func (d *Deployer) SendNativePayment(ctx context.Context, destinationStrkey string, stroops int64) error
- func (d *Deployer) SignerAddress() string
- func (d *Deployer) SimulateContract(ctx context.Context, contractID string, functionName string, args []xdr.ScVal) (*xdr.ScVal, error)
- func (d *Deployer) SimulateExtendTTL(ctx context.Context, keys []xdr.LedgerKey, targetTTL uint32) (fee int64, atTarget bool, err error)
- func (d *Deployer) SubmitClassicOperation(ctx context.Context, op txnbuild.Operation) error
- func (d *Deployer) UploadContractWASM(ctx context.Context, wasmPath string) (xdr.Hash, error)
- func (d *Deployer) UploadContractWASMBytes(ctx context.Context, wasmBytes []byte) (xdr.Hash, error)
- type DeployerOption
- type TxSigner
Constants ¶
const StellarTransmitterKeyName = selectors.FamilyStellar + "/tx/stellar_transmitter_ed25519_key"
StellarTransmitterKeyName is the full keystore path of the Ed25519 key used by the Stellar accessor as the transmitter / deployer keypair when signing Soroban transactions. The "stellar/tx/" prefix mirrors the "evm/tx/" convention used by chainlink-ccv's executor.DefaultEVMTransmitterKeyName.
It is declared here (in the deployment module) rather than in ccv/common to avoid a ccv <-> deployment import cycle: ccv already imports deployment for the deployer primitives (TxSigner, NewDeployerWithSigner), and deployment/adapters needs this key name when building executor chain configs, so keeping it on the deployment side holds the edge one-way (ccv -> deployment) with no back-edge.
Variables ¶
var ErrLedgerEntryNotFound = errors.New("ledger entry not found")
ErrLedgerEntryNotFound reports a ledger key with no live entry on chain.
Functions ¶
func ComputeContractID ¶
ComputeContractID returns the deterministic contract address (C… strkey) for deployerAddress+salt without touching the chain; it mirrors the preimage built by buildCreateContractHostFunction.
func ComputeSACContractID ¶
ComputeSACContractID returns the deterministic contract address (C… strkey) for a Soroban Asset Contract wrapping the given classic Stellar asset.
func ContractCodeLedgerKey ¶
ContractCodeLedgerKey is the ledger key of an uploaded WASM blob.
func ContractInstanceLedgerKey ¶
ContractInstanceLedgerKey is the ledger key of a contract's instance entry.
func GenerateDeterministicSalt ¶
GenerateDeterministicSalt generates a deterministic salt for contract deployment.
Types ¶
type Deployer ¶
type Deployer struct {
// contains filtered or unexported fields
}
Deployer handles Soroban contract deployment and initialization.
func NewDeployer ¶
func NewDeployer(rpcClient *rpcclient.Client, networkPassphrase string, signer *keypair.Full, opts ...DeployerOption) *Deployer
NewDeployer creates a Deployer from a *keypair.Full, suiting the call sites that hold a raw seed. For keystore-backed signing (raw key bytes never exposed) use NewDeployerWithSigner. Options customise behaviour.
func NewDeployerFromChain ¶
func NewDeployerFromChain(ch cldfstellar.Chain, opts ...DeployerOption) (*Deployer, error)
NewDeployerFromChain creates a Deployer directly from a CLDF Stellar chain. It uses NewKeypairSigner when the chain signer exposes a KeypairFull, and otherwise NewSDKSigner so keystore-backed signers need no raw key material.
func NewDeployerWithSigner ¶
func NewDeployerWithSigner(rpcClient *rpcclient.Client, networkPassphrase string, signer TxSigner, opts ...DeployerOption) *Deployer
NewDeployerWithSigner is like NewDeployer but accepts an arbitrary TxSigner (e.g. a ccv keystore-managed key) so raw key bytes are never exposed.
func (*Deployer) ContractInstanceState ¶
func (d *Deployer) ContractInstanceState(ctx context.Context, contractID string) (bool, xdr.Hash, error)
ContractInstanceState reads a contract's instance ledger entry, reporting whether the contract exists and, when it does, the WASM hash its instance currently runs. A contract that was never deployed reports exists=false with no error.
func (*Deployer) ContractWasmHash ¶
ContractWasmHash returns the WASM hash a deployed contract instance currently runs.
func (*Deployer) DeployContract ¶
func (d *Deployer) DeployContract(ctx context.Context, wasmPath string, salt [32]byte) (string, error)
DeployContract deploys a Soroban contract from a WASM file and returns the contract ID (upload the code, then create the instance).
func (*Deployer) DeployContractBytes ¶
func (d *Deployer) DeployContractBytes(ctx context.Context, wasmBytes []byte, salt [32]byte) (string, error)
DeployContractBytes uploads WASM bytes held in memory (e.g. go:embed) and instantiates a contract, returning the contract ID. DeployContract is the file-path wrapper.
func (*Deployer) DeployContractBytesWithArgs ¶
func (d *Deployer) DeployContractBytesWithArgs(ctx context.Context, wasmBytes []byte, salt [32]byte, ctorArgs []xdr.ScVal) (string, error)
DeployContractBytesWithArgs uploads the given WASM bytes and instantiates a contract, passing ctorArgs to its __constructor when non-empty.
func (*Deployer) DeployContractWithArgs ¶
func (d *Deployer) DeployContractWithArgs(ctx context.Context, wasmPath string, salt [32]byte, ctorArgs []xdr.ScVal) (string, error)
DeployContractWithArgs deploys a Soroban contract whose __constructor takes arguments.
func (*Deployer) DeploySACToken ¶
DeploySACToken deploys the SAC wrapper for a classic asset and returns its contract ID (C… strkey). The address is deterministic per network+asset, so an existing SAC is adopted as-is.
func (*Deployer) ExtendTTLTo ¶
func (d *Deployer) ExtendTTLTo(ctx context.Context, keys []xdr.LedgerKey, targetTTL uint32) ([]uint32, error)
ExtendTTLTo extends the given persistent ledger entries until their remaining TTL reaches targetTTL ledgers, in one ExtendFootprintTtl transaction paid by the deployer, and returns each entry's live-until ledger afterwards, in key order. When every entry already has at least targetTTL ledgers of life left, no transaction is sent. Extending is permissionless: no contract auth is involved.
targetTTL must stay below the network's MaxEntryTtl; use ExtendTTLToMax to reach the maximum. A target that keeps the simulated fee (plus the fee buffer) under the uint32 transaction-fee cap fits in a single transaction.
Archived entries are restored first when auto-restore is enabled.
func (*Deployer) ExtendTTLToMax ¶
ExtendTTLToMax extends the given persistent ledger entries to the network's maximum TTL in one ExtendFootprintTtl transaction paid by the deployer, and returns each entry's live-until ledger afterwards, in key order. Extending is permissionless: no contract auth is involved.
Extending a contract instance key does not extend its code; pass ContractCodeLedgerKey of the instance's WASM hash as well.
Archived entries are restored first when auto-restore is enabled.
The fee of a maximum extension can exceed the uint32 transaction-fee cap for large code entries; ExtendTTLTo reaches a chosen target instead.
func (*Deployer) GetEvents ¶
func (d *Deployer) GetEvents(ctx context.Context, contractID string, startLedger uint32, topics []string) ([]protocolrpc.EventInfo, error)
GetEvents returns events from a ledger range.
func (*Deployer) InvokeContract ¶
func (d *Deployer) InvokeContract(ctx context.Context, contractID string, functionName string, args []xdr.ScVal) (*xdr.ScVal, error)
InvokeContract invokes a contract function and returns the result.
func (*Deployer) NativeAccountState ¶
func (d *Deployer) NativeAccountState(ctx context.Context, rawAccountKey []byte) (balance *big.Int, seq uint64, exists bool, err error)
NativeAccountState returns the account native balance (stroops) and sequence number from the ledger. rawAccountKey must be the 32-byte Ed25519 public key (Stellar account id).
func (*Deployer) SendNativePayment ¶
func (d *Deployer) SendNativePayment(ctx context.Context, destinationStrkey string, stroops int64) error
SendNativePayment submits a payment of stroops native XLM from the deployer's account.
func (*Deployer) SignerAddress ¶
SignerAddress returns the G… strkey of the deployer's signing keypair.
func (*Deployer) SimulateContract ¶
func (d *Deployer) SimulateContract(ctx context.Context, contractID string, functionName string, args []xdr.ScVal) (*xdr.ScVal, error)
SimulateContract simulates a contract invocation without submitting.
func (*Deployer) SimulateExtendTTL ¶
func (d *Deployer) SimulateExtendTTL(ctx context.Context, keys []xdr.LedgerKey, targetTTL uint32) (fee int64, atTarget bool, err error)
SimulateExtendTTL previews ExtendTTLTo without submitting anything. It returns the simulated minimum resource fee, or atTarget=true when every entry already has at least targetTTL ledgers of life left (fee 0).
func (*Deployer) SubmitClassicOperation ¶
SubmitClassicOperation builds, signs, and submits a single classic Stellar operation (e.g. ChangeTrust, Payment). Classic ops cannot be simulated via the Soroban RPC, so this submits directly.
func (*Deployer) UploadContractWASM ¶
UploadContractWASM uploads a WASM file and returns its code hash.
func (*Deployer) UploadContractWASMBytes ¶
UploadContractWASMBytes uploads WASM bytes and returns the code hash an upgrade points an existing instance at, without instantiating. UploadContractWASM is the file-path wrapper.
type DeployerOption ¶
type DeployerOption func(*Deployer)
DeployerOption configures optional Deployer behaviour.
func WithAutoRestore ¶
func WithAutoRestore(enabled bool) DeployerOption
WithAutoRestore controls whether the Deployer automatically submits a RestoreFootprint transaction when simulation indicates that persistent ledger entries have expired. Enabled by default.
func WithFeeBumpFactor ¶
func WithFeeBumpFactor(factor float64) DeployerOption
WithFeeBumpFactor sets the multiplier applied to the simulation's MinResourceFee (1.25 = 25% headroom; a minFeeBuffer floor always applies). Non-finite or <1.0 values clamp to 1.0 (no bump).
func WithLogger ¶
func WithLogger(l cldflogger.Logger) DeployerOption
WithLogger sets an optional logger that records every submitted transaction hash with the operation's context, so pipeline and test logs show what was actually sent on chain.
func WithMaxResourceFee ¶
func WithMaxResourceFee(maxFee int64) DeployerOption
WithMaxResourceFee caps the Soroban resource fee a transaction may declare. Zero disables the cap.
func WithTxnTimeBound ¶
func WithTxnTimeBound(d time.Duration) DeployerOption
WithTxnTimeBound sets the validity window for every submitted transaction, used as both MaxTime and the confirmation poll timeout so they stay in sync. Non-positive values keep the default (120s).
type TxSigner ¶
type TxSigner interface {
// Address returns the Stellar account strkey (G...) of the signer.
Address() string
// SignTransaction signs the given transaction for the given network passphrase
// and returns a new transaction with the signature appended.
SignTransaction(networkPassphrase string, tx *txnbuild.Transaction) (*txnbuild.Transaction, error)
}
TxSigner abstracts transaction signing so the Deployer can use either an in-process *keypair.Full (tests) or a keystore-backed signer (production). Implementations MUST NOT mutate the input transaction; sign a clone.
func NewKeypairSigner ¶
NewKeypairSigner returns a TxSigner backed by the given Stellar keypair. The keypair MUST be non-nil; the caller is responsible for safe handling of the underlying private seed.
func NewSDKSigner ¶
func NewSDKSigner(sdk stellarSDKSigner) TxSigner
NewSDKSigner wraps a Stellar SDK-shaped signer (any value providing Address() and SignDecorated()) as a deployment.TxSigner. Returns nil if sdk is nil so callers can fall back to a different signer source.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package adapters registers Stellar with chainlink-ccip CCIP 2.0 tooling, with chainlink-ccv/deployment (per-concern FamilyRegistry singletons plus the shared JD identity plumbing), and with shared infrastructure (MCMS, transfer ownership, tokens, fees, curse).
|
Package adapters registers Stellar with chainlink-ccip CCIP 2.0 tooling, with chainlink-ccv/deployment (per-concern FamilyRegistry singletons plus the shared JD identity plumbing), and with shared infrastructure (MCMS, transfer ownership, tokens, fees, curse). |
|
Package ccip holds Stellar CCIP deployment helpers: datastore contract types, lane/onramp config, topology conversion, the CCIPDevenvHost surface for Soroban devenv, post-deploy token pool (DeployLockReleaseTestTokenPool), CLDF-backed devenv host (NewCLDFStellarCCIPDevenvHost), and stellarutil/.
|
Package ccip holds Stellar CCIP deployment helpers: datastore contract types, lane/onramp config, topology conversion, the CCIPDevenvHost surface for Soroban devenv, post-deploy token pool (DeployLockReleaseTestTokenPool), CLDF-backed devenv host (NewCLDFStellarCCIPDevenvHost), and stellarutil/. |
|
Package changesets exports one CLDF ChangeSetV2 per Stellar CCIP component (deploy + initialize together), wrapping the per-component sequences in deployment/sequences.
|
Package changesets exports one CLDF ChangeSetV2 per Stellar CCIP component (deploy + initialize together), wrapping the per-component sequences in deployment/sequences. |
|
Package cre exposes the CRE contract WASM artifacts produced by `stellar contract build` (into target/wasm32v1-none/release/).
|
Package cre exposes the CRE contract WASM artifacts produced by `stellar contract build` (into target/wasm32v1-none/release/). |
|
Package operations hosts CLDF-style deployment operations for Stellar Soroban contracts (thin wrappers around generated bindings plus chain I/O).
|
Package operations hosts CLDF-style deployment operations for Stellar Soroban contracts (thin wrappers around generated bindings plus chain I/O). |
|
lock_release_pool
Package lock_release_pool defines CLDF operations for the Soroban lock-release pool contract.
|
Package lock_release_pool defines CLDF operations for the Soroban lock-release pool contract. |
|
offramp
Package offramp defines CLDF operations for the Soroban OffRamp contract.
|
Package offramp defines CLDF operations for the Soroban OffRamp contract. |
|
operationstest
Package operationstest provides shared stubs for unit-testing Soroban deployment operations without a live network: a recording invoker that captures every InvokeContract/SimulateContract call, a no-op fake deployer, and a test bundle builder.
|
Package operationstest provides shared stubs for unit-testing Soroban deployment operations without a live network: a recording invoker that captures every InvokeContract/SimulateContract call, a no-op fake deployer, and a test bundle builder. |
|
Package rpclimit bounds the size of Soroban RPC HTTP responses.
|
Package rpclimit bounds the size of Soroban RPC HTTP responses. |
|
Package sequences defines CLDF deployment sequences for Stellar CCIP.
|
Package sequences defines CLDF deployment sequences for Stellar CCIP. |