timelock

package
v1.0.4 Latest Latest
Warning

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

Go to latest
Published: Apr 24, 2026 License: MIT Imports: 13 Imported by: 2

Documentation

Index

Constants

View Source
const (
	// Timestamp value used to mark an operation as done
	DoneTimestamp = 1
	// Timestamp value used to mark an operation as error
	ErrorTimestamp = 2
)

Variables

View Source
var (
	// TODO: compute with Go implementation of keccak256
	// Notice: role constants are kept as original Ethereum implementation (keccak256)
	RoleAdmin     = mustHexToBigInt("0xa49807205ce4d355092ef5a8a18f56e8913cf4a201fbe287825b095693c21775") // keccak256('ADMIN_ROLE')
	RoleProposer  = mustHexToBigInt("0xb09aa5aeb3702cfd50b6b62bc4532604938f21248a27a1d5ca736082b6819cc1") // keccak256('PROPOSER_ROLE')
	RoleCanceller = mustHexToBigInt("0xfd643c72710c63c0180259aba6b2d05451e3591a24e58b62239378085726f783") // keccak256('CANCELLER_ROLE')
	RoleExecutor  = mustHexToBigInt("0xd8aa0f3194971a2a116679f7c2090f6939c8d4e01a2a8d7e41d55e5351469e63") // keccak256('EXECUTOR_ROLE')
	RoleBypasser  = mustHexToBigInt("0xa1b2b8005de234c4b8ce8cd0be058239056e0d54f6097825b5117101469d5a8d") // keccak256('BYPASSER_ROLE')
	// @dev: new role, can report errors for executed operations
	RoleOracle = mustHexToBigInt("0x68e79a7bf1e0bc45d0a330c573bc367f9cf464fd326078812f301165fbda4ef1") // keccak256('ORACLE_ROLE')

	TopicBypasserCallExecuted Topic = hash.CRC32("Timelock_BypasserCallExecuted")
	TopicCallScheduled        Topic = hash.CRC32("Timelock_CallScheduled")
	TopicCallExecuted         Topic = hash.CRC32("Timelock_CallExecuted")
)
View Source
var BoolRes = tvm.NewResultDecoder(func(r *ton.ExecutionResult) (bool, error) {
	rs, err := r.Int(0)
	if err != nil {
		return false, fmt.Errorf("error getting bool result: %w", err)
	}

	return rs.Uint64() == 1, nil
})
View Source
var GetMinDelay = tvm.NewNoArgsGetter(tvm.NoArgsOpts[uint64]{
	Name: "getMinDelay",
	Decoder: tvm.NewResultDecoder(func(r *ton.ExecutionResult) (uint64, error) {
		rs, err := r.Int(0)
		if err != nil {
			return 0, fmt.Errorf("error getting minDelay slice: %w", err)
		}

		return rs.Uint64(), nil
	}),
})
View Source
var GetOpPendingInfo = tvm.NewNoArgsGetter(tvm.NoArgsOpts[OpPendingInfo]{
	Name: "getOpPendingInfo",
	Decoder: tvm.NewResultDecoder(func(r *ton.ExecutionResult) (OpPendingInfo, error) {
		validAfter, err := r.Int(0)
		if err != nil {
			return OpPendingInfo{}, fmt.Errorf("error getting Int(0) - validAfter: %w", err)
		}

		opFinalizationTimeout, err := r.Int(1)
		if err != nil {
			return OpPendingInfo{}, fmt.Errorf("error getting Int(1) - opFinalizationTimeout: %w", err)
		}

		opPendingID, err := r.Int(2)
		if err != nil {
			return OpPendingInfo{}, fmt.Errorf("error getting Int(2) - opPendingID: %w", err)
		}

		return OpPendingInfo{
			ValidAfter:            validAfter.Uint64(),
			OpFinalizationTimeout: uint32(opFinalizationTimeout.Uint64()),
			OpPendingID:           tlbe.NewUint256(opPendingID),
		}, nil
	}),
})
View Source
var GetRoleMember = tvm.Getter[GetRoleMemberArgs, *address.Address]{
	Name: "getRoleMember",
	Decoder: tvm.NewResultDecoder(func(r *ton.ExecutionResult) (*address.Address, error) {
		isNil, err := r.IsNil(0)
		if err != nil {
			return nil, fmt.Errorf("error checking if getRoleMember result is nil: %w", err)
		}

		if isNil {
			return nil, nil
		}

		sAddr, err := r.Slice(0)
		if err != nil {
			return nil, fmt.Errorf("error decoding getRoleMember result: %w", err)
		}

		addr, err := sAddr.LoadAddr()
		if err != nil {
			return nil, fmt.Errorf("error decoding getRoleMember result slice: %w", err)
		}
		return addr, nil
	}),
}
View Source
var GetRoleMemberCount = tvm.Getter[*big.Int, uint64]{
	Name: "getRoleMemberCount",
	Decoder: tvm.NewResultDecoder(func(r *ton.ExecutionResult) (uint64, error) {
		rs, err := r.Int(0)
		if err != nil {
			return 0, fmt.Errorf("error decoding getRoleMemberCount result: %w", err)
		}

		return rs.Uint64(), nil
	}),
}
View Source
var IsOperation = tvm.Getter[*big.Int, bool]{
	Name:    "isOperation",
	Decoder: BoolRes,
}
View Source
var IsOperationDone = tvm.Getter[*big.Int, bool]{
	Name:    "isOperationDone",
	Decoder: BoolRes,
}
View Source
var IsOperationError = tvm.Getter[*big.Int, bool]{
	Name:    "isOperationError",
	Decoder: BoolRes,
}
View Source
var IsOperationPending = tvm.Getter[*big.Int, bool]{
	Name:    "isOperationPending",
	Decoder: BoolRes,
}
View Source
var IsOperationReady = tvm.Getter[*big.Int, bool]{
	Name:    "isOperationReady",
	Decoder: BoolRes,
}
View Source
var ScheduleCallMinValue = tlb.MustFromTON("0.012")

