fibre

type API struct {
	Internal struct {
		Submit func(
			context.Context,
			libshare.Namespace,
			[]byte,
			*txclient.TxConfig,
		) (*SubmitResult, error) `perm:"write"`
		Upload func(
			ctx context.Context,
			ns libshare.Namespace,
			data []byte,
			config *txclient.TxConfig,
		) (*UploadResult, error) `perm:"write"`
		Download func(
			ctx context.Context,
			blobID appfibre.BlobID,
		) (*GetBlobResult, error) `perm:"read"`
		QueryEscrowAccount func(
			ctx context.Context,
			signer string,
		) (*fibre.EscrowAccount, error) `perm:"read"`
		Deposit func(
			ctx context.Context,
			amount sdktypes.Coin,
			cfg *txclient.TxConfig,
		) error `perm:"write"`
		Withdraw func(
			ctx context.Context,
			amount sdktypes.Coin,
			cfg *txclient.TxConfig,
		) error `perm:"write"`
		PendingWithdrawals func(
			ctx context.Context,
			signer string,
		) ([]fibre.PendingWithdrawal, error) `perm:"read"`
	}
}

type GetBlobResult struct {
	// Data is the raw blob data reconstructed from FSPs.
	Data []byte `json:"data"`
}

type Module interface {
	// Submit submits a v0 Fibre blob via the Fibre network.
	// It performs the full Fibre flow: uploads blob data to FSPs, aggregates validator
	// availability signatures, and submits MsgPayForFibre on-chain.
	// Returns the submission result including the on-chain height and transaction hash.
	// Requires the node to be connected to a core endpoint with Fibre support.
	// NOTE: Currently only v0 Fibre blobs are supported.
	Submit(context.Context, libshare.Namespace, []byte, *txclient.TxConfig) (*SubmitResult, error)
	// Upload performs the off-chain portion of v0 Fibre blob submission only.
	// It encodes the blob, constructs a payment promise, uploads encoded rows to FSPs,
	// and aggregates validator availability signatures. It does NOT submit MsgPayForFibre on-chain.
	// Use fibre.Submit for the full submit flow.
	// NOTE: Currently only v0 Fibre blobs are supported.
	Upload(context.Context, libshare.Namespace, []byte, *txclient.TxConfig) (*UploadResult, error)
	// Download retrieves a Fibre blob from FSPs by blobID.
	// It reconstructs the original blob data from the encoded rows stored off-chain.
	Download(context.Context, appfibre.BlobID) (*GetBlobResult, error)
	// QueryEscrowAccount returns the escrow account details for the given signer address,
	// including total balance and available (spendable) balance.
	QueryEscrowAccount(_ context.Context, signer string) (*fibre.EscrowAccount, error)
	// Deposit adds funds to the node's Fibre escrow account.
	// The signer is resolved from cfg (SignerAddress or KeyName) or the node's default account.
	Deposit(context.Context, sdktypes.Coin, *txclient.TxConfig) error
	// Withdraw requests a withdrawal from the node's Fibre escrow account.
	// The signer is resolved from cfg (SignerAddress or KeyName) or the node's default account.
	// The withdrawal enters an unbonding period before funds become claimable.
	Withdraw(context.Context, sdktypes.Coin, *txclient.TxConfig) error
	// PendingWithdrawals returns all pending (not yet claimable) withdrawals for the given signer.
	PendingWithdrawals(_ context.Context, signer string) ([]fibre.PendingWithdrawal, error)
}

type PaymentPromise struct {
	// ChainID is the chain identifier for which the promise is valid.
	ChainID string `json:"chain_id"`
	// Namespace is the blob namespace.
	Namespace libshare.Namespace `json:"namespace"`
	// BlobSize is the size of the uploaded blob data in bytes.
	BlobSize uint32 `json:"blob_size"`
	// Commitment is the Fibre commitment for the blob.
	Commitment appfibre.Commitment `json:"commitment"`
	// RowVersion is the blob/share version used for encoding.
	RowVersion uint32 `json:"row_version"`
	// ValsetHeight is the validator set height at the time the promise was created.
	ValsetHeight uint64 `json:"valset_height"`
	// CreationTimestamp is the time when the payment promise was created.
	CreationTimestamp time.Time `json:"creation_timestamp"`
	// Signature is the cryptographic signature over the promise fields.
	Signature []byte `json:"signature"`
}

type SubmitResult struct {
	UploadResult
	// Height is the block height at which MsgPayForFibre was included on-chain.
	Height uint64 `json:"height"`
	// TxHash is the transaction hash of the on-chain MsgPayForFibre.
	TxHash string `json:"tx_hash"`
}

type UploadResult struct {
	// BlobID is the Fibre blob identifier for the uploaded blob.
	BlobID appfibre.BlobID `json:"blob_id"`
	// ValidatorSignatures are attestations from validators confirming blob availability.
	ValidatorSignatures []ValidatorSignature `json:"validator_signatures"`
	// PaymentPromise is the signed promise used for on-chain fee settlement.
	PaymentPromise *PaymentPromise `json:"payment_promise,omitempty"`
}

type ValidatorSignature []byte