-
Notifications
You must be signed in to change notification settings - Fork 3.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat(accounts): make x/accounts more depinject friendly #21928
Open
testinginprod
wants to merge
9
commits into
main
Choose a base branch
from
tip/accoutns/depinject
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+251
−82
Open
Changes from all commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
ed7087e
checkpoint
testinginprod 5a83dfc
checkpoint
testinginprod ee363f3
cleanups
testinginprod 61d874a
enhance docs
testinginprod c9e4a60
Merge branch 'main' into tip/accoutns/depinject
testinginprod ca7a5ed
cleanups
testinginprod 83698e0
micro fix
testinginprod bb25983
fix some tests, make things more consistent
testinginprod 4006313
lint
testinginprod File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,6 +1,95 @@ | ||
# x/accounts | ||
# x/accounts Module | ||
|
||
The x/accounts module provides module and facilities for writing smart cosmos-sdk accounts. | ||
The x/accounts module enhances the Cosmos SDK by providing tools and infrastructure for creating advanced smart accounts. | ||
|
||
# The Authentication Interface | ||
|
||
x/accounts introduces the `Authentication` interface, allowing for flexible transaction (TX) authentication beyond traditional public key cryptography. | ||
|
||
Chain developers can implement tailored authentication methods for their accounts. Any account that implements the `Authentication` interface can be authenticated within a transaction. | ||
|
||
To implement the `Authentication` interface in x/accounts, an account must expose an execution handler capable of processing a specific message type. | ||
|
||
The key message type for authentication is `MsgAuthenticate`, which is defined in the module's protocol buffer files: | ||
|
||
[interfaces/account_abstraction/v1/interface.proto](./proto/cosmos/accounts/interfaces/account_abstraction/v1/interface.proto) | ||
|
||
## Authentication Mechanism | ||
|
||
### AnteHandler in the SDK | ||
|
||
The Cosmos SDK utilizes an `AnteHandler` to verify transaction (TX) integrity. Its primary function is to ensure that the messages within a transaction are correctly signed by the purported sender. | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. nit (can be done during the doc week), let's mention tx validator (antehandler) to be future proof already |
||
### Authentication Flow for x/accounts Module | ||
|
||
When the `AnteHandler` identifies that a message sender (and transaction signer) belongs to the x/accounts module, it delegates the authentication process to that module. | ||
|
||
#### Authentication Interface Requirement | ||
|
||
For successful authentication, the account must implement the `Authentication` interface. If an account fails to implement this interface, it's considered non-externally owned, resulting in transaction rejection. | ||
|
||
##### Sequence Diagram | ||
|
||
```mermaid | ||
graph TD | ||
A[Tx Is Received] --> B[Execute Signature Verification Ante Handler] | ||
B --> D{Is signer an x/accounts account?} | ||
D -->|No| E[Continue with signature verification ante handler] | ||
D -->|Yes| F{Does account handle MsgAuthenticate?} | ||
F -->|No| G[Fail TX: Non-externally owned account] | ||
F -->|Yes| H[Invoke signer account MsgAuthenticate] | ||
E --> I[End] | ||
G --> I | ||
H --> I | ||
``` | ||
|
||
|
||
## Implementing the Authentication Interface | ||
|
||
To implement the Authentication interface, an account must handle the execution of `MsgAuthenticate`. Here's an example of how to do this: | ||
|
||
```go | ||
package base | ||
|
||
import ( | ||
"context" | ||
"errors" | ||
aa_interface_v1 "github.com/cosmos/cosmos-sdk/x/accounts/interfaces/account_abstraction/v1" | ||
"github.com/cosmos/cosmos-sdk/x/accounts/std" | ||
) | ||
|
||
// Account represents a base account structure | ||
type Account struct { | ||
// Account fields... | ||
} | ||
|
||
// Authenticate implements the authentication flow for an abstracted base account. | ||
func (a Account) Authenticate(ctx context.Context, msg *aa_interface_v1.MsgAuthenticate) (*aa_interface_v1.MsgAuthenticateResponse, error) { | ||
if !accountstd.SenderIsAccountsModule(ctx) { | ||
return nil, errors.New("unauthorized: only accounts module is allowed to call this") | ||
} | ||
// Implement your authentication logic here | ||
// ... | ||
return &aa_interface_v1.MsgAuthenticateResponse{}, nil | ||
} | ||
|
||
// RegisterExecuteHandlers registers the execution handlers for the account. | ||
func (a Account) RegisterExecuteHandlers(builder *accountstd.ExecuteBuilder) { | ||
accountstd.RegisterExecuteHandler(builder, a.SwapPubKey) // Other handlers | ||
accountstd.RegisterExecuteHandler(builder, a.Authenticate) // Implements the Authentication interface | ||
} | ||
``` | ||
|
||
### Key Implementation Points | ||
|
||
1. **Sender Verification**: Always verify that the sender is the x/accounts module. This prevents unauthorized accounts from triggering authentication. | ||
2. **Authentication Safety**: Ensure your authentication mechanism is secure: | ||
- Prevent replay attacks by making it impossible to reuse the same action with the same signature. | ||
|
||
|
||
#### Implementation example | ||
|
||
Please find an example [here](./defaults/base/account.go). | ||
|
||
# Supporting Custom Accounts in the x/auth gRPC Server | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,31 @@ | ||
package basedepinject | ||
|
||
import ( | ||
"cosmossdk.io/depinject" | ||
"cosmossdk.io/x/accounts/accountstd" | ||
"cosmossdk.io/x/accounts/defaults/base" | ||
"cosmossdk.io/x/tx/signing" | ||
) | ||
|
||
type Inputs struct { | ||
depinject.In | ||
|
||
SignHandlersMap *signing.HandlerMap | ||
Options []base.Option | ||
} | ||
|
||
func ProvideAccount(in Inputs) accountstd.DepinjectAccount { | ||
return accountstd.DepinjectAccount{MakeAccount: base.NewAccount("base", in.SignHandlersMap, in.Options...)} | ||
} | ||
|
||
func ProvideSecp256K1PubKey() base.Option { | ||
return base.WithSecp256K1PubKey() | ||
} | ||
|
||
func ProvideCustomPubkey[T any, PT base.PubKeyG[T]]() base.Option { | ||
return base.WithPubKey[T, PT]() | ||
} | ||
|
||
func ProvideCustomPubKeyAndValidationFunc[T any, PT base.PubKeyG[T]](validateFn func(PT) error) base.Option { | ||
return base.WithPubKeyWithValidationFunc(validateFn) | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,31 @@ | ||
package lockupdepinject | ||
|
||
import ( | ||
"cosmossdk.io/x/accounts/accountstd" | ||
"cosmossdk.io/x/accounts/defaults/lockup" | ||
) | ||
|
||
func ProvideAllLockupAccounts() []accountstd.DepinjectAccount { | ||
return []accountstd.DepinjectAccount{ | ||
ProvidePeriodicLockingAccount(), | ||
ProvideContinuousLockingAccount(), | ||
ProvidePermanentLockingAccount(), | ||
ProvideDelayedLockingAccount(), | ||
} | ||
} | ||
|
||
func ProvideContinuousLockingAccount() accountstd.DepinjectAccount { | ||
return accountstd.DIAccount(lockup.CONTINUOUS_LOCKING_ACCOUNT, lockup.NewContinuousLockingAccount) | ||
} | ||
|
||
func ProvidePeriodicLockingAccount() accountstd.DepinjectAccount { | ||
return accountstd.DIAccount(lockup.PERIODIC_LOCKING_ACCOUNT, lockup.NewPeriodicLockingAccount) | ||
} | ||
|
||
func ProvideDelayedLockingAccount() accountstd.DepinjectAccount { | ||
return accountstd.DIAccount(lockup.DELAYED_LOCKING_ACCOUNT, lockup.NewDelayedLockingAccount) | ||
} | ||
|
||
func ProvidePermanentLockingAccount() accountstd.DepinjectAccount { | ||
return accountstd.DIAccount(lockup.PERMANENT_LOCKING_ACCOUNT, lockup.NewPermanentLockingAccount) | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit (can be done during the doc week). We should use the
go reference
markdown code