Minimum value required for the schedule call (fails with Error.InsufficientValue)

Functions

This section is empty.

Types

type BlockFunctionSelector

type BlockFunctionSelector struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	// Function selector to block.
	Selector uint32 `tlb:"## 32"`
	// contains filtered or unexported fields
}

Blocks a function selector from being used, i.e. schedule operations with this function selector will revert.

Note that blocked selectors are only checked when an operation is being scheduled, not when it is executed. You may want to check any pending operations for whether they contain the blocked selector and cancel them.

Requirements:

- the caller must have the 'admin' role.

type BypasserCallExecuted

type BypasserCallExecuted struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	Index  uint64           `tlb:"## 64"` // Index of the call in the operation
	Target *address.Address `tlb:"addr"`  // Address of the target contract to call.
	Value  tlb.Coins        `tlb:"."`     // Value in TONs to send with the call.
	Data   *cell.Cell       `tlb:"^"`     // Data to send with the call - message body.
	// contains filtered or unexported fields
}

Emitted when a call is performed via bypasser.

type BypasserExecuteBatch

type BypasserExecuteBatch struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	// Array of calls to be scheduled
	Calls common.SnakedCell[Call] `tlb:"^"` // vec<Timelock_Call>
	// contains filtered or unexported fields
}

Directly execute a batch of transactions, bypassing any other checks.

Emits one {Timelock_BypasserCallExecuted} event per transaction in the batch.

Requirements:

- the caller must have the 'bypasser' or 'admin' role.

type Call

type Call struct {
	// Address of the target contract to call.
	Target *address.Address `tlb:"addr"`
	// Value in TONs to send with the call.
	Value tlb.Coins `tlb:"."`
	// Data to send with the call - message body.
	Data *cell.Cell `tlb:"^"`
}

Represents a single call

type CallExecuted

