README
¶
Stellar chain fakes
In-process implementation of the Stellar chain capability
(stellar:ChainSelector:<selector>@1.0.0) used by cre-cli's
cre workflow simulate.
This module is deliberately small (chainlink-common + go-stellar-sdk) so cre-cli can import it without pulling in the relayer or deployment dependency trees.
Reads
ReadContract and GetLatestLedger proxy to the configured Stellar RPC.
ReadContract runs the call through simulateTransaction; an empty
source_account uses the all-zero placeholder account.
How WriteReport works
Production DON writes go through the CRE forwarder (contracts/cre/forwarder),
which verifies f+1 ed25519 DON signatures and only accepts allowlisted
transmitters. A local simulation can produce neither, so the fake writes
through the mock forwarder (contracts/cre/mock_forwarder) instead: a
permissionless contract with the same report(transmitter, receiver, raw_report, report_context, signatures) entrypoint, report layout, replay
protection, on_report dispatch and forwarder_ReportProcessed event, minus
signature and transmitter checks. The fake sends an empty signature vector.
Result mapping mirrors production:
| Outcome | TxStatus |
ReceiverContractExecutionStatus |
|---|---|---|
| Forwarder rejects the call (malformed report, replay, archived state) | REVERTED |
unset |
Forwarder accepts; receiver on_report succeeds |
SUCCESS |
SUCCESS |
Forwarder accepts; receiver on_report errors or traps |
SUCCESS |
REVERTED |
| Submission rejected by the network (broadcast only) | FATAL |
unset |
The receiver outcome is read from the forwarder's ReportProcessed.success.
Modes
- Dry-run (
Config.DryRun = true):report()is run throughsimulateTransactionin record-auth mode. Nothing is submitted and no key is needed (a placeholder transmitter is used whenTransmitteris nil). The returnedtx_hashis the hash of the unsigned simulated transaction. - Broadcast: the fake loads the transmitter account, preflights with
simulateTransaction, attaches the Soroban footprint/resource fee (+20% headroom) and auth entries, signs withConfig.Transmitter, submits withsendTransactionand pollsgetTransactionuntil confirmed orConfig.TxTimeout. A preflight failure is returned asREVERTEDwithout submitting. Writes are serialized per fake so sequence numbers never race. The transmitter account must exist and be funded.
What receiver authors still need
Receivers see the mock forwarder as sender in on_report. A receiver
that gates on its trusted forwarder (e.g. the data-feeds cache's
(sender, workflow_owner, workflow_name) permissions) must be configured to
trust the mock forwarder for writes to take effect. Use a test receiver for
this; never configure a production receiver to accept the mock forwarder.
Receiver events are logged at info level, so permission rejections such as
InvalidUpdatePermission show up in simulation output.
Documentation
¶
Overview ¶
Package fakes provides an in-process implementation of the Stellar chain capability for cre-cli's `cre workflow simulate`. Stellar counterpart to chainlink-solana/contracts/capabilities/fakes. See README.md.
Index ¶
- type Config
- type FakeStellarChain
- func (c *FakeStellarChain) ChainSelector() uint64
- func (c *FakeStellarChain) Close() error
- func (c *FakeStellarChain) Description() string
- func (c *FakeStellarChain) GetLatestLedger(ctx context.Context, _ commonCap.RequestMetadata, ...) (*commonCap.ResponseAndMetadata[*stellarcap.GetLatestLedgerResponse], ...)
- func (c *FakeStellarChain) HealthReport() map[string]error
- func (c *FakeStellarChain) Initialise(context.Context, core.StandardCapabilitiesDependencies) error
- func (c *FakeStellarChain) Name() string
- func (c *FakeStellarChain) ReadContract(ctx context.Context, _ commonCap.RequestMetadata, ...) (*commonCap.ResponseAndMetadata[*stellarcap.ReadContractResponse], ...)
- func (c *FakeStellarChain) Ready() error
- func (c *FakeStellarChain) Start(context.Context) error
- func (c *FakeStellarChain) WriteReport(ctx context.Context, _ commonCap.RequestMetadata, ...) (*commonCap.ResponseAndMetadata[*stellarcap.WriteReportReply], caperrors.Error)
- type RPCClient
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
ChainSelector uint64
NetworkPassphrase string
// ForwarderID is the C… address of a deployed mock forwarder
// (contracts/cre/mock_forwarder). Reports are delivered through its
// report() entrypoint, which skips DON signature verification.
ForwarderID string
// Transmitter signs and pays for writes. Required unless DryRun. In dry-run
// mode a nil Transmitter is replaced by a placeholder account.
Transmitter *keypair.Full
// DryRun simulates writes with simulateTransaction instead of submitting.
DryRun bool
// TxTimeout bounds a broadcast write from submission to confirmation.
TxTimeout time.Duration
// PollInterval is the getTransaction polling interval while confirming.
PollInterval time.Duration
}
Config configures a FakeStellarChain.
type FakeStellarChain ¶
type FakeStellarChain struct {
// contains filtered or unexported fields
}
FakeStellarChain implements the Stellar chain capability for simulation.
func NewFakeStellarChain ¶
func NewFakeStellarChain(lggr logger.Logger, client RPCClient, cfg Config) (*FakeStellarChain, error)
NewFakeStellarChain validates cfg and returns a fake ready to register with stellarserver.NewClientServer.
func (*FakeStellarChain) ChainSelector ¶
func (c *FakeStellarChain) ChainSelector() uint64
func (*FakeStellarChain) Close ¶
func (c *FakeStellarChain) Close() error
func (*FakeStellarChain) Description ¶
func (c *FakeStellarChain) Description() string
func (*FakeStellarChain) GetLatestLedger ¶
func (c *FakeStellarChain) GetLatestLedger(ctx context.Context, _ commonCap.RequestMetadata, _ *stellarcap.GetLatestLedgerRequest) (*commonCap.ResponseAndMetadata[*stellarcap.GetLatestLedgerResponse], caperrors.Error)
func (*FakeStellarChain) HealthReport ¶
func (c *FakeStellarChain) HealthReport() map[string]error
func (*FakeStellarChain) Initialise ¶
func (c *FakeStellarChain) Initialise(context.Context, core.StandardCapabilitiesDependencies) error
func (*FakeStellarChain) Name ¶
func (c *FakeStellarChain) Name() string
func (*FakeStellarChain) ReadContract ¶
func (c *FakeStellarChain) ReadContract(ctx context.Context, _ commonCap.RequestMetadata, input *stellarcap.ReadContractRequest) (*commonCap.ResponseAndMetadata[*stellarcap.ReadContractResponse], caperrors.Error)
func (*FakeStellarChain) Ready ¶
func (c *FakeStellarChain) Ready() error
func (*FakeStellarChain) WriteReport ¶
func (c *FakeStellarChain) WriteReport(ctx context.Context, _ commonCap.RequestMetadata, input *stellarcap.WriteReportRequest) (*commonCap.ResponseAndMetadata[*stellarcap.WriteReportReply], caperrors.Error)
WriteReport delivers the report to input.ContractId through the mock forwarder's report(transmitter, receiver, raw_report, report_context, signatures). The mock skips signature verification, so an empty signature vector is sent: simulator-signed reports carry no ed25519 DON signatures.
Result mapping mirrors production:
- forwarder rejects the call (malformed report, replay): TX_STATUS_REVERTED;
- forwarder accepts it: TX_STATUS_SUCCESS, with the receiver's outcome (ReportProcessed.success) in ReceiverContractExecutionStatus.
type RPCClient ¶
type RPCClient interface {
GetLatestLedger(ctx context.Context) (protocol.GetLatestLedgerResponse, error)
SimulateTransaction(ctx context.Context, request protocol.SimulateTransactionRequest) (protocol.SimulateTransactionResponse, error)
SendTransaction(ctx context.Context, request protocol.SendTransactionRequest) (protocol.SendTransactionResponse, error)
GetTransaction(ctx context.Context, request protocol.GetTransactionRequest) (protocol.GetTransactionResponse, error)
LoadAccount(ctx context.Context, address string) (txnbuild.Account, error)
}
RPCClient is the subset of the Stellar RPC client the fake needs. *rpcclient.Client satisfies it.
Source Files