type CallExecuted struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	ID     *tlbe.Uint256    `tlb:"."`     // ID of the operation that was executed.
	Index  uint64           `tlb:"## 64"` // Index of the call in the operation
	Target *address.Address `tlb:"addr"`  // Address of the target contract to call.
	Value  tlb.Coins        `tlb:"."`     // Value in TONs to send with the call.
	Data   *cell.Cell       `tlb:"^"`     // Data to send with the call - message body.
	// contains filtered or unexported fields
}

Emitted when a call is performed as part of operation `id`.

type CallScheduled

type CallScheduled struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	ID          *tlbe.Uint256 `tlb:"."`     // ID of the operation that was scheduled.
	Index       uint64        `tlb:"## 64"` // Index of the call in the operation
	Call        Call          `tlb:"^"`     // Call to be executed as part of the operation.
	Predecessor *tlbe.Uint256 `tlb:"."`     // Predecessor operation ID
	Salt        *tlbe.Uint256 `tlb:"."`     // Salt used to derive the operation ID
	Delay       uint32        `tlb:"## 32"` // Delay in seconds before the operation can be executed
	// contains filtered or unexported fields
}

Emitted when a call is scheduled as part of operation `id`.

type Cancel

type Cancel struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	// ID of the operation to cancel.
	ID *tlbe.Uint256 `tlb:"."`
	// contains filtered or unexported fields
}

Cancel an operation.

Requirements:

- the caller must have the 'canceller' or 'admin' role.

type Cancelled

type Cancelled struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	ID *tlbe.Uint256 `tlb:"."` // ID of the operation that was cancelled.
	// contains filtered or unexported fields
}

Emitted when operation `id` is cancelled.

type Data

type Data struct {
	// ID allows multiple independent instances, since contract address depends on initial state.
	ID uint32 `tlb:"## 32"`

	// Minimum delay for operations in seconds
	MinDelay uint32 `tlb:"## 32"`
	// Map of operation id to timestamp
	Timestamps *tlbe.Dict[*tlbe.Uint256, uint64] `tlb:"."`

	// Number of fn selectors blocked by the contract.
	BlockedFnSelectorsLen uint32 `tlb:"## 32"`

	// Map of blocked function selectors.
	BlockedFnSelectors *tlbe.Dict[uint32, bool] `tlb:"."`

	// Flag to enable/disable the executor role check (if disabled, anyone can execute)
	ExecutorRoleCheckEnabled bool `tlb:"bool"`
	// Information about the currently pending operation.
	OpPendingInfo OpPendingInfo `tlb:"."`

	// AccessControl trait data
	RBAC rbac.Data `tlb:"^"`
}

RBACTimelock contract storage, auto-serialized to/from cell.

func EmptyDataFrom

func EmptyDataFrom(id uint32) Data

type ExecuteBatch

type ExecuteBatch struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	Calls       common.SnakedCell[Call] `tlb:"^"` // Array of calls to be scheduled // vec<Timelock_Call>
	Predecessor *tlbe.Uint256           `tlb:"."` // Predecessor operation ID
	Salt        *tlbe.Uint256           `tlb:"."` // Salt used to derive the operation ID
	// contains filtered or unexported fields
}

Execute an (ready) operation containing a batch of transactions.

Emits one {Timelock_CallExecuted} event per transaction in the batch.

Requirements:

- the caller must have the 'executor' or 'admin' role.

type ExecutorRoleCheckUpdated

type ExecutorRoleCheckUpdated struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	// Flag to enable/disable the executor role check (if disabled, anyone can execute)
	Enabled bool `tlb:"bool"`
	// contains filtered or unexported fields
}

Sent back to sender after the executor role check is updated.

type ExitCode

type ExitCode tvm.ExitCode
const (
	// Thrown when trying to schedule an operation which contains a blocked function selector.
	ErrorSelectorIsBlocked ExitCode = iota + 60600 // Facility ID * 100
	// Thrown when trying to execute an operation which is not ready yet.
	ErrorOperationNotReady
	// Thrown when an operation is missing a required dependency (predecessor not done).
	ErrorOperationMissingDependency
	// Thrown when trying to cancel a non-pending operation.
	ErrorOperationCannotBeCancelled
	// Thrown when trying to schedule an already scheduled operation.
	ErrorOperationAlreadyScheduled
	// Thrown when the provided delay is less than the minimum delay.
	ErrorInsufficientDelay
	// Thrown when trying to execute a pending operation while another pending operation is not yet final
	ErrorPendingOperationNotFinal
	// Thrown when the provided op.value is insufficient (min required value not met).
	ErrorInsufficientValue
	// Thrown when trying to submit an error report for an operation that is not done.
	ErrorOperationNotDone
	// Thrown when trying to initialize the contract more than once.
	ErrorContractAlreadyInitialized
	// Thrown when trying to call a function on an uninitialized contract.
	ErrorContractNotInitialized
	// Value attached to incoming message is not enough to pay for handler execution
	InsufficientFee
)

func (ExitCode) NewFrom

func (ExitCode) NewFrom(ec tvm.ExitCode) (ExitCode, error)

func (ExitCode) String

func (i ExitCode) String() string

type FunctionSelectorBlocked

type FunctionSelectorBlocked struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	// Function selector that was blocked.
	Selector uint32 `tlb:"## 32"`
	// contains filtered or unexported fields
}

Emitted when a function selector is blocked.

type FunctionSelectorUnblocked

type FunctionSelectorUnblocked struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	// Function selector that was unblocked.
	Selector uint32 `tlb:"## 32"`
	// contains filtered or unexported fields
}

Emitted when a function selector is unblocked.

type GetRoleMemberArgs

type GetRoleMemberArgs struct {
	Role  *big.Int
	Index uint64
}

type Init

type Init struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	// Minimum delay in seconds for future operations.
	MinDelay uint32 `tlb:"## 32"`

	// Address of the admin account.
	Admin *address.Address `tlb:"addr"`

	// Collection of addresses to be granted proposer, executor, canceller and bypasser roles.
	Proposers  common.SnakedCell[common.AddressWrap] `tlb:"^"`
	Executors  common.SnakedCell[common.AddressWrap] `tlb:"^"`
	Cancellers common.SnakedCell[common.AddressWrap] `tlb:"^"`
	Bypassers  common.SnakedCell[common.AddressWrap] `tlb:"^"`

	// Flag to enable/disable the executor role check (if disabled, anyone can execute)
	ExecutorRoleCheckEnabled bool `tlb:"bool"`
	// The timeout required to finalize the currently executing op
	OpFinalizationTimeout uint32 `tlb:"## 32"`
	// contains filtered or unexported fields
}

Initializes the contract with the following parameters:

- `minDelay`: initial minimum delay for operations - `admin`: account to be granted admin role - `proposers`: accounts to be granted proposer role - `executors`: accounts to be granted executor role - `cancellers`: accounts to be granted canceller role - `bypassers`: accounts to be granted bypasser role

type MinDelayChange

type MinDelayChange struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	OldDuration uint32 `tlb:"## 32"` // Duration of the old minimum delay in seconds.
	NewDuration uint32 `tlb:"## 32"` // Duration of the new minimum delay in seconds.
	// contains filtered or unexported fields
}

Emitted when the minimum delay for future operations is modified.

type OpFinalizationTimeoutChange

type OpFinalizationTimeoutChange struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	OldDuration uint32 `tlb:"## 32"` // Duration of the old timeout in seconds.
	NewDuration uint32 `tlb:"## 32"` // Duration of the new timeout in seconds.
	// contains filtered or unexported fields
}

Replied to sender when the op finalization timeout is modified.

type OpPendingInfo

type OpPendingInfo struct {
	// The time at which the scheduled ops becomes valid to execute [executionTime(opCount -
	// At this time the previous executed operation is considered optimistically final and successful,
	// meaning no bounce was received and we can continue executing.
	ValidAfter uint64 `tlb:"## 64"`
	// The timeout required to finalize the currently executing op
	OpFinalizationTimeout uint32 `tlb:"## 32"`
	// The id of the currently pending operation (OperationBatch hash)
	OpPendingID *tlbe.Uint256 `tlb:"."`
	// The ids (fingerprints) for calls awaiting finalization in the pending op (true = pending, false = finalized/bounced)
	OpPendingCalls *tlbe.Dict[*tlbe.Uint256, bool] `tlb:"."`
}

Information about the currently pending operation.

@dev TON-specific additional data required to support reliable execution in the async environment.

type OperationBatch

type OperationBatch struct {
	// Array of calls to be scheduled
	Calls common.SnakedCell[Call] `tlb:"^"` // vec<Timelock_Call>
	// Predecessor operation ID
	Predecessor *tlbe.Uint256 `tlb:"."`
	// Salt used to derive the operation ID
	Salt *tlbe.Uint256 `tlb:"."`
}

Batch of transactions represented as a operation, which can be scheduled and executed.

type Role

type Role = *big.Int

role identifier (keccak256 hash of the role name)

type ScheduleBatch

type ScheduleBatch struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	Calls       common.SnakedCell[Call] `tlb:"^"`     // Array of calls to be scheduled // vec<Timelock_Call>
	Predecessor *tlbe.Uint256           `tlb:"."`     // Predecessor operation ID
	Salt        *tlbe.Uint256           `tlb:"."`     // Salt used to derive the operation ID
	Delay       uint32                  `tlb:"## 32"` // Delay in seconds before the operation can be executed
	// contains filtered or unexported fields
}

Schedule an operation containing a batch of transactions.

Emits one {Timelock_CallScheduled} event per transaction in the batch.

Requirements:

- the caller must have the 'proposer' or 'admin' role. - all payloads must not start with a blocked function selector.

type SubmitErrorReport

type SubmitErrorReport struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	// The operation which produced the error (used to re-derive the op id).
	OpBatch OperationBatch `tlb:"^"`
	// The hash of the execute transaction.
	OpTxHash *tlbe.Uint256 `tlb:"."`

	// The hash of the transaction which errored (part of the tx trace).
	ErrorTxHash *tlbe.Uint256 `tlb:"."`
	// The error code.
	ErrorCode uint32 `tlb:"## 32"`
	// contains filtered or unexported fields
}

Submit an oracle error report, which marks an operation in error state.

The error report is used for a category of errors which might occur during execution of an operation, but can't be caught on-chain (OOG errors, and downstream tx-trace errors).

type Topic

type Topic = uint32

crc32 hash of the event name

type UnblockFunctionSelector

type UnblockFunctionSelector struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	// Function selector to unblock.
	Selector uint32 `tlb:"## 32"`
	// contains filtered or unexported fields
}

Unblocks a previously blocked function selector so it can be used again.

Requirements:

- the caller must have the 'admin' role.

type UpdateDelay

type UpdateDelay struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	// New minimum delay in seconds for future operations.
	NewDelay uint32 `tlb:"## 32"`
	// contains filtered or unexported fields
}

Changes the minimum timelock duration for future operations.

Emits a {Timelock_MinDelayChange} event.

Requirements:

- the caller must have the 'admin' role.

type UpdateExecutorRoleCheck

type UpdateExecutorRoleCheck struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	// Flag to enable/disable the executor role check (if disabled, anyone can execute)
	Enabled bool `tlb:"bool"`
	// contains filtered or unexported fields
}

Updates the executor role check (enabled/disabled) which guards the execution of operations.

Replies with {Timelock_ExecutorRoleCheckUpdated} message.

Requirements:

- the caller must have the 'admin' role.

type UpdateOpFinalizationTimeout

type UpdateOpFinalizationTimeout struct {

	// Query ID of the change request.
	QueryID uint64 `tlb:"## 64"`

	// The timeout required to finalize the currently executing op
	NewOpFinalizationTimeout uint32 `tlb:"## 32"`
	// contains filtered or unexported fields
}

Changes the timeout required to finalize the currently executing op

Replies with {Timelock_OpFinalizationTimeoutChange} message.

Requirements:

- the caller must have the 'admin' role.